Skip to content

Models

Starplot has models to represent 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:

  • Selecting objects to plot (via the where kwarg) (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())

starplot.Star

Star model.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

magnitude instance-attribute 

magnitude: float

Magnitude

bv class-attribute instance-attribute 

bv: Optional[float] = None

B-V Color Index, if available

hip class-attribute instance-attribute 

hip: Optional[int] = None

Hipparcos Catalog ID, if available

tyc class-attribute instance-attribute 

tyc: Optional[str] = None

Tycho ID, if available

ccdm class-attribute instance-attribute 

ccdm: Optional[str] = None

CCDM Component Identifier (if applicable)

name class-attribute instance-attribute 

name: Optional[str] = None

Name, if available

bayer class-attribute instance-attribute 

bayer: Optional[str] = None

Bayer designation, if available

flamsteed class-attribute instance-attribute 

flamsteed: Optional[int] = None

Flamsteed number, if available

geometry class-attribute instance-attribute 

geometry: ShapelyPoint = None

Shapely Point of the star's position. Right ascension coordinates are in degrees (0...360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

constellation 

constellation()

Returns an instance of the Constellation that contains this object

get 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 StarCatalog for 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 None if there are zero matches

find 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 StarCatalog for details

Returns:

  • list[Star] –

    List of Stars that match all where expressions

starplot.Constellation

Constellation model.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

iau_id class-attribute instance-attribute 

iau_id: str = None

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

name class-attribute instance-attribute 

name: str = None

Name of constellation

star_hip_ids class-attribute instance-attribute 

star_hip_ids: list[int] = None

List of HIP ids for stars that are part of the lines for this constellation.

boundary class-attribute instance-attribute 

boundary: ShapelyPolygon | ShapelyMultiPolygon = None

Shapely Polygon of the constellation's boundary. Right ascension coordinates are in degrees (0...360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

get 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

find 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 where expressions

constellation 

constellation()

Not applicable to Constellation model, raises NotImplementedError

starplot.DSO

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.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

name instance-attribute 

name: str

Name of the DSO (as specified in OpenNGC)

type instance-attribute 

type: DsoType

Type of DSO

magnitude class-attribute instance-attribute 

magnitude: Optional[float] = None

Magnitude (if available)

maj_ax class-attribute instance-attribute 

maj_ax: Optional[float] = None

Major axis of the DSO, in arcmin (if available)

min_ax class-attribute instance-attribute 

min_ax: Optional[float] = None

Minor axis of the DSO, in arcmin (if available)

angle class-attribute instance-attribute 

angle: Optional[float] = None

Angle of the DSO, in degrees (if available)

size class-attribute instance-attribute 

size: Optional[float] = None

Size of the DSO calculated as the area of the minimum bounding rectangle of the DSO, in degrees squared (if available)

m class-attribute instance-attribute 

m: Optional[str] = None

Messier number. Note that this field is a string, to be consistent with the other identifier fields (ngc and ic).

ngc class-attribute instance-attribute 

ngc: Optional[str] = None

New General Catalogue (NGC) identifier. Note that this field is a string, to support objects like '3537 NED01'.

ic class-attribute instance-attribute 

ic: Optional[str] = None

Index Catalogue (IC) identifier. Note that this field is a string, to support objects like '4974 NED01'.

geometry class-attribute instance-attribute 

geometry: ShapelyPolygon | ShapelyMultiPolygon = None

Shapely Polygon of the DSO's extent. Right ascension coordinates are in degrees (0...360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

constellation 

constellation()

Returns an instance of the Constellation that contains this object

get 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

find 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 where expressions

starplot.models.dso.DsoType

Type of deep sky object (DSO), as designated in OpenNGC

ASSOCIATION_OF_STARS class-attribute instance-attribute 

ASSOCIATION_OF_STARS = '*Ass'

Association of stars

DARK_NEBULA class-attribute instance-attribute 

DARK_NEBULA = 'DrkN'

Dark nebula

DOUBLE_STAR class-attribute instance-attribute 

DOUBLE_STAR = '**'

Double star or multiple star system

DUPLICATE_RECORD class-attribute instance-attribute 

DUPLICATE_RECORD = 'Dup'

Duplicate record of another object

EMISSION_NEBULA class-attribute instance-attribute 

EMISSION_NEBULA = 'EmN'

Emission Nebula

GALAXY class-attribute instance-attribute 

GALAXY = 'G'

Galaxy

GALAXY_PAIR class-attribute instance-attribute 

GALAXY_PAIR = 'GPair'

Group of two galaxies

GALAXY_TRIPLET class-attribute instance-attribute 

GALAXY_TRIPLET = 'GTrpl'

Group of three galaxies

GLOBULAR_CLUSTER class-attribute instance-attribute 

GLOBULAR_CLUSTER = 'GCl'

Globular cluster of stars

GROUP_OF_GALAXIES class-attribute instance-attribute 

GROUP_OF_GALAXIES = 'GGroup'

Group of more than three galaxies

HII_IONIZED_REGION class-attribute instance-attribute 

HII_IONIZED_REGION = 'HII'

Hydrogen ionized region

NEBULA class-attribute instance-attribute 

NEBULA = 'Neb'

Nebula

NONEXISTENT class-attribute instance-attribute 

NONEXISTENT = 'NonEx'

Non-existant object

NOVA_STAR class-attribute instance-attribute 

NOVA_STAR = 'Nova'

Nova star

OPEN_CLUSTER class-attribute instance-attribute 

OPEN_CLUSTER = 'OCl'

Open cluster of stars

PLANETARY_NEBULA class-attribute instance-attribute 

PLANETARY_NEBULA = 'PN'

Planetary nebula

REFLECTION_NEBULA class-attribute instance-attribute 

REFLECTION_NEBULA = 'RfN'

Reflection nebula

STAR class-attribute instance-attribute 

STAR = '*'

Star

STAR_CLUSTER_NEBULA class-attribute instance-attribute 

STAR_CLUSTER_NEBULA = 'Cl+N'

Star cluster with nebulosity

SUPERNOVA_REMNANT class-attribute instance-attribute 

SUPERNOVA_REMNANT = 'SNR'

Supernova remnant

UNKNOWN class-attribute instance-attribute 

UNKNOWN = 'Other'

Unknown type of object

starplot.Planet

Planet model.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

name instance-attribute 

name: str

Name of the planet:

  • Mercury
  • Venus
  • Mars
  • Jupiter
  • Saturn
  • Uranus
  • Neptune
  • Pluto

dt instance-attribute 

dt: datetime

Date/time of planet's position

apparent_size instance-attribute 

apparent_size: float

Apparent size (degrees)

geometry class-attribute instance-attribute 

geometry: ShapelyPolygon = None

Shapely Polygon of the planet's extent. Right ascension coordinates are in degrees (0...360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

constellation 

constellation()

Returns an instance of the Constellation that contains this object

all 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)

get 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.name for 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)

starplot.Sun

Sun model.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

name class-attribute instance-attribute 

name: str = 'Sun'

Name of the Sun

dt instance-attribute 

dt: datetime

Date/time of Sun's position

apparent_size instance-attribute 

apparent_size: float

Apparent size (degrees)

geometry class-attribute instance-attribute 

geometry: ShapelyPolygon = None

Shapely Polygon of the Sun's extent. Right ascension coordinates are in degrees (0...360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

constellation 

constellation()

Returns an instance of the Constellation that contains this object

get 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)

starplot.Moon

Moon model. Only used for Earth's moon right now, but will potentially represent other planets' moons in future versions.

ra instance-attribute 

ra: float

Right Ascension, in degrees (0 to 360)

dec instance-attribute 

dec: float

Declination, in degrees (-90 to 90)

constellation_id property 

constellation_id: str | None

Identifier of the constellation that contains this object. The ID is the three-letter (all lowercase) abbreviation from the International Astronomical Union (IAU).

name class-attribute instance-attribute 

name: str = 'Moon'

Name of the moon

dt instance-attribute 

dt: datetime

Date/time of moon's position

apparent_size instance-attribute 

apparent_size: float

Apparent size in the sky (degrees)

phase_angle instance-attribute 

phase_angle: float

Angle of the moon from the Sun (degrees)

phase_description instance-attribute 

phase_description: str

Description of the moon's phase. The Moon will be considered New/Full/Quarter if it's within 12 hours of that precise phase.

illumination instance-attribute 

illumination: float

Percent of illumination (0 to 1)

geometry class-attribute instance-attribute 

geometry: ShapelyPolygon = None

Shapely Polygon of the moon's extent. Right ascension coordinates are in degrees (0 to 360).

create_optic 

create_optic(*args, **kwargs)

Creates an optic plot with this object at the center

Parameters:

Returns:

create_map 

create_map(height_degrees: float, width_degrees: float, *args, **kwargs)

Creates a map plot with this object at the center

Parameters:

  • height_degrees (float) –

    Height of the map (degrees)

  • width_degrees (float) –

    Width of the map (degrees)

  • *args –

    args passed through to MapPlot()

  • **kwargs –

    kwargs passed through to MapPlot()

Returns:

  • MapPlot –

    new instance of a MapPlot

constellation 

constellation()

Returns an instance of the Constellation that contains this object

get 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)

starplot.ObjectList

Lists of objects that have been plotted. An instance of this model is returned by a plot's objects property.

stars class-attribute instance-attribute 

stars: list[Star] = []

Stars

constellations class-attribute instance-attribute 

constellations: list[Constellation] = []

Constellations

dsos class-attribute instance-attribute 

dsos: list[DSO] = []

Deep Sky Objects (DSOs)

planets class-attribute instance-attribute 

planets: list[Planet] = []

Planets

moon class-attribute instance-attribute 

moon: Moon = None

Moon

sun class-attribute instance-attribute 

sun: Sun = None

Sun