API#

imephu.annotation#

class imephu.annotation.Annotation(*args, **kwargs)[source]#

An annotation to add to a finder chart.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add this annotation to a finder chart.

Parameters

ax (WCSAxes) – Plot axes.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.Annotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north towards the east.

Returns

The annotation resulting from the rotation.

Return type

Annotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.Annotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

Annotation

imephu.annotation.general#

class imephu.annotation.general.ArrowAnnotation(start: astropy.coordinates.sky_coordinate.SkyCoord, end: astropy.coordinates.sky_coordinate.SkyCoord, wcs: astropy.wcs.wcs.WCS, head_width: astropy.coordinates.angles.Angle, head_height: astropy.coordinates.angles.Angle, head_filled: bool = False, tail_shown: bool = True, color: Union[str, Tuple[float, float, float]] = 'black', **kwargs: Any)[source]#

An annotation for plotting an arrow from a start to an end position.

The start of the arrow’s tail and the tip of the arrow’s head are given as sky positions (in right ascension and declination). The width and height of the arrow head are given as an angle on the sky, and this angle is converted to pixels using the pixel scale in right ascension direction.

By default the arrow is not filled, but you can change this behavior with the head_filled parameter.

Parameters

  • start (SkyCoord) – Position of the arrow tail’s start.

  • end (SkyCoord) – Position of the arrow head’s tip.

  • wcs (WCS) – WCS object.

  • head_width (Angle) – Width of the arrow head.

  • head_height (Angle) – Height of the arrow head.

  • head_filled (bool, default: False) – Whether the arrow head is filled.

  • tail_shown (bool, default: True) – Whether the tail should be shown. If False, only the head is displayed.

  • color (color, default: "black") – The arrow color.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to the LinePathAnnotation constructor for both tail and head.

class imephu.annotation.general.CircleAnnotation(center: astropy.coordinates.sky_coordinate.SkyCoord, radius: astropy.coordinates.angles.Angle, wcs: astropy.wcs.wcs.WCS, edgecolor: Union[str, Tuple[float, float, float]] = 'black', facecolor: Union[str, Tuple[float, float, float]] = 'none', **kwargs: Any)[source]#

An annotation for adding a circle to a plot.

The radius of the circle is given as an angular distance on the sky, in the direction of the right ascension. A circle is drawn irrespective of the pixel scales for right ascension and declination. Hence the circle in general is not a circle on the sky but just on the finder chart.

Parameters

  • center (SkyCoord) – The right ascension and declination of the circle’s center.

  • radius (Angle) – The radius of the circle, as an angular distance on the sky in right ascension direction.

  • wcs (WCS) – WCS object.

  • edgecolor (color, default: "black") – The edge color.

  • facecolor (color, default: "none") – The filling color.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to Matplotlib’s Circle patch constructor.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add the circle to a finder chart.

ax: WCSAxes

WCS axes object.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.general.circle.CircleAnnotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north to east.

Returns

The annotation resulting from the rotation.

Return type

CircleAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.general.circle.CircleAnnotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

CircleAnnotation

class imephu.annotation.general.CrosshairsAnnotation(center: astropy.coordinates.sky_coordinate.SkyCoord, size: astropy.coordinates.angles.Angle, wcs: astropy.wcs.wcs.WCS, color: Union[str, Tuple[float, float, float]] = 'black', **kwargs: Any)[source]#

An annotation for plotting crosshairs.

The crosshairs are defined by their center (i.e. where the two lines intersect), the size (i.e. the length of the lines) and the angle of rotation around the center.

The lines bisect each other. The crosshair lines are in the direction of right ascension and declination.

Parameters

  • center (SkyCoord) – The center of the crosshairs, i.e. the point of intersection of the two lines, as a position on the sky (in right ascension and declination).

  • size (Angle) – The length of each line, as an angle on the sky.

  • wcs (WCS) – WCS object.

  • color (color, default: "black") – The line color.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to Matplotlib’s PathPatch patch constructor.

class imephu.annotation.general.EmptyAnnotation(*args, **kwargs)[source]#

An annotation for adding nothing to a finder chart.

In other words, this annotation just leaves the finder chart as is.

This is a convenience class for cases where you formally need to pass an annotation, but there is nothing to annotate with.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add nothing to a finder chart, leaving it as is.

ax: WCSAxes

WCS axes object.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.Annotation[source]#

Return a copy of this annotation.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north to east.

Returns

A copy of this annotation.

Return type

CircleAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.Annotation[source]#

Return a copy of this annotation.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

A copy of this annotation.

Return type

CircleAnnotation

class imephu.annotation.general.GroupAnnotation(items: Sequence[imephu.annotation.Annotation])[source]#

An annotation made of a group of annotations.

The annotation comprises a list of annotation items. Any of the Annotation methods are applied to all the items in the list, in the order the items appear in the list. So, for example, the apply_to method calls the apply_to method for all list items, starting from the first item in the list and finishing with the last item.

Annotations can be added to the group when calling the constructor or by using the add_item method afterwards.

Parameters

items (sequence of Annotation) – The initial list of group items.

add_item(item: imephu.annotation.Annotation) → None[source]#

Add an annotation to this group.

Parameters

item (Annotation) – Annotation to add to this group.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add this annotation to a finder chart.

Parameters

ax (WCSAxes) – Plot axes.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.general.group.GroupAnnotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north towards the east.

Returns

The annotation resulting from the rotation.

Return type

GroupAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.general.group.GroupAnnotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

GroupAnnotation

class imephu.annotation.general.LinePathAnnotation(vertices: Sequence[astropy.coordinates.sky_coordinate.SkyCoord], wcs: astropy.wcs.wcs.WCS, closed: bool = True, edgecolor: Union[str, Tuple[float, float, float]] = 'black', facecolor: Union[str, Tuple[float, float, float]] = 'none', **kwargs: Any)[source]#

An annotation consisting of straight lines between vertices.

The path displayed by this annotation is defined by a set of vertices, which are connected by straight lines on the finder chart. (The connecting lines in general will refer to curved lines on the sky.)

By default the path is assumed to be closed, i.e. the last vertex is connected to the first by a line. This behavior may be changed with the closed parameter.

Parameters

  • vertices (sequence of SkyCoord) – The path vertices, as an array or sequence of sky coordinates (with right ascension abd declination).

  • wcs (WCS) – WCS object.

  • closed (bool, default: True) – Whether the the path is closed, i.e. whether the last vertex is connected to the first by a line.

  • edgecolor (color, default: "black") – The edge color.

  • facecolor (color, default: "none") – The filling color.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to Matplotlib’s PathPatch patch constructor.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add the line path to a finder chart.

Parameters

ax (WCSAxes) – Plot axes.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.general.line_path.LinePathAnnotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north towards the east.

Returns

The annotation resulting from the rotation.

Return type

LinePathAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.general.line_path.LinePathAnnotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

LinePathAnnotation

class imephu.annotation.general.RectangleAnnotation(center: astropy.coordinates.sky_coordinate.SkyCoord, width: astropy.coordinates.angles.Angle, height: astropy.coordinates.angles.Angle, wcs: astropy.wcs.wcs.WCS, edgecolor: Union[str, Tuple[float, float, float]] = 'black', facecolor: Union[str, Tuple[float, float, float]] = 'none', **kwargs: Any)[source]#

An annotation for plotting a rectangle on a finder chart.

The rectangle is defined by its center, width and height. The center must be a sky position in right ascension and declination, the width and height must be an angle on the sky. The width is taken to be the extension in the right ascension direction, the height the extension in the declination direction.

The corners of the rectangle are mapped to their corresponding pixel positions on the finder chart. This implies that in general the figure plotted on the finder chart will be a quadrilateral, but not exactly a rectangle.

Note

The center rather than “bottom left” corner is specified, as this is more convenient in the context of finder charts.

Parameters

  • center (SkyCoord) – The center of the rectangle, in right ascension and declination.

  • width (Angle) – The width of the rectangle as an angle on the sky in the direction of the right ascension.

  • height (Angle) – The height of the rectangle as an angle on the sky in the direction of the declination.

  • wcs (WCS) – WCS object.

  • edgecolor (color, default: "black") – The edge color.

  • facecolor (color, default: "none") – The filling color.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to Matplotlib’s PathPatch patch constructor.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.general.rectangle.RectangleAnnotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north towards the east.

Returns

The annotation resulting from the rotation.

Return type

RectangleAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.general.rectangle.RectangleAnnotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

RectangleAnnotation

class imephu.annotation.general.TextAnnotation(position: Union[astropy.coordinates.sky_coordinate.SkyCoord, Sequence[float], numpy.ndarray[Any, numpy.dtype[numpy.float64]]], s: str, wcs: astropy.wcs.wcs.WCS, color: Union[str, Tuple[float, float, float]] = 'black', horizontalalignment: Literal['center', 'left', 'right'] = 'center', verticalalignment: Literal['baseline', 'bottom', 'center', 'center_baseline', 'top'] = 'center', clip_on: bool = True, **kwargs: Any)[source]#

An annotation for adding text to a plot.

The text position can be specified as a position on the sky (as an instance of SkyCoord) or as a point in axes coordinates (as an array of float values. Axes coordinates range from (0, 0) (bottom left of the axes) to (1, 1) (top right of the axes).

You can only rotate and translate the annotation if the text position is specified as a position on the sky.

Note

The rotate method rotates the text position, but not the text itself. If you want to rotate the text rather than the text position, you should use the rotation parameter with the angle in degrees.

Parameters

  • position (SkyCoord or) – The right ascension and declination of the point where to put the text.

  • s (str) – The text.

  • wcs (WCS) – WCS object.

  • color (color, default: "black") – The text color.

  • horizontalalignment ({"center", "left", "right"}, default: "center") – The horizontal alignment of the text.

  • verticalalignment ({"baseline", "bottom", "center", "center_baseline", "top"}, default: "center") – The vertical alignment of the text.

  • clip_on (bool, default: True) – Whether to clip the text at the plot boundaries.

  • **kwargs (dict, optional) – Additional keyword arguments, which will be passed to Matplotlib’s text method for adding text to plot Axes.

add_to(ax: astropy.visualization.wcsaxes.core.WCSAxes) → None[source]#

Add the text to a finder chart.

ax: WCSAxes

WCS axes object.

rotate(pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle) → imephu.annotation.general.text.TextAnnotation[source]#

Rotate this annotation around a pivot and return the result.

The rotation angle is an angle on the sky, measured from north to east.

Parameters

  • pivot (SkyCoord) – Point around which to rotate the annotation.

  • angle (Angle) – Angle of rotation, measured from north to east.

Returns

The annotation resulting from the rotation.

Return type

TextAnnotation

translate(displacement: astropy.coordinates.angles.Angle) → imephu.annotation.general.text.TextAnnotation[source]#

Move this annotation along a displacement vector and return the result.

Parameters

displacement (2D array of angles) – The displacement by which to move the annotation.

Returns

The annotation resulting from the translation.

Return type

TextAnnotation

imephu.geometry#

imephu.geometry.pixel_scales(wcs: astropy.wcs.wcs.WCS) → Tuple[astropy.coordinates.angles.Angle, astropy.coordinates.angles.Angle][source]#

Calculate the pixel scales of a WCS object.

For a WCS returns pixel scales along each axis of the image pixel at the CRPIX location once it is projected onto the “plane of intermediate world coordinates” as defined in Greisen & Calabretta 2002, A&A, 395, 1061.

Note

This function is concerned only about the transformation “image plane”->”projection plane” and not about the transformation “celestial sphere”->”projection plane”->”image plane”. Therefore, this function ignores distortions arising due to non-linear nature of most projections.

Note

In order to compute the scales corresponding to celestial axes only, make sure that the input WCS object contains celestial axes only, e.g., by passing in the celestial WCS object.

The code has been adapted from APLpy.

Parameters

wcs (WCS) – A world coordinate system object.

Returns

scale – A vector (ndarray) of projection plane increments corresponding to each pixel side (axis). The units of the returned results are the same as the units of cdelt, crval, and cd for the celestial WCS and can be obtained by inquiring the value of cunit property of the input WCS WCS object.

Return type

tuple of Angle

See also

astropy.wcs.utils.proj_plane_pixel_area

imephu.geometry.pixel_to_sky_position(position_px: numpy.ndarray[Any, numpy.dtype[numpy.float64]], wcs: astropy.wcs.wcs.WCS) → astropy.coordinates.sky_coordinate.SkyCoord[source]#

Convert pixel coordinates to the corresponding sky position.

Parameters

  • position_px (ndarray of float) – Pixel coordinates.

  • wcs (WCS) – WCS object.

Returns

The sky coordinates.

Return type

SkyCoord

imephu.geometry.rotate(v: astropy.coordinates.sky_coordinate.SkyCoord, pivot: astropy.coordinates.sky_coordinate.SkyCoord, angle: astropy.coordinates.angles.Angle, wcs: astropy.wcs.wcs.WCS) → astropy.coordinates.sky_coordinate.SkyCoord[source]#

Rotate a point around a pivot.

Both the pivot and the point to rotate are assumed to be given as right ascension and declination. The rotation angle is taken to be the angle on the sky. If the pixel scales for right ascension and declination differ, the angle seen on the finder chart will differ from this angle.

The angle is measured from north to south. Hence it depends on the orientation of the coordinate axes whether a positive angle corresponds to a clockwise or anti-clockwise orientation.

Parameters

  • v (SkyCoord) – The point to rotate.

  • pivot (SkyCoord) – The point around which the point v is rotated.

  • angle (Angle) – The angle of rotation, measured from north to east.

  • wcs (WCS) – WCS object.

Returns

The point after the rotation.

Return type

SkyCoord

imephu.geometry.sky_position_to_pixel(position: astropy.coordinates.sky_coordinate.SkyCoord, wcs: astropy.wcs.wcs.WCS) → numpy.ndarray[Any, numpy.dtype[numpy.float64]][source]#

Convert a sky position to the corresponding pixel coordinates.

Parameters

  • position (SkyCoord) – Sky position as right ascension and declination.

  • wcs (WCS) – WCS object.

Returns

The pixel coordinates.

Return type

ndarray of float

imephu.geometry.translate(v: astropy.coordinates.sky_coordinate.SkyCoord, displacement: astropy.coordinates.angles.Angle) → astropy.coordinates.sky_coordinate.SkyCoord[source]#

Move a point by a displacement vector.

The point to move is assumed to be given as right ascension and declination. The displacement vector is assumed to be a vector on the sky, with real angles, as described for the sky_vector_to_pixel method.

Parameters

  • v (SkyCoord) – Point to move.

  • displacement (2D array of angles) – Vector by which to move the point.

Returns

The point after moving.

Return type

SkyCoord

imephu.finder_chart#

class imephu.finder_chart.FinderChart(name: Union[str, BinaryIO, os.PathLike[Any]])[source]#

A finder chart for an astronomical observation.

The finder chart is generated from a FITS file. By default the finder chart just shows the region with an overlaid coordinate grid. The axes show WCS coordinates. Use the add_annotation method to add more content to the finder chart.

You can display the finder chart on the screen or save it as a file.

This class uses Matplotlib for generating the finder chart.

Warning

Be careful when working with several finder charts as all the finder charts use the same Matplotlib figure.

Parameters

name (str, path-like or binary file-like) – FITS file to display.

add_annotation(annotation: imephu.annotation.Annotation) → None[source]#

Add an annotation to the finder chart.

Annotations will be plotted onto the finder chart in the order they have been added. So, for example, the annotation added last will be output on top of all the other annotations.

static for_time_interval(start: datetime.datetime, end: datetime.datetime, ephemerides: List[imephu.utils.Ephemeris], max_track_length: astropy.coordinates.angles.Angle, create_finder_chart: Callable[[List[imephu.utils.Ephemeris]], imephu.finder_chart.FinderChart]) → Generator[Tuple[imephu.finder_chart.FinderChart, Tuple[datetime.datetime, datetime.datetime]], None, None][source]#

Create finder charts for a time interval.

This method is intended for non-sidereal targets, which may require multiple finder charts to cover their track over a time interval. It creates finder charts according to the following rules:

  • Taken together, the finder charts cover the whole time interval.

  • The track length on each finder chart does not exceed max_track_length.

  • Each finder chart is created using create_finder_chart.

The method is completely agnostic as to what a finder chart should look like; this decision is left completely to create_finder_chart. In particular, if you need any annotations for the non-sidereal nature, it is up to create_finder_chart to provide them.

The create_finder_chart function has to accept two arguments, in this order:

  • The center of the finder chart as a position on the sky, in right ascension and declination.

  • The list of ephemerides to include on the finder chart (for example when using an annotation to indicate the target motion).

The finder charts are returned along with the time interval they cover.

Parameters

  • start (datetime) – The start time of the interval to be covered by the finder charts. This must be a timezone-aware datetime.

  • end (datetime) – The end time of the interval to be covered by the finder charts. This must be a timezone-aware datetime.

  • ephemerides (list of Ephemeris) – The list of ephemerides. The time interval from start to end must be fully covered by the ephemerides.

  • max_track_length (float) – The maximum length a track may have on a finder chart, as an angle on the sky.

  • create_finder_chart (function) – The function for creating a finder chart from a list of ephemerides.

Yields

tuple of a FinderChart and a datetime interval – The generated finder charts along with the time intervals they cover.

static from_survey(survey: str, fits_center: astropy.coordinates.sky_coordinate.SkyCoord, size: astropy.coordinates.angles.Angle) → imephu.finder_chart.FinderChart[source]#

Create a finder chart from a sky survey FITS image.

Parameters

  • survey (str) – The name of the survey to query for the FITS file.

  • fits_center (SkyCoord) – The center position of the loaded FITS file.

  • size (Angle) – The width and height of the FITS file image, as an angle on the sky.

save(name: Union[str, BinaryIO, os.PathLike[str], os.PathLike[bytes]], format: Optional[str] = None) → None[source]#

Save the finder chart in a file.

If format is not set, the file extension of name is used to figure out the file or, if there is no extension, Matplotlib’s default is used. See Matplotlib’s matplotlib.pyplot.savefig function for more details regarding the format.

Parameters

  • name (str, path-like or binary file-like) – The file to which the finder chart is saved. An existing file is replaced.

  • format (str, optional) – The format in which to store the finder chart.

show() → None[source]#

Display the finder chart on the screen.

property wcs: astropy.wcs.wcs.WCS#

Return a deep copy of the WCS object of the finder chart.

Returns

A deep copy of the WCS object.

Return type

WCS