Starplot

https://starplot.dev
Admin
Starplot is a Python library for creating star charts, maps, zenith charts, horizon charts, and...
Tokens:187,992
Snippets:2,023
Trust Score:6.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Constellation Example

Source: https://starplot.dev/reference-models/index.html

Example demonstrating how to retrieve a Constellation object using its name.

```python
hercules = Constellation.get(name="Hercules")
```

--------------------------------

### Install Shapely from source

Source: https://starplot.dev/installation

If encountering segmentation faults, install Shapely from source. This may take several minutes.

```bash
pip install --no-binary :all: shapely

```

--------------------------------

### Comprehensive Object Plotting Example

Source: https://starplot.dev/tutorial/06

This example demonstrates extensive use of the 'where' kwarg to plot various celestial objects with specific filters and styling. It includes setup for MapPlot, plotting constellations, stars (bright and dim), nebulae, open clusters, globular clusters, and background elements like the ecliptic and Milky Way.

```python
from starplot import MapPlot, Miller, callables, _
from starplot.styles import PlotStyle, extensions

style = PlotStyle().extend(
    extensions.BLUE_NIGHT,
    extensions.MAP,
)
p = MapPlot(
    projection=Miller(),
    ra_min=15 * 15,
    ra_max=20 * 15,
    dec_min=-45.2,
    dec_max=-3,
    style=style,
    resolution=3600,
    scale=0.8,
)
p.constellations()
p.constellation_borders()

p.stars(
    # select the brightest stars:
    where=[_.magnitude <= 3],
    # here we make the stars 2x bigger by passing in a custom size function (i.e. a callable)
    # you'll learn more about this later in the tutorial...
    size_fn=lambda d: callables.size_by_magnitude(d) * 2,
    # use an 8-pointed star for bright star markers:
    style__marker__symbol="star_8",
    style__label__offset_x=8,
    style__label__offset_y=-8,
    style__label__border_width=2,
)
p.stars(
    where=[
        _.magnitude > 3,  # select the dimmer stars
        _.magnitude < 8,
    ],
    bayer_labels=True,
)

p.nebula(
    # select nebulae which have no defined magnitude or less than 7
    where=[_.magnitude.isnull() | (_.magnitude < 7)],
    where_true_size=[_.size > 1],  # only plot large nebula as their true size
)
p.open_clusters(
    where=[_.magnitude.isnull() | (_.magnitude < 7)],
    where_true_size=[False],
)
p.globular_clusters(
    where=[_.magnitude.isnull() | (_.magnitude < 7)],
    where_true_size=[False],
)

p.ecliptic()
p.milky_way()
p.constellation_labels()

p.export("tutorial_06.png", padding=0.08)

```

--------------------------------

### Install Starplot using pip

Source: https://starplot.dev/installation

Use this command to install Starplot from the Python Package Index.

```bash
pip install starplot

```

--------------------------------

### Using Built-in Callables

Source: https://starplot.dev/reference-callables/index.html

Example demonstrating how to use the `color_by_bv` callable to color stars based on their B-V index.

```APIDOC
## Using Built-in Callables

This example shows how to use the `color_by_bv` callable to color stars based on their B-V index.

### Code Example
```python
from starplot import MapPlot, Mercator, callables, _
from starplot.styles import PlotStyle, extensions

style = PlotStyle().extend(
    extensions.GRAYSCALE_DARK,
    extensions.MAP,
)

p = MapPlot(
    projection=Mercator(),
    ra_min=3.4,
    ra_max=8,
    dec_min=-16,
    dec_max=25.6,
    style=style,
)

p.stars(
    where=[_.magnitude < 12],
    color_fn=callables.color_by_bv, 
)

p.constellations()

p.export("orion_colored_stars.png")
```
```

--------------------------------

### Hive Partitioning Example

Source: https://starplot.dev/data/building/index.html

Illustrates how Hive partitioning organizes data into folders based on a specific field, such as 'constellation_id', to speed up queries.

```bash
stars/
    constellation_id=and/
    constellation_id=cma/
    constellation_id=uma/
    ...
```

--------------------------------

### Install Starplot using Conda

Source: https://starplot.dev/installation

Use this command to install Starplot from the conda-forge channel.

```bash
conda install conda-forge::starplot

```

--------------------------------

### Setup Starplot (Optional)

Source: https://starplot.dev/installation

Run this command to pre-install spatial extensions, build the font cache, and download data catalogs. This is useful for deployed environments or CI.

```bash
starplot setup

```

--------------------------------

### Star.all

Source: https://starplot.dev/reference-models

Get all stars from a catalog.

```APIDOC
## Star.all

Get all stars from a catalog.

### Parameters
* `catalog` (Catalog, default: `BIG_SKY_MAG11` ) – 
Catalog you want to get star objects from

### Returns
* `Iterator[Star]` – 
Iterator of Star instances
```

--------------------------------

### Get DSO by Attributes Class Method

Source: https://starplot.dev/reference-models

Fetches a single DSO by matching its attributes or using a SQL query. Raises `ValueError` if multiple DSOs match.

```python
get(catalog: Catalog = OPEN_NGC, sql: str = None, **kwargs) -> DSO


```

```python
d = DSO.get(m=13)


```

--------------------------------

### Get All Planets

Source: https://starplot.dev/reference-models/index.html

Iterates through all planets for a given observation time and location. Requires an Observer instance and optionally an ephemeris file.

```python
all(
    observer: Observer = None, ephemeris: str = "de421.bsp"
) -> Iterator[Planet]
```

--------------------------------

### get (Planet)

Source: https://starplot.dev/reference-models

Retrieves a specific planet by name for a given time and observer location, using a specified ephemeris file.

```APIDOC
## get `classmethod`

### Description
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.
* **`observer`** (`Observer`, default: `None`) - Observer instance that specifies a time and location
* **`ephemeris`** (`str`, default: `'de421.bsp'`) - Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)

### Returns
* **`Planet`**
```

--------------------------------

### Get Sun Instance

Source: https://starplot.dev/reference-models/index.html

Retrieves the Sun object for a specific date/time and observing location. Requires an Observer instance and optionally an ephemeris file.

```python
get(observer: Observer = None, ephemeris: str = 'de421.bsp') -> Sun
```

--------------------------------

### Get Single Star by Attributes

Source: https://starplot.dev/reference-models

Retrieves a single star by matching its attributes. Returns the first match sorted by CCDM, or None if no match is found. Example: `sirius = Star.get(name="Sirius")`

```python
get(
    catalog: Catalog = BIG_SKY_MAG11, sql: str = None, **kwargs
) -> Union[Star, None]
```

--------------------------------

### Settings Initialization

Source: https://starplot.dev/reference-settings/index.html

Shows the signature for initializing the Settings object.

```APIDOC
### `` __init__
```python
__init__(
    data_path: Path = _get_path("STARPLOT_DATA_PATH", cwd())(),
    svg_text_type: SvgTextType = (
        lambda: get("STARPLOT_SVG_TEXT_TYPE", PATH)
    )(),
    language: str = (lambda: get("STARPLOT_LANGUAGE", "en-US"))(),
    debug: bool = _get_boolean("STARPLOT_DEBUG", False)(),
) -> None
```
```

--------------------------------

### Get Matplotlib Font Weight String

Source: https://starplot.dev/reference-styling

Use this method to get the font weight as a matplotlib string. This is necessary to avoid a bug when rendering text elements in SVG with integer font weights.

```python
as_matplot() -> str
```

--------------------------------

### Initialize HorizonPlot

Source: https://starplot.dev/reference-horizonplot

Creates a new HorizonPlot instance. Configure altitude, azimuth, observer, ephemeris, style, resolution, collision handlers, and scaling. Warnings can be suppressed.

```python
HorizonPlot(
    altitude: tuple[float, float],
    azimuth: tuple[float, float],
    observer: Observer = None,
    ephemeris: str = "de421.bsp",
    style: PlotStyle = None,
    resolution: int = 4096,
    point_label_handler: CollisionHandler = None,
    area_label_handler: CollisionHandler = None,
    path_label_handler: CollisionHandler = None,
    scale: float = 1.0,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs
)

```

--------------------------------

### Create Basic Star Chart

Source: https://starplot.dev/examples/star-chart-basic/index.html

Use this snippet to generate a star chart for a specific date, time, and geographical location. It sets up the observer, applies a style, and exports the chart as a PNG.

```python
from datetime import datetime
from zoneinfo import ZoneInfo

from starplot import ZenithPlot, Observer, _
from starplot.styles import PlotStyle, extensions

tz = ZoneInfo("America/Los_Angeles")
dt = datetime(2023, 7, 13, 22, 0, tzinfo=tz)  # July 13, 2023 at 10pm PT

observer = Observer(
    dt=dt,
    lat=33.363484,
    lon=-116.836394,
)

p = ZenithPlot(
    observer=observer,
    style=PlotStyle().extend(
        extensions.BLUE_MEDIUM,
    ),
    resolution=3600,
    autoscale=True,
)
p.horizon()
p.constellations()
p.stars(where=[_.magnitude < 4.6], where_labels=[_.magnitude < 2.4])
p.constellation_labels()

p.export("star_chart_basic.png", transparent=True, padding=0.1)

```

--------------------------------

### Comet.trajectory

Source: https://starplot.dev/reference-models/index.html

Iterator for getting a trajectory of the comet.

```APIDOC
## Comet.trajectory

### Description
Iterator for getting a trajectory of the comet.

### Method
`trajectory(date_start: datetime, date_end: datetime, step: timedelta = None) -> Iterator[Comet]`

### Parameters
#### Query Parameters
- **date_start** (datetime) - Starting date/time for the trajectory (inclusive)
- **date_end** (datetime) - End date/time for the trajectory (exclusive)
- **step** (timedelta, Optional) - Time-step for the trajectory. Defaults to 1-day.
```

--------------------------------

### Initialize MapPlot and Add Stars

Source: https://starplot.dev/examples/map-custom-marker

Sets up the MapPlot with a specific projection and boundaries, then adds star data with custom styling and labels based on magnitude.

```python
center_coord = SkyCoord(ra=160, dec=58, unit="deg")
center_ra = center_coord.ra.deg
center_dec = center_coord.dec.deg

style = PlotStyle().extend(
    extensions.BLUE_LIGHT,
    extensions.MAP,
)
p = MapPlot(
    projection=LambertAzEqArea(center_ra=center_ra, center_dec=center_dec),
    ra_min=120,
    ra_max=200,
    dec_min=33,
    dec_max=78,
    style=style,
    resolution=4000,
    autoscale=True,
)

p.stars(
    where=[_.magnitude < 8],
    bayer_labels=True,
    where_labels=[_.magnitude < 1.75],
    alpha_fn=lambda star: max(0.01, 1.0 - 0.1 * star.magnitude),
)
```

--------------------------------

### Initialize OpticPlot

Source: https://starplot.dev/reference-opticplot

Creates a new OpticPlot instance. Configure parameters like target coordinates, optic properties, observer location, ephemeris, style, and collision handling for labels. Warnings can be suppressed, and scaling options are available.

```python
OpticPlot(
    ra: float,
    dec: float,
    optic: Optic,
    observer: Observer = None,
    ephemeris: str = "de421.bsp",
    style: PlotStyle = None,
    resolution: int = 4096,
    point_label_handler: CollisionHandler = None,
    area_label_handler: CollisionHandler = None,
    path_label_handler: CollisionHandler = None,
    raise_on_below_horizon: bool = True,
    scale: float = 1.0,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs
)

```

--------------------------------

### Comet.get

Source: https://starplot.dev/reference-models/index.html

Get a comet for a specific date/time.

```APIDOC
## Comet.get

### Description
Get a comet for a specific date/time.

### Method
`get(name: str, observer: Observer = None, ephemeris: str = "de421.bsp", reload: bool = False) -> Comet`

### Parameters
#### Query Parameters
- **name** (str) - Name of the comet you want to get (as designated by IAU Minor Planet Center)
- **observer** (Observer, Optional) - Observer instance that specifies a time and location
- **ephemeris** (str, Optional) - Ephemeris to use for calculating comet positions (see Skyfield's documentation for details). Defaults to 'de421.bsp'.
- **reload** (bool, Optional) - If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available. Defaults to False.
```

--------------------------------

### get

Source: https://starplot.dev/reference-models/index.html

Retrieves a single Constellation by matching its attributes.

```APIDOC
## get

### Description
Get a Constellation, by matching its attributes.
Example:
```
hercules = Constellation.get(name="Hercules")
```

### Parameters
* **`catalog`**(`Catalog`, default: `CONSTELLATIONS_IAU` ) – 
The catalog of constellations to use
* **`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
```

--------------------------------

### Initialize OPEN_NGC Catalog

Source: https://starplot.dev/data/dsos/index.html

This code snippet shows how to initialize the OPEN_NGC catalog, which includes nebulae outlines. It specifies the local path to the data file and the URL for downloading it.

```python
OPEN_NGC = Catalog(
    path=data_path / "ongc.0.1.2.parquet",
    url="https://github.com/steveberardi/starplot-ongc/releases/download/v0.1.2/ongc.0.1.2.parquet",
)
```

--------------------------------

### get

Source: https://starplot.dev/reference-models

Retrieves a single Constellation by matching its attributes.

```APIDOC
## `get`

### Description
Get a Constellation, by matching its attributes.

### Method
`get(catalog: Catalog = CONSTELLATIONS_IAU, sql: str = None, **kwargs) -> Constellation`

### Parameters
- **`catalog`** (`Catalog`, default: `CONSTELLATIONS_IAU`): The catalog of constellations to use.
- **`sql`** (`str`, default: `None`): SQL query for selecting constellation (table name is "_").
- **`**kwargs`**: Attributes on the constellation you want to match.

### Example
```python
hercules = Constellation.get(name="Hercules")
```

### Raises
`ValueError` if more than one constellation is matched.
```

--------------------------------

### Initialize Settings with Default Values

Source: https://starplot.dev/reference-settings/index.html

The `__init__` method for the Settings dataclass allows initialization of `data_path`, `svg_text_type`, `language`, and `debug` with default or environment-provided values.

```python
__init__(
    data_path: Path = _get_path("STARPLOT_DATA_PATH", cwd())(),
    svg_text_type: SvgTextType = (
        lambda: get("STARPLOT_SVG_TEXT_TYPE", PATH)
    )(),
    language: str = (lambda: get("STARPLOT_LANGUAGE", "en-US"))(),
    debug: bool = _get_boolean("STARPLOT_DEBUG", False)(),
) -> None

```

--------------------------------

### Star.get

Source: https://starplot.dev/reference-models

Get a Star, by matching its attributes as specified in `**kwargs`.

```APIDOC
## Star.get

Get a Star, by matching its attributes as specified in `**kwargs`.
If there are multiple matches, then the first match (sorted by CCDM) will be returned.
Example:
```
sirius = Star.get(name="Sirius")
```

### Parameters
* `catalog` (Catalog, default: `BIG_SKY_MAG11` ) – 
The catalog of stars to use
* `sql` (str , default: `None` ) – 
SQL query for selecting star (table name is "_")
* `**kwargs`–
Attributes on the star you want to match

### Returns
* `Union[Star, None]` – 
First star that matches specified attributes, when sorted by CCDM -- or `None` if no star matches
```

--------------------------------

### Build Catalog from Objects

Source: https://starplot.dev/data/overview

Creates a catalog from an iterable of SkyObject instances, outputting data as Parquet files. Allows configuration of chunk size, columns, partitioning, sorting, compression, and row group size.

```python
build(
    objects: Iterable[SkyObject],
    chunk_size: int = 1000000,
    columns: list[str] = None,
    partition_columns: list[str] = None,
    sorting_columns: list[str] = None,
    compression: str = "snappy",
    row_group_size: int = 200000,
) -> None
```

--------------------------------

### magnitude_range Property

Source: https://starplot.dev/reference-zenithplot

Get the range of magnitudes for all plotted stars.

```APIDOC
## magnitude_range `property`

### Description
Range of magnitude for all plotted stars, as a tuple (min, max)

### Type
`tuple[float, float]`
```

--------------------------------

### Create an Observer Instance

Source: https://starplot.dev/reference-models/index.html

Instantiate an Observer with a specific datetime and geographic coordinates. Ensure the datetime is timezone-aware.

```python
obs = Observer(
    dt=datetime(2025, 10, 13, 21, 0, 0, tzinfo=ZoneInfo('US/Pacific')),
    lat=33.363484,
    lon=-116.836394,
)

```

--------------------------------

### Get Azimuth Property

Source: https://starplot.dev/reference-opticplot

Retrieves the azimuth of the target in degrees.

```python
az
```

--------------------------------

### Initialize GalaxyPlot

Source: https://starplot.dev/reference-galaxyplot/index.html

Creates a new GalaxyPlot instance. Customize the projection center, observer, ephemeris, style, resolution, and collision handling for labels. Scaling and autoscale options are available.

```python
GalaxyPlot(
    center_lon: float = 0,
    observer: Observer = None,
    ephemeris: str = "de421.bsp",
    style: PlotStyle = None,
    resolution: int = 4096,
    point_label_handler: CollisionHandler = None,
    area_label_handler: CollisionHandler = None,
    path_label_handler: CollisionHandler = None,
    scale: float = 1.0,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs
)

```

--------------------------------

### Get Altitude Property

Source: https://starplot.dev/reference-opticplot

Retrieves the altitude of the target in degrees.

```python
alt
```

--------------------------------

### Comet.all

Source: https://starplot.dev/reference-models/index.html

Iterator for getting all comets at a specific date/time and observing location.

```APIDOC
## Comet.all

### Description
Iterator for getting all comets at a specific date/time and observing location.

### Method
`all(observer: Observer = None, ephemeris: str = "de421.bsp", reload: bool = False) -> Iterator[Comet]`

### Parameters
#### Query Parameters
- **observer** (Observer, Optional) - Observer instance that specifies a time and location
- **ephemeris** (str, Optional) - Ephemeris to use for calculating comet positions (see Skyfield's documentation for details). Defaults to 'de421.bsp'.
- **reload** (bool, Optional) - If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available. Defaults to False.
```

--------------------------------

### Creating a Custom Callable

Source: https://starplot.dev/reference-callables/index.html

Demonstrates how to define and use a custom callable function for coloring stars based on magnitude.

```APIDOC
## Creating a Custom Callable

This example shows how to create a custom callable function to color stars based on their magnitude.

### Custom Callable Definition
```python
# first we define the callable:
def color_by_mag(star: Star) -> str:
    if star.magnitude <= 4:
        return "#218fef"
    else:
        return "#d52727"
```

### Using the Custom Callable
```python
# then to use your callable:
p = MapPlot(...)
p.stars(
    where=[_.magnitude < 12],
    color_fn=color_by_mag,
)
```
```

--------------------------------

### Create a Basic Plot Style

Source: https://starplot.dev/reference-styling

Initializes a new PlotStyle instance. This serves as the foundation for further customization.

```python
from starplot.styles import PlotStyle

style = PlotStyle()
```

--------------------------------

### Comet.from_json

Source: https://starplot.dev/reference-models/index.html

Get a comet for a specific date/time/location from an IAU MPC JSON.

```APIDOC
## Comet.from_json

### Description
Get a comet for a specific date/time/location from an IAU MPC JSON.

### Method
`from_json(data: dict, observer: Observer = None, ephemeris: str = "de421.bsp") -> Comet`

### Parameters
#### Request Body
- **data** (dict) - Dictionary of the IAU MPC JSON
- **observer** (Observer, Optional) - Observer instance that specifies a time and location
- **ephemeris** (str, Optional) - Ephemeris to use for calculating comet positions (see Skyfield's documentation for details). Defaults to 'de421.bsp'.
```

--------------------------------

### Get All Planets

Source: https://starplot.dev/tutorial/07

Retrieve a list of all available planet objects in Starplot.

```python
planets = Planet.all()
```

--------------------------------

### Get Matplotlib Figure Instance

Source: https://starplot.dev/reference-opticplot

Accesses the underlying Matplotlib figure object.

```python
fig: Figure = None
```

--------------------------------

### Path Label Handler Initialization

Source: https://starplot.dev/reference-mapplot

Sets up the default collision handler for path labels. Allows constellation line collisions by default.

```python
path_label_handler = path_label_handler or CollisionHandler(
    allow_constellation_line_collisions=True
)

```

--------------------------------

### Basic Plot Style Application

Source: https://starplot.dev/reference-styling

Demonstrates the three-step process of creating a PlotStyle, extending it with built-in extensions, and applying it to a MapPlot. Ensure PlotStyle and relevant extensions are imported.

```python
from starplot import MapPlot, Miller
from starplot.styles import PlotStyle, extensions

# Step 1: create a style
style = PlotStyle()

# Step 2: extend the style with a few built-in extensions
style = style.extend(
    extensions.BLUE_LIGHT,
    extensions.MAP,
)

# Step 3: apply the style in a new map plot
mp = MapPlot(
    projection=Miller(),
    ra_min=4,
    ra_max=8,
    dec_min=0,
    dec_max=20,
    style=style,
)
```

--------------------------------

### Get All Stars from Catalog

Source: https://starplot.dev/reference-models

Retrieves an iterator for all stars within a specified catalog. Defaults to the BIG_SKY_MAG11 catalog.

```python
all(catalog: Catalog = BIG_SKY_MAG11) -> Iterator[Star]
```

--------------------------------

### BLUE_LIGHT Styling Configuration

Source: https://starplot.dev/reference-styling

This configuration defines a light and bright blue color scheme. It sets colors for background, borders, text, and celestial objects, suitable for a clear and vibrant display.

```yaml
background_color: hsl(218, 88%, 99%)

text_border_color: hsl(218, 88%, 99%)

border_bg_color: '#b5cbe3'
border_font_color: '#2f4358'
border_line_color: '#2f4358'

horizon:
  line:
    color: '#b5cbe3'
    edge_color: '#2f4358'
  label:
    font_color: '#2f4358'

zenith:
  marker:
    color: hsl(18, 68%, 75%)
  label:
    font_color: hsl(18, 68%, 75%)

title:
  font_color: '#2f4358'
star:
  marker:
    edge_color: '#fff'

celestial_equator:
  label:
    font_color: '#2d5ec2'
    border_color: hsl(218, 88%, 99%)
  line:
    color: '#2d5ec2'

ecliptic:
  label:
    font_color: '#e33b3b'
    border_color: hsl(218, 88%, 99%)
  line:
    color: hsl(359, 98%, 49%)
    alpha: 1
    style: [0, [0.14, 2]]

# Constellations
constellation_labels:
  font_alpha: 0.27
  font_color: '#000'
constellation_lines:
  alpha: 0.52
  color: '#6ba832'
  width: 3

dso_double_star:
  marker:
    alpha: 1

dso_galaxy:
  marker:
    alpha: 1
    color: hsl(330, 80%, 85%)
    edge_color: hsl(330, 84%, 20%)
  label:
    font_color: hsl(330, 84%, 20%)

dso_nebula: &DSO-NEB
  marker:
    alpha: 1
    color: hsl(98, 68%, 82%)
    edge_color: hsl(91, 63%, 24%)
  label:
    font_color: hsl(91, 63%, 29%)
dso_planetary_nebula:
  marker:
    alpha: 1
    color: hsl(96, 76%, 82%)
    edge_color: hsl(91, 63%, 24%)
  label:
    font_color: hsl(91, 63%, 29%)

dso_open_cluster: &DSO-OC
  marker:
    alpha: 1
    color: hsl(58, 98%, 77%)
    edge_color: "#000"
  label:
    font_color: hsl(58, 98%, 20%)
dso_association_stars: *DSO-OC

dso_globular_cluster:
  marker:
    alpha: 1
    color: hsl(58, 98%, 77%)
    edge_color: "#000"
  label:
    font_color: '#989400'

# other DSOs
dso_unknown: &DSO
  marker:
    alpha: 0.76
    color: hsl(91, 53%, 75%)
    edge_color: hsl(91, 53%, 40%)
  label:
    font_color: hsl(91, 53%, 40%)
dso_dark_nebula: *DSO
dso_supernova_remnant: *DSO
dso_nova_star: *DSO
dso_nonexistant: *DSO
dso_unknown: *DSO
dso_duplicate: *DSO

milky_way:
  alpha: 0.25
  fill_color: hsl(203, 70%, 81%)
  edge_width: 0
planets:
  marker:
    alpha: 0.4
    color: '#f89d00'
    fill: full

legend:
  background_color: '#fff'

```

--------------------------------

### Get Plotted Sky Objects

Source: https://starplot.dev/reference-opticplot

Returns an ObjectList containing various lists of plotted sky objects.

```python
objects: ObjectList
```

--------------------------------

### Creating a Custom Callable (`color_by_mag`)

Source: https://starplot.dev/reference-callables

Demonstrates how to define and use a custom callable function to color stars based on their magnitude.

```APIDOC
## Creating a Custom Callable (`color_by_mag`)

### Description
This example illustrates defining a custom callable function, `color_by_mag`, which colors stars blue if they are brighter than magnitude 4 and red otherwise. It then shows how to use this custom callable with `MapPlot.stars()`.

### Method
`MapPlot.stars()`

### Parameters
- `color_fn`: A callable that accepts a `Star` object and returns a color string.

### Request Example
```python
# Define the custom callable
def color_by_mag(star: Star) -> str:
    if star.magnitude <= 4:
        return "#218fef"  # Blue
    else:
        return "#d52727"  # Red

# Instantiate MapPlot (assuming projection, ra/dec ranges, and style are defined)
# p = MapPlot(...)

# Use the custom callable
p.stars(
    where=[_.magnitude < 12],
    color_fn=color_by_mag, # Using the custom callable
)
```
```

--------------------------------

### Get Magnitude Range Property

Source: https://starplot.dev/reference-opticplot

Retrieves the range of magnitudes for plotted stars as a tuple (min, max).

```python
magnitude_range: tuple[float, float]
```

--------------------------------

### HorizonPlot Constructor

Source: https://starplot.dev/reference-horizonplot/index.html

Initializes a new HorizonPlot instance. This plot visualizes the sky from the horizon, showing celestial objects in their apparent positions.

```APIDOC
## HorizonPlot Constructor

### Description
Creates a new horizon plot. This plot visualizes the sky from the horizon, showing celestial objects in their apparent positions.

### Parameters
* **`altitude`**(`tuple[float, float]`) – Required - Tuple of altitude range to plot (min, max).
* **`azimuth`**(`tuple[float, float]`) – Required - Tuple of azimuth range to plot (min, max).
* **`observer`**(`Observer`, default: `None`) – Observer instance which specifies a time and place. Defaults to `Observer()`.
* **`ephemeris`**(`str`, default: `'de421.bsp'`) – Ephemeris to use for calculating planet positions.
* **`style`**(`PlotStyle`, default: `None`) – Styling for the plot (colors, sizes, fonts, etc). If `None`, it defaults to `PlotStyle()`.
* **`resolution`**(`int`, default: `4096`) – Size (in pixels) of largest dimension of the map.
* **`point_label_handler`**(`CollisionHandler`, default: `None`) – Default CollisionHandler for point labels.
* **`area_label_handler`**(`CollisionHandler`, default: `None`) – Default CollisionHandler for area labels.
* **`path_label_handler`**(`CollisionHandler`, default: `None`) – Default CollisionHandler for path labels.
* **`scale`**(`float`, default: `1.0`) – Scaling factor that will be applied to all relevant sizes in styles.
* **`autoscale`**(`bool`, default: `False`) – If True, then the scale will be automatically set based on resolution.
* **`suppress_warnings`**(`bool`, default: `True`) – If True (the default), then all warnings will be suppressed.

### Returns
* **`HorizonPlot`**– A new instance of an HorizonPlot.
```

--------------------------------

### Get DSO Style

Source: https://starplot.dev/reference-styling/index.html

Retrieves the specific style configuration for a given Deep Sky Object (DSO) type.

```python
get_dso_style(dso_type: DsoType)

```

--------------------------------

### Environment Variable Configuration

Source: https://starplot.dev/reference-settings/index.html

Explains how to configure Starplot settings using environment variables.

```APIDOC
## Environment Variables
To set values through environment variables, just add the `STARPLOT_` prefix to the setting name (and uppercase the entire name):
```bash
STARPLOT_DATA_PATH=/home/myuser/data
```
```

--------------------------------

### Get All Constellations Class Method

Source: https://starplot.dev/reference-models/index.html

Retrieves an iterator of all Constellation objects from a specified catalog. Defaults to the IAU catalog.

```python
all(catalog: Catalog = CONSTELLATIONS_IAU) -> Iterator[Constellation]
```

--------------------------------

### Dump Style to File

Source: https://starplot.dev/reference-styling/index.html

Saves the current style configuration to a YAML file. All style properties are included in the output.

```python
dump_to_file(filename: str) -> None

```

--------------------------------

### Get SkyObject Constellation

Source: https://starplot.dev/reference-models/index.html

The `constellation` method returns the `Constellation` object that contains the sky object, or `None` if not found.

```python
constellation()

```

--------------------------------

### Satellite Instance Methods

Source: https://starplot.dev/reference-models

Methods for interacting with Satellite objects.

```APIDOC
## `Satellite.create_optic`

### Description
Creates an optic plot with this object at the center.

### Method
`instance-method`

### Parameters
#### Arguments
- **`*args`** - args passed through to `OpticPlot()`
- **`**kwargs`** - kwargs passed through to `OpticPlot()`

### Response
- **`OpticPlot`** - new instance of a `OpticPlot`
```

```APIDOC
## `Satellite.create_map`

### Description
Creates a map plot with this object at the center.

### Method
`instance-method`

### Parameters
#### Arguments
- **`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()`

### Response
- **`MapPlot`** - new instance of a `MapPlot`
```

```APIDOC
## `Satellite.constellation`

### Description
Returns an instance of the `Constellation` that contains this object, or `None` if no constellation is found.

### Method
`instance-method`

### Response
- `Constellation` or `None`
```

```APIDOC
## `Satellite.populate_constellation_id`

### Description
Populates the `constellation_id` field based on the location of this object.

### Method
`instance-method`
```

--------------------------------

### Enable Hive Partitioning

Source: https://starplot.dev/data/overview

Set to True if the catalog utilizes Hive partitioning for organization.

```python
hive_partitioning: bool = False
```

--------------------------------

### Get DSO Style Function

Source: https://starplot.dev/reference-styling

Retrieves the specific style configuration for a given Deep Sky Object (DSO) type.

```python
get_dso_style(dso_type: DsoType)
```

--------------------------------

### get (Sun)

Source: https://starplot.dev/reference-models

Retrieves the Sun's position for a specific date/time and observer location, using a specified ephemeris file.

```APIDOC
## get `classmethod`

### Description
Get the Sun for a specific date/time and observing location.

### Parameters
* **`observer`** (`Observer`, default: `None`) - Observer instance that specifies a time and location
* **`ephemeris`** (`str`, default: `'de421.bsp'`) - Ephemeris to use for calculating Sun/moon/planet positions (see Skyfield's documentation for details)

### Returns
* **`Sun`**
```

--------------------------------

### Create and use an Observer instance

Source: https://starplot.dev/migration-guides/0.16.0

Instantiate an Observer with datetime, latitude, and longitude. This observer is now required for most plot types, including HorizonPlot.

```python
from starplot import Observer
from datetime import datetime
from zoneinfo import ZoneInfo

# Create observer
observer = Observer(
    dt=datetime(2023, 7, 13, 22, 0, tzinfo=ZoneInfo("America/Los_Angeles")),
    lat=33.363484,
    lon=-116.836394,
)

# Use the observer in a horizon plot
p = HorizonPlot(
    altitude=(0, 70),
    azimuth=(320, 435),
    observer=observer,
    ...
)
```

--------------------------------

### Satellite Class Methods

Source: https://starplot.dev/reference-models

Methods for creating Satellite instances from different data sources.

```APIDOC
## Satellite.from_json

### Description
Get a satellite for a specific date/time/location from a CelesTrak JSON.

### Method
`classmethod`

### Parameters
* **`data`** (`dict`) – Dictionary of the CelesTrak JSON
* **`observer`** (`Observer`, default: `None`) – Observer instance that specifies a time and location

### Returns
* `Satellite` – A Satellite instance.
```

```APIDOC
## Satellite.from_tle

### Description
Get a satellite for a specific date/time/location from a two-line element set (TLE).

### Method
`classmethod`

### 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)
* **`observer`** (`Observer`, default: `None`) – Observer instance that specifies a time and location

### Returns
* `Satellite` – A Satellite instance.
```

```APIDOC
## Satellite.trajectory

### Description
Iterator for getting a trajectory of the satellite.

### Method
`instance-method`

### 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.
```

--------------------------------

### Satellite Class Methods

Source: https://starplot.dev/reference-models/index.html

Methods for creating Satellite instances from different data sources.

```APIDOC
## Satellite.from_json

### Description
Get a satellite for a specific date/time/location from a CelesTrak JSON.

### Method
`classmethod from_json(data: dict, observer: Observer = None) -> Satellite`

### Parameters
#### Path Parameters
- **`data`** (dict) - Dictionary of the CelesTrak JSON
- **`observer`** (Observer, default: `None`) - Observer instance that specifies a time and location

### Returns
- `Satellite` - A Satellite instance.
```

```APIDOC
## Satellite.from_tle

### Description
Get a satellite for a specific date/time/location from a two-line element set (TLE).

### Method
`classmethod from_tle(name: str, line1: str, line2: str, observer: Observer = None) -> Satellite`

### Parameters
#### Path 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)
- **`observer`** (Observer, default: `None`) - Observer instance that specifies a time and location

### Returns
- `Satellite` - A Satellite instance.
```

```APIDOC
## Satellite.trajectory

### Description
Iterator for getting a trajectory of the satellite.

### Method
`trajectory(date_start: datetime, date_end: datetime, step: timedelta = None) -> Iterator[Satellite]`

### Parameters
#### Path 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.
```

--------------------------------

### Create and use an Observer instance

Source: https://starplot.dev/migration-guides/0.16.0/index.html

Instantiate an Observer with datetime, latitude, and longitude. This observer is now required for all plot types, including HorizonPlot.

```python
from datetime import datetime
from zoneinfo import ZoneInfo
from starplot import Observer, HorizonPlot

# Create observer
observer = Observer(
    dt=datetime(2023, 7, 13, 22, 0, tzinfo=ZoneInfo("America/Los_Angeles")),
    lat=33.363484,
    lon=-116.836394,
)

# Use the observer in a horizon plot
p = HorizonPlot(
    altitude=(0, 70),
    azimuth=(320, 435),
    observer=observer,
    ...
)
```

--------------------------------

### Get Constellation Instance

Source: https://starplot.dev/reference-models/index.html

Returns the Constellation object containing this celestial body, or None if it's not part of a known constellation.

```python
constellation()
```

```python
constellation()
```

--------------------------------

### Get Constellation Method

Source: https://starplot.dev/reference-models

Retrieves the `Constellation` object that contains this DSO. Returns `None` if the DSO is not part of a recognized constellation.

```python
constellation()


```

--------------------------------

### MapPlot Constructor

Source: https://starplot.dev/reference-mapplot

Initializes a new MapPlot instance. Configure projection, map extent, observer, ephemeris, style, resolution, and collision handlers for labels. Optional parameters control clipping, scaling, and warning suppression.

```python
MapPlot(
    projection: ProjectionBase,
    ra_min: float = 0,
    ra_max: float = 360,
    dec_min: float = -90,
    dec_max: float = 90,
    observer: Observer = None,
    ephemeris: str = "de421.bsp",
    style: PlotStyle = None,
    resolution: int = 4096,
    point_label_handler: CollisionHandler = None,
    area_label_handler: CollisionHandler = None,
    path_label_handler: CollisionHandler = None,
    clip_path: Polygon = None,
    scale: float = 1.0,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs
)

```

--------------------------------

### size_by_magnitude

Source: https://starplot.dev/reference-callables/index.html

A built-in callable for simple star sizing based on magnitude, using a step size of 1.

```APIDOC
## `size_by_magnitude`

```python
size_by_magnitude(star: Star) -> float
```

Simple sizing by magnitude, using a step size of 1.

```
if mag <= 0:
    size = 3800
elif mag <= 1:  # 0..1
    size = 2400
elif mag <= 2:  # 1..2
    size = 1600
elif mag <= 3:  # 2..3
    size = 1000
elif mag <= 4:  # 3..4
    size = 600
elif mag <= 5:  # 4..5
    size = 300
elif mag <= 6:  # 5..6
    size = 120
elif mag <= 7:  # 6..7
    size = 60
elif mag <= 8:  # 7..8
    size = 40
else:           # > 8
    size = 20
```
```

--------------------------------

### Get a Specific DSO

Source: https://starplot.dev/tutorial/07

Retrieve a Deep Sky Object (DSO) by its Messier number. Requires importing the DSO model.

```python
m13 = DSO.get(m="13")
```

--------------------------------

### Get Matplotlib Axes Instance

Source: https://starplot.dev/reference-opticplot

Accesses the underlying Matplotlib axes object. Use with caution as transformations may be applied.

```python
ax: Axes = None
```

--------------------------------

### Comet Instance Methods

Source: https://starplot.dev/reference-models

Methods and attributes for individual Comet objects.

```APIDOC
## `Comet.populate_constellation_id`

### Description
Populates the `constellation_id` field based on the location of this object.

### Method
`instance-method`
```

```APIDOC
## `Comet.trajectory`

### Description
Iterator for getting a trajectory of the comet.

### Method
`instance-method`

### Parameters
#### Arguments
- **`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.

### Response
- `Iterator[Comet]` - Iterator yielding a Comet instance at each step.
```

--------------------------------

### Get All DSOs Class Method

Source: https://starplot.dev/reference-models

Retrieves an iterator for all Deep Sky Objects (DSOs) from a specified catalog. Defaults to the OPEN_NGC catalog.

```python
all(catalog: Catalog = OPEN_NGC) -> Iterator[DSO]


```

--------------------------------

### size_by_magnitude_factory

Source: https://starplot.dev/reference-callables/index.html

Creates a new version of `size_by_magnitude_log` with a custom threshold and base multiplier. This allows for flexible size calculations based on star magnitude.

```APIDOC
## size_by_magnitude_factory

### Description
Creates a new version of `size_by_magnitude_log` with a custom threshold and base multiplier.

### Parameters
* **`threshold`** (`float`) - The threshold at which size will be a constant value. If an object's magnitude is more than or equal to this number, then its size will be the constant `under_threshold_size`.
* **`over_threshold_size`** (`float`) - Size for objects that have a magnitude greater than or equal to the threshold.
* **`base`** (`float`, default: `20`) - Base for objects that have a magnitude less than the threshold.

### Returns
* `Callable[[Star], float]` - A callable for calculating size based on magnitude.
```

--------------------------------

### Get All DSOs from Catalog

Source: https://starplot.dev/reference-models/index.html

A class method to retrieve an iterator of all Deep Sky Objects from a specified catalog. Defaults to the `OPEN_NGC` catalog.

```python
all(catalog: Catalog = OPEN_NGC) -> Iterator[DSO]
```
Tokens:
Raw