starplot.OpticPlot

Optic plots simulate what you'll see through an optic (e.g. binoculars, telescope, camera) at a specific time and location. The simulated view will show you the true field of view for the optic, and it will even orient the stars based on the location you specify and the most logical position of your optic.

These plots use an azimuthal equidistant projection, with the projection's center set to the target's position (in azimuth, altitude coordinates). This projection was chosen because it preserves the correct proportional distances from the center point.

starplot.OpticPlot(optic, ra, dec, lat, lon, dt=None, limiting_magnitude=6.0, limiting_magnitude_labels=2.1, include_info_text=False, ephemeris='de421_2001.bsp', style=OPTIC_BASE, resolution=2048, hide_colliding_labels=True, adjust_text=False, rasterize_stars=False, colorize_stars=False, raise_on_below_horizon=True, *args, **kwargs)

Creates a new optic plot.

Parameters:

• optic (Optic) –

  Optic instance that defines optical parameters

• ra (float) –

  Right ascension of target center

• dec (float) –

  Declination of target center

• lat (float) –

  Latitude of observer's location

• lon (float) –

  Longitude of observer's location

• dt (datetime, default: None ) –

  Date/time of observation (must be timezone-aware). Default = current UTC time.

• limiting_magnitude (float, default: 6.0 ) –

  Limiting magnitude of stars to plot

• limiting_magnitude_labels (float, default: 2.1 ) –

  Limiting magnitude of stars to label on the plot

• include_info_text (bool, default: False ) –

  If True, then the plot will include a table with details of the target/observer/optic

• ephemeris (str, default: 'de421_2001.bsp' ) –

  Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)

• style (PlotStyle, default: OPTIC_BASE ) –

  Styling for the plot (colors, sizes, fonts, etc)

• resolution (int, default: 2048 ) –

  Size (in pixels) of largest dimension of the map

• hide_colliding_labels (bool, default: True ) –

  If True, then labels will not be plotted if they collide with another existing label

• adjust_text (bool, default: False ) –

  If True, then the labels will be adjusted to avoid overlapping

• rasterize_stars (bool, default: False ) –

  If True, then the stars will be rasterized when plotted, which can speed up exporting to SVG and reduce the file size but with a loss of image quality

• colorize_stars (bool, default: False ) –

  If True, then stars will be filled with their BV color index

• raise_on_below_horizon (bool, default: True ) –

  If True, then a ValueError will be raised if the target is below the horizon at the observing time/location

Returns:

• OpticPlot –

  A new instance of a OpticPlot

adjust_labels()

Adjust all the labels to avoid overlapping.

close_fig()

Closes the underlying matplotlib figure.

draw_reticle(ra, dec, size=6, color='red')

Plots a basic reticle on the map.

Parameters:

• ra (float) –

  Right ascension of the reticle's center

• dec (float) –

  Declination of the reticle's center

• size (int, default: 6 ) –

  Relative size of the reticle

• color (str, default: 'red' ) –

  Color of the reticle (Matplotlib format)

export(filename, format='png', padding=0, **kwargs)

Exports the plot to an image file.

Parameters:

• filename (str) –

  Filename of exported file

• format (str, default: 'png' ) –

  Format of file: "png" or "svg"

• padding (float, default: 0 ) –

  Padding (in inches) around the image

• **kwargs –

  Any keyword arguments to pass through to matplotlib's savefig method

plot_circle(center, radius_degrees, style, num_pts=100)

Plots a circle

Parameters:

• center (tuple) –

  Center of circle (ra, dec)

• radius_degrees (float) –

  Radius of circle (degrees)

• style (PolygonStyle) –

  Style of circle

• num_pts (int, default: 100 ) –

  Number of points to calculate for the circle polygon

plot_ellipse(center, height_degrees, width_degrees, style, angle=0, num_pts=100)

Plots an ellipse

Parameters:

• center (tuple) –

  Center of ellipse (ra, dec)

• height_degrees (float) –

  Height of ellipse (degrees)

• width_degrees (float) –

  Width of ellipse (degrees)

• style (PolygonStyle) –

  Style of ellipse

• angle (float, default: 0 ) –

  Angle of rotation clockwise (degrees)

• num_pts (int, default: 100 ) –

  Number of points to calculate for the ellipse polygon

plot_object(obj)

Plots an object (see SkyObject for details).

Parameters:

• obj (SkyObject) –

  The object to plot

plot_polygon(points, style)

Plots a polygon of points

Parameters:

• points (list) –

  List of polygon points [(ra, dec), ...]

• style (PolygonStyle) –

  Style of polygon

plot_rectangle(center, height_degrees, width_degrees, style, angle=0, *args, **kwargs)

Plots a rectangle

Parameters:

• center (tuple) –

  Center of rectangle (ra, dec)

• height_degrees (float) –

  Height of rectangle (degrees)

• width_degrees (float) –

  Width of rectangle (degrees)

• angle (float, default: 0 ) –

  Angle of rotation clockwise (degrees)

• style (PolygonStyle) –

  Style of rectangle

refresh_legend()

Redraws the legend.

This is useful if you want to include objects in the legend that were plotted AFTER creating the plot (via plot_object)

starplot.optics.Optic

Abstract class for defining Optics.

starplot.optics.Binoculars(magnification, fov)

Creates a new Binoculars optic

Parameters:

• magnification (float) –

  Magnification of the binoculars

• fov (float) –

  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

starplot.optics.Scope(focal_length, eyepiece_focal_length, eyepiece_fov)

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 (float) –

  Focal length (mm) of the telescope

• eyepiece_focal_length (float) –

  Focal length (mm) of the eyepiece

• eyepiece_fov (float) –

  Field of view (degrees) of the eyepiece

Returns:

• Scope –

  A new instance of a Scope optic

starplot.optics.Refractor(focal_length, eyepiece_focal_length, eyepiece_fov)

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 (float) –

  Focal length (mm) of the telescope

• eyepiece_focal_length (float) –

  Focal length (mm) of the eyepiece

• eyepiece_fov (float) –

  Field of view (degrees) of the eyepiece

Returns:

• Refractor –

  A new instance of a Refractor optic

starplot.optics.Reflector(focal_length, eyepiece_focal_length, eyepiece_fov)

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 (float) –

  Focal length (mm) of the telescope

• eyepiece_focal_length (float) –

  Focal length (mm) of the eyepiece

• eyepiece_fov (float) –

  Field of view (degrees) of the eyepiece

Returns:

• Reflector –

  A new instance of a Reflector optic

starplot.optics.Camera(sensor_height, sensor_width, lens_focal_length, rotation=0)

Creates a new Camera optic

Note

Field of view for each dimension is calculated using the following formula:

TFOV = 2 * arctan( d / (2 * f) )

Where:

d = sensor size (height or width)

f = focal length of lens

Parameters:

• sensor_height (float) –

  Height of camera sensor (mm)

• sensor_width (float) –

  Width of camera sensor (mm)

• lens_focal_length (float) –

  Focal length of camera lens (mm)

• rotation (float, default: 0 ) –

  Angle (degrees) to rotate camera

Returns:

• Camera –

  A new instance of a Camera optic