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 = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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

Magnitude

bv class-attribute instance-attribute 

bv: Optional[float] = bv

B-V Color Index, if available

hip class-attribute instance-attribute 

hip: Optional[int] = hip if hip is not None and isfinite(hip) else None

Hipparcos Catalog ID, if available

tyc class-attribute instance-attribute 

tyc: Optional[str] = tyc

Tycho ID, if available

ccdm class-attribute instance-attribute 

ccdm: Optional[str] = ccdm

CCDM Component Identifier (if applicable)

name class-attribute instance-attribute 

name: Optional[str] = name

Name, if available

geometry class-attribute instance-attribute 

geometry: Point = Point([ra, dec])

Shapely Point of the star's position. Right ascension coordinates are in 24H format.

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(**kwargs) -> Star

Get a Star, by matching its attributes.

Example: sirius = Star.get(name="Sirius")

Parameters:

  • **kwargs –

    Attributes on the star you want to match

Raises: ValueError if more than one star is matched

find classmethod 

find(where: list) -> list[Star]

Find Stars

Parameters:

  • where (list) –

    A list of expressions that determine which stars to find. See Selecting Objects for details.

Returns:

  • list[Star] –

    List of Stars that match all where expressions

starplot.Constellation

Constellation model.

ra instance-attribute 

ra: float = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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 = lower()

International Astronomical Union (IAU) three-letter designation, all lowercase

name class-attribute instance-attribute 

name: str = name

Name

boundary class-attribute instance-attribute 

boundary: Polygon = boundary

Shapely Polygon of the constellation's boundary. Right ascension coordinates are in 24H format.

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(**kwargs) -> Constellation

Get a Constellation, by matching its attributes.

Example: hercules = Constellation.get(name="Hercules")

Parameters:

  • **kwargs –

    Attributes on the constellation you want to match

Raises: ValueError if more than one constellation is matched

find classmethod 

find(where: list) -> list[Constellation]

Find Constellations

Parameters:

  • where (list) –

    A list of expressions that determine which constellations to find. See Selecting Objects for details.

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 = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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

Name of the DSO (as specified in OpenNGC)

magnitude class-attribute instance-attribute 

magnitude: Optional[float] = magnitude

Magnitude (if available)

maj_ax class-attribute instance-attribute 

maj_ax: Optional[float] = maj_ax

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

min_ax class-attribute instance-attribute 

min_ax: Optional[float] = min_ax

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

angle class-attribute instance-attribute 

angle: Optional[float] = angle

Angle of the DSO, in degrees (if available)

size class-attribute instance-attribute 

size: Optional[float] = size

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] = m

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] = ngc

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] = ic

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

geometry class-attribute instance-attribute 

geometry: Union[Polygon, MultiPolygon] = geometry

Shapely Polygon of the DSO's extent. Right ascension coordinates are in 24H format.

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(**kwargs) -> DSO

Get a DSO, by matching its attributes.

Example: d = DSO.get(m=13)

Parameters:

  • **kwargs –

    Attributes on the DSO you want to match

Raises: ValueError if more than one DSO is matched

find classmethod 

find(where: list) -> list[DSO]

Find DSOs

Parameters:

  • where (list) –

    A list of expressions that determine which DSOs to find. See Selecting Objects for details.

Returns:

  • list[DSO] –

    List of DSOs that match all where expressions

starplot.Planet

Planet model.

ra instance-attribute 

ra: float = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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

Name of the planet:

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

dt instance-attribute 

dt: datetime = dt

Date/time of planet's position

apparent_size instance-attribute 

apparent_size: float = apparent_size

Apparent size (degrees)

geometry class-attribute instance-attribute 

geometry: Polygon = geometry

Shapely Polygon of the planet's extent. Right ascension coordinates are in 24H format.

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 = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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 = name

Name of the Sun

dt instance-attribute 

dt: datetime = dt

Date/time of Sun's position

apparent_size instance-attribute 

apparent_size: float = apparent_size

Apparent size (degrees)

geometry class-attribute instance-attribute 

geometry: Polygon = geometry

Shapely Polygon of the Sun's extent. Right ascension coordinates are in 24H format.

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 = ra

Right Ascension, in hours (0...24)

dec instance-attribute 

dec: float = dec

Declination, in degrees (-90...90)

constellation_id class-attribute instance-attribute 

constellation_id: Optional[str] = lower()

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 = name

Name of the moon

dt instance-attribute 

dt: datetime = dt

Date/time of moon's position

apparent_size instance-attribute 

apparent_size: float = apparent_size

Apparent size (degrees)

phase_angle instance-attribute 

phase_angle: float = phase_angle

Angle of the moon from the Sun (degrees)

phase_description instance-attribute 

phase_description: str = phase_description

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 = illumination

Percent of illumination (0...1)

geometry class-attribute instance-attribute 

geometry: Polygon = geometry

Shapely Polygon of the moon's extent. Right ascension coordinates are in 24H format.

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