Models
Starplot has models to represent an observer and some of the objects you can plot, including stars, DSOs, planets, the Sun, and the Moon. These models are used for many things in Starplot:
- Defining an observing time and location
- Selecting objects to plot (via the
wherekwarg) (see docs) - Creating callables to calculate size/color/alpha values (see docs)
- Keeping track of plotted objects (via
ObjectList) - Getting the position of an object at a specific time (via
get()) - Getting a list of objects that meet a series of conditions (via
find())
Represents an observer at a specific time and place.
Example:
obs = Observer(
dt=datetime(2025, 10, 13, 21, 0, 0, tzinfo=ZoneInfo('US/Pacific')),
lat=33.363484,
lon=-116.836394,
)
class-attribute
instance-attribute
Date and time of observation (must be timezone-aware).
Defaults to current time in UTC.
class-attribute
instance-attribute
Latitude of observer location
class-attribute
instance-attribute
Longitude of observer location
Sky Objects
Star model.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
CCDM Component Identifier (if applicable)
class-attribute
instance-attribute
Bayer designation, if available
class-attribute
instance-attribute
Flamsteed number, if available
class-attribute
instance-attribute
Shapely Point of the star's position. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
get(
catalog: StarCatalog = BIG_SKY_MAG11, sql: str = None, **kwargs
) -> Union[Star, None]
Get a Star, by matching its attributes as specified in **kwargs
Example:
sirius = Star.get(name="Sirius")
Parameters:
-
catalog(StarCatalog, default:BIG_SKY_MAG11) –The catalog of stars to use: "big-sky-mag11", or "big-sky" -- see
StarCatalogfor details -
sql(str, default:None) –SQL query for selecting star (table name is "_")
-
**kwargs–Attributes on the star you want to match
Raises: ValueError if more than one star is matched
Returns:
-
Union[Star, None]–Star instance if there's exactly one match or
Noneif there are zero matches
classmethod
find(
where: list = None, sql: str = None, catalog: StarCatalog = BIG_SKY_MAG11
) -> list[Star]
Find Stars
Parameters:
-
where(list, default:None) –A list of expressions that determine which stars to find. See Selecting Objects for details.
-
sql(str, default:None) –SQL query for selecting stars (table name is "_")
-
catalog(StarCatalog, default:BIG_SKY_MAG11) –The catalog of stars to use: "big-sky-mag11", or "big-sky" -- see
StarCatalogfor details
Returns:
-
list[Star]–List of Stars that match all
whereexpressions
Constellation model.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
International Astronomical Union (IAU) three-letter designation, all lowercase.
Important: Starplot treats Serpens as two separate constellations to make them easier to work with programatically.
Serpens Caput has the iau_id of ser1 and Serpens Cauda is ser2
class-attribute
instance-attribute
List of HIP ids for stars that are part of the lines for this constellation.
class-attribute
instance-attribute
Shapely Polygon of the constellation's boundary. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
get(sql: str = None, **kwargs) -> Constellation
Get a Constellation, by matching its attributes.
Example:
hercules = Constellation.get(name="Hercules")
Parameters:
-
sql(str, default:None) –SQL query for selecting constellation (table name is "_")
-
**kwargs–Attributes on the constellation you want to match
Raises: ValueError if more than one constellation is matched
classmethod
find(where: list = None, sql: str = None) -> list[Constellation]
Find Constellations
Parameters:
-
where(list, default:None) –A list of expressions that determine which constellations to find. See Selecting Objects for details.
-
sql(str, default:None) –SQL query for selecting constellations (table name is "_")
Returns:
-
list[Constellation]–List of Constellations that match all
whereexpressions
Deep Sky Object (DSO) model. An instance of this model is passed to any callables you define when plotting DSOs. So, you can use any attributes of this model in your callables. Note that some may be null.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
List of common names for the DSO (e.g. 'Andromeda Galaxy' for M31)
Note: this field is parsed into a list of strings after querying DSOs, so if you want to query on this field, you should treat it as a comma-separated list.
class-attribute
instance-attribute
Magnitude (if available)
class-attribute
instance-attribute
Major axis of the DSO, in arcmin (if available)
class-attribute
instance-attribute
Minor axis of the DSO, in arcmin (if available)
class-attribute
instance-attribute
Angle of the DSO, in degrees (if available)
class-attribute
instance-attribute
Size of the DSO calculated as the area of the minimum bounding rectangle of the DSO, in degrees squared (if available)
class-attribute
instance-attribute
Messier number. Note that this field is a string, to be consistent with the other identifier fields (ngc and ic).
class-attribute
instance-attribute
New General Catalogue (NGC) identifier. Note that this field is a string, to support objects like '3537 NED01'.
class-attribute
instance-attribute
Index Catalogue (IC) identifier. Note that this field is a string, to support objects like '4974 NED01'.
class-attribute
instance-attribute
Shapely Polygon of the DSO's extent. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
get(sql: str = None, **kwargs) -> DSO
Get a DSO, by matching its attributes.
Example:
d = DSO.get(m=13)
Parameters:
-
sql(str, default:None) –SQL query for selecting DSO (table name is "_")
-
**kwargs–Attributes on the DSO you want to match
Raises: ValueError if more than one DSO is matched
classmethod
find(where: list = None, sql: str = None) -> list[DSO]
Find DSOs
Parameters:
-
where(list, default:None) –A list of expressions that determine which DSOs to find. See Selecting Objects for details.
-
sql(str, default:None) –SQL query for selecting DSOs (table name is "_")
Returns:
-
list[DSO]–List of DSOs that match all
whereexpressions
Type of deep sky object (DSO), as designated in OpenNGC
class-attribute
instance-attribute
Association of stars
class-attribute
instance-attribute
Double star or multiple star system
class-attribute
instance-attribute
Duplicate record of another object
class-attribute
instance-attribute
Globular cluster of stars
class-attribute
instance-attribute
Group of more than three galaxies
class-attribute
instance-attribute
Hydrogen ionized region
class-attribute
instance-attribute
Star cluster with nebulosity
Planet model.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
instance-attribute
Name of the planet:
- Mercury
- Venus
- Mars
- Jupiter
- Saturn
- Uranus
- Neptune
- Pluto
class-attribute
instance-attribute
Shapely Polygon of the planet's extent. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
all(
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Iterator[Planet]
Iterator for getting all planets at a specific date/time and observing location.
Parameters:
-
dt(datetime, default:None) –Datetime you want the planets for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the planet's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)
classmethod
get(
name: str,
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Planet
Get a planet for a specific date/time.
Parameters:
-
name(str) –Name of the planet you want to get (see
Planet.namefor options). Case insensitive. -
dt(datetime, default:None) –Datetime you want the planet for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the planet's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)
Sun model.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
Shapely Polygon of the Sun's extent. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
get(
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Sun
Get the Sun for a specific date/time and observing location.
Parameters:
-
dt(datetime, default:None) –Datetime you want the Sun for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the Sun's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating Sun/moon/planet positions (see Skyfield's documentation for details)
Moon model. Only used for Earth's moon right now, but will potentially represent other planets' moons in future versions.
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
instance-attribute
Description of the moon's phase. The Moon will be considered New/Full/Quarter if it's within 12 hours of that precise phase.
class-attribute
instance-attribute
Shapely Polygon of the moon's extent. Right ascension coordinates are in degrees (0 to 360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
get(
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Moon
Get the Moon for a specific date/time and observing location.
Parameters:
-
dt(datetime, default:None) –Datetime you want the moon for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the Moon's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating moon positions (see Skyfield's documentation for details)
Comets can be created in three ways:
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
Distance to comet, in Astronomical units (the Earth-Sun distance of 149,597,870,700 m)
class-attribute
instance-attribute
Ephemeris used when retrieving this instance
class-attribute
instance-attribute
Shapely Point of the comet's position. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
from_json(
data: dict,
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Comet
Get a comet for a specific date/time/location from an IAU MPC JSON.
Parameters:
-
data(dict) –Dictionary of the IAU MPC JSON
-
dt(datetime, default:None) –Datetime you want the comet for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the comet's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating comet positions (see Skyfield's documentation for details)
classmethod
all(
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
reload: bool = False,
) -> Iterator[Comet]
Iterator for getting all comets at a specific date/time and observing location.
Parameters:
-
dt(datetime, default:None) –Datetime you want the comets for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the comet's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating comet positions (see Skyfield's documentation for details)
-
reload(bool, default:False) –If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available.
classmethod
get(
name: str,
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
reload: bool = False,
) -> Comet
Get a comet for a specific date/time.
Parameters:
-
name(str) –Name of the comet you want to get (as designated by IAU Minor Planet Center)
-
dt(datetime, default:None) –Datetime you want the comet for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the comet's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating comet positions (see Skyfield's documentation for details)
-
reload(bool, default:False) –If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available.
trajectory(
date_start: datetime, date_end: datetime, step: timedelta = None
) -> Iterator[Comet]
Iterator for getting a trajectory of the comet.
Parameters:
-
date_start(datetime) –Starting date/time for the trajectory (inclusive)
-
date_end(datetime) –End date/time for the trajectory (exclusive)
-
step(timedelta, default:None) –Time-step for the trajectory. Defaults to 1-day
Returns:
-
Iterator[Comet]–Iterator that yields a Comet instance at each step in the date range
Satellites can be created in two ways:
property
Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).
class-attribute
instance-attribute
Distance to satellite, in Astronomical units (the Earth-Sun distance of 149,597,870,700 m)
class-attribute
instance-attribute
Ephemeris used when retrieving this instance
class-attribute
instance-attribute
Shapely Point of the satellite's position. Right ascension coordinates are in degrees (0...360).
Creates an optic plot with this object at the center
Parameters:
-
*args–args passed through to
OpticPlot() -
**kwargs–kwargs passed through to
OpticPlot()
Returns:
-
OpticPlot–new instance of a
OpticPlot
classmethod
from_json(
data: dict,
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Satellite
Get a satellite for a specific date/time/location from a CelesTrak JSON.
Parameters:
-
data(dict) –Dictionary of the CelesTrak JSON
-
dt(datetime, default:None) –Datetime you want the satellite for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the satellite's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating satellite positions (see Skyfield's documentation for details)
classmethod
from_tle(
name: str,
line1: str,
line2: str,
dt: datetime = None,
lat: float = None,
lon: float = None,
ephemeris: str = "de421_2001.bsp",
) -> Satellite
Get a satellite for a specific date/time/location from a two-line element set (TLE).
Parameters:
-
name(str) –Name of the satellite
-
line1(str) –Line 1 of the two-line element set (TLE)
-
line2(str) –Line 2 of the two-line element set (TLE)
-
dt(datetime, default:None) –Datetime you want the satellite for (must be timezone aware!). Defaults to current UTC time.
-
lat(float, default:None) –Latitude of observing location. If you set this (and longitude), then the satellite's apparent RA/DEC will be calculated.
-
lon(float, default:None) –Longitude of observing location
-
ephemeris(str, default:'de421_2001.bsp') –Ephemeris to use for calculating satellite positions (see Skyfield's documentation for details)
trajectory(
date_start: datetime, date_end: datetime, step: timedelta = None
) -> Iterator[Satellite]
Iterator for getting a trajectory of the satellite.
Parameters:
-
date_start(datetime) –Starting date/time for the trajectory (inclusive)
-
date_end(datetime) –End date/time for the trajectory (exclusive)
-
step(timedelta, default:None) –Time-step for the trajectory. Defaults to 1-day
Returns:
-
Iterator[Satellite]–Iterator that yields a Satellite instance at each step in the date range
Lists of objects that have been plotted. An instance of this model is returned by a plot's objects property.
class-attribute
instance-attribute
constellations: list[Constellation] = []
Constellations
Optics
Abstract class for defining Optics.
Creates a new Binoculars optic
Parameters:
-
magnification–Magnification of the binoculars
-
fov–Apparent field of view (FOV) of the binoculars in degrees. This isn't always easy to find for binoculars, so if you can't find it in your binocular's specs, then try using
60.
Returns:
-
Binoculars–A new instance of a Binoculars optic
Creates a new generic Scope optic.
Use this class to create custom scope optics or use it as a generic optic that does NOT apply any transforms to the view.
See subclasses of this optic for more specific use cases:
-
Refractor- automatically inverts the view (i.e. assumes a star diagonal is used) -
Reflector- automatically rotates the view so it's upside-down
Parameters:
-
focal_length–Focal length (mm) of the telescope
-
eyepiece_focal_length–Focal length (mm) of the eyepiece
-
eyepiece_fov–Field of view (degrees) of the eyepiece
Returns:
-
Scope–A new instance of a Scope optic
instance-attribute
Focal length (mm) of the eyepiece
property
Magnification calculated from the telescope's focal length and eyepiece focal length
Creates a new Refractor Telescope optic
Warning
This optic assumes a star diagonal is used, so it applies a transform that inverts the image.
If you don't want this transform applied, then use the generic Scope optic instead.
Parameters:
-
focal_length–Focal length (mm) of the telescope
-
eyepiece_focal_length–Focal length (mm) of the eyepiece
-
eyepiece_fov–Field of view (degrees) of the eyepiece
Returns:
-
Refractor–A new instance of a Refractor optic
instance-attribute
Focal length (mm) of the eyepiece
property
Magnification calculated from the telescope's focal length and eyepiece focal length
Creates a new Reflector Telescope optic
Warning
This optic applies a transform that produces an "upside-down" image.
If you don't want this transform applied, then use the generic Scope optic instead.
Parameters:
-
focal_length–Focal length (mm) of the telescope
-
eyepiece_focal_length–Focal length (mm) of the eyepiece
-
eyepiece_fov–Field of view (degrees) of the eyepiece
Returns:
-
Reflector–A new instance of a Reflector optic
instance-attribute
Focal length (mm) of the eyepiece
property
Magnification calculated from the telescope's focal length and eyepiece focal length
Creates a new Camera optic
Note
Field of view for each dimension is calculated using the following formula:
Where:
d = sensor size (height or width)
f = focal length of lens
Parameters:
-
sensor_height–Height of camera sensor (mm)
-
sensor_width–Width of camera sensor (mm)
-
lens_focal_length–Focal length of camera lens (mm)
-
rotation–Angle (degrees) to rotate camera, defaults to 0
Returns:
-
Camera–A new instance of a Camera optic
instance-attribute
Focal length (mm) of the camera's lens
class-attribute
instance-attribute
Angle (degrees) to rotate the camera