Starplot Python Library

Starplot utilizes several external catalogs and datasets to render celestial features. When configuring or extending your star map, you can reference these primary sources for specific astronomical data:

• Stars: Big Sky Catalog (Hipparcos, Tycho-1, Tycho-2 in Epoch J2000).
• Constellation Lines: Stellarium (via Sky & Telescope).
• Constellation Borders: IAU Constellation page and VizieR VI/49 (via d3-celestial).
• Deep Sky Objects (DSOs): OpenNGC (NGC and IC catalogs).
• Moon & Planet Sizes: NASA Solar System and Moon facts.
• Milky Way Outline: NASA Deep Star Maps (processed via QGIS + GDAL).

Note: Starplot now supports custom data catalogs for stars, constellations, and DSOs.

Callables are functions used to dynamically calculate style properties for stars, such as size, alpha (opacity), color, and label.

Note that Deep Sky Objects (DSOs) only support callables for alpha and labels.

When you provide a callable to a star plotting method, Starplot passes an instance of a Star object to your function, allowing you to access any of its properties (like magnitude, ra, dec, etc.) to determine the return value.

Starplot uses models to represent the observer and various celestial objects. These models serve several core functions in the library:

• Observing Context: Defining the specific time and geographic location of an observer.
• Object Selection: Filtering which objects to plot using the where keyword argument.
• Dynamic Styling: Creating callables to calculate visual properties like size, color, or alpha values.
• Object Management: Tracking plotted objects using starplot.ObjectList.
• Positioning & Querying:
  • Using .get() to retrieve an object's position at a specific time.
  • Using .find() to retrieve a list of objects that satisfy specific conditions.

Starplot uses a CollisionHandler to manage label positioning and prevent overlaps between labels and map features. You can control how different types of labels behave by specifying handlers for three distinct categories:

• Points (point_label_handler): Used for stars, DSOs, etc.
• Areas (area_label_handler): Used for constellations.
• Paths (path_label_handler): Used for the ecliptic, celestial equator, etc.

You can set these handlers globally when creating a plot, or override them individually in any function that plots text.

# Example of setting global handlers during plot creation (conceptual)
plot = Starplot(
    point_label_handler=my_point_handler,
    area_label_handler=my_area_handler,
    path_label_handler=my_path_handler
)

Zenith plots (also known as star charts or all-sky charts) show the entire sky as seen from a specific time and place, with the zenith at the center of the plot. In starplot, stars on zenith plots are plotted using their astrometric positions.

You can use the starplot.ZenithPlot class to generate these visualizations.

# Example usage of ZenithPlot
from starplot import ZenithPlot

# Initialize the plot (specific parameters depend on your data and location)
plot = ZenithPlot()

The starplot.data.Catalog class is used to represent a collection of sky objects. Currently, Starplot supports the following object types within catalogs:

• Stars
• Constellations
• Deep Sky Objects (DSOs)

All catalogs are stored as Parquet files to ensure fast object lookup. If you attempt to plot an object type using a catalog that does not exist locally but has a defined URL, Starplot will automatically download the catalog from that URL.

For catalogs containing fewer than 1 million objects, you can improve query performance by specifying sorting_columns during the build process.

If you frequently query a specific field that has medium or high standard deviation, sorting the catalog by that field allows the data backend to scan data more efficiently. Pass a list of field names to the sorting_columns parameter in the build method.

Starplot provides a hierarchy of models to represent the observer and celestial bodies:

Observer

• starplot.Observer: Represents the person or device observing the sky.

Sky Objects

All sky objects inherit from starplot.models.base.SkyObject. Available models include:

• starplot.Star: Individual stars.
• starplot.Constellation: Groups of stars.
• starplot.DSO: Deep Sky Objects (categorized by starplot.models.dso.DsoType).
• starplot.Planet: Planets in the solar system.
• starplot.Sun: The Sun.
• starplot.Moon: The Moon.
• starplot.Comet: Comets.
• starplot.Satellite: Artificial satellites.

Object Management

• starplot.ObjectList: A container used to keep track of multiple plotted objects.

Callables allow you to define custom functions to calculate specific style properties for stars, such as size, alpha (opacity), color, and their labels.

Important Compatibility Note:

• DSOs (Data Source Objects) only support callables for alpha and labels.
• Starplot supports callables for size, alpha, color, and labels.

Starplot includes several built-in callables (e.g., color_by_bv for colorizing stars based on their B-V index), but you can also implement your own custom functions to drive these properties dynamically.

# Example concept: using a built-in callable like color_by_bv
# to colorize stars based on their B-V index.