`planetmapper`

Hint

See also the page of examples of using the PlanetMapper Python module

PlanetMapper: A Python module for visualising, navigating and mapping Solar System observations.

The core logic of this code is based on conversion between different coordinate systems of interest. The xy and radec coordinate systems define positions from the point of view of the observer while the lonlat coordinate system defines locations on the surface of the target body:

xy: image pixel coordinates. These coordinates count the number of pixels in an observed image with the bottom left pixel defined as (0,0), and the x and y coordinates defined as normal. Integer coordinates represent the middle of the corresponding pixel, so (0, 3) covers x values from -0.5 to 0.5 and y values from 2.5 to 3.5.

radec: observer frame RA/Dec sky coordinates. These are the right ascension and declination which define the position in the sky of a point from the point of view of the observer. These coordinates are expressed in degrees. See Wikipedia for more details.

lonlat: planetographic coordinates on target body. These are the planetographic longitude and latitude coordinates of a point on the surface of the target body. These coordinates are expressed in degrees. See Wikipedia and the SPICE documentation for more details.

km: defines the distance in the image plane from the centre of the target body in km with the target’s north pole pointing up. This coordinate system is similar to the radec and xy coordinate systems, but has the image zoomed so that the planet’s radius is fixed and rotated so that the north pole points up. It can therefore be useful for comparing observations of the same target taken at different times.

Dimension	Unit
Angles (RA, Dec, longitude, latitude…)	degrees
Angles (target angular diameter, plate scale)	arcseconds [1]
Distances	km
Time intervals	seconds
Speeds	km/s
Dates (timezone)	UTC

Note

By default, all angles should be degrees unless using a function/value explicitly named with _arcsec or _radians. Note that angles in SPICE are radians, so extra care should be taken converting to/from SPICE values.

These additional coordinate systems are mainly used for internal calculations and to interface with SPICE:

targvec - target frame rectangular vector.
obsvec - observer frame (e.g. J2000) rectangular vector.
obsvec_norm - normalised observer frame rectangular vector.
rayvec - target frame rectangular vector from observer to point.

This code makes extensive use of the the spiceypy package which provides a Python wrapper around NASA’s cspice toolkit. See the spiceypy documentation and the SPICE documentation for more information.

Warning

This code is in active development, so may contain bugs! Any issues, bugs and suggestions can be reported on GitHub.

planetmapper.set_kernel_path(path: str | None) → None[source]

Set the path of the directory containing SPICE kernels. See the kernel directory documentation for more detail.

Parameters:: path – Directory which PlanetMapper will search for SPICE kernels. If None, then the default value of '~/spice_kernels/' will be used.

planetmapper.get_kernel_path(return_source: bool = False) → str | tuple[str, str][source]

Get the path of the directory of SPICE kernels used in PlanetMapper.

If a kernel path has been manually set using set_kernel_path(), then this path is used.
Otherwise the value of the environment variable PLANETMAPPER_KERNEL_PATH is used.
If PLANETMAPPER_KERNEL_PATH is not set, then the default value, '~/spice_kernels/' is used.

Parameters:: return_source – If True, return a tuple of the kernel path and a string which indicates the source of the kernel path. If False (the default), return only the kernel path. The possible source strings are: 'set_kernel_path()', 'PLANETMAPPER_KERNEL_PATH', and 'default'.
Returns:: The path of the directory of SPICE kernels used in PlanetMapper. If return_source is True, then a tuple of the kernel path and a string indicating the source of the kernel path is returned.

class planetmapper.SpiceBase(show_progress: bool = False, optimize_speed: bool = True, auto_load_kernels: bool = True, kernel_path: str | None = None, manual_kernels: None | list[str] = None)[source]

Bases: object

Class containing methods to interface with spice and manipulate coordinates.

This is the base class for all the main classes used in planetmapper.

Parameters:

show_progress – Show progress bars for long running processes. This is mainly useful for complex functions in derived classes, such as backplane generation in BodyXY. These progress bars can be quite messy, but can be useful to keep track of very long operations.
optimize_speed – Toggle speed optimizations. For typical observations, the optimizations can make code significantly faster with no effect on accuracy, so should generally be left enabled.
auto_load_kernels – Toggle automatic kernel loading with load_spice_kernels().
kernel_path – Passed to load_spice_kernels() if load_kernels is True. It is recommended to use set_kernel_path() instead of passing this argument.
manual_kernels – Passed to load_spice_kernels() if load_kernels is True. It is recommended to use planetmapper.base.prevent_kernel_loading() then manually load kernels yourself instead of passing this argument.

copy() → Self[source]: Return a copy of this object.

standardise_body_name(name: str | int) → str[source]

Return a standardised version of the name of a SPICE body.

This converts the provided name into the SPICE ID code with spice.bods2c, then back into a string with spice.bodc2s. This standardises to the version of the name preferred by SPICE. For example, 'jupiter', 'JuPiTeR', ' Jupiter ', '599' and 599 are all standardised to 'JUPITER'

Parameters:: name – The name of a body (e.g. a planet). This can also be the numeric ID code of a body.
Returns:: Standardised version of the body’s name preferred by SPICE.
Raises:: NotFoundError – If SPICE does not recognise the provided name

et2dtm(et: float) → datetime[source]

Convert ephemeris time to a Python datetime object.

Parameters:: et – Ephemeris time in seconds past J2000.
Returns:: Timezone aware (UTC) datetime corresponding to et.

static mjd2dtm(mjd: float) → datetime[source]

Convert Modified Julian Date into a python datetime object.

Parameters:: mjd – Float representing MJD.
Returns:: Python datetime object corresponding to mjd. This datetime is timezone aware and set to the UTC timezone.

speed_of_light() → float[source]

Return the speed of light in km/s. This is a convenience function to call spice.clight().

Returns:: Speed of light in km/s.

calculate_doppler_factor(radial_velocity: Numeric) → Numeric[source]

Calculates the doppler factor caused by a target’s radial velocity relative to the observer. This doppler factor, $D$ can be used to calculate the doppler shift caused by this velocity as $\lambda_r = \lambda_e D$ where $\lambda_r$ is the wavelength received by the observer and $\lambda_e$ is the wavelength emitted at the target.

This doppler factor is calculated as $D = \sqrt{\frac{1 + v/c}{1 - v/c}}$ where $v$ is the input radial_velocity and $c$ is the speed of light.

Parameters:: radial_velocity – Radial velocity in km/s with positive values corresponding to motion away from the observer. This can be a single float value or a numpy array containing multiple velocity values.
Returns:: Doppler factor calculated from input radial velocity. If the input radial_velocity is a single value, then a float is returned. If the input radial_velocity is a numpy array, then a numpy array of doppler factors is returned.

static load_spice_kernels(kernel_path: str | None = None, manual_kernels: None | list[str] = None, only_if_needed: bool = True) → None[source]

Attempt to intelligently SPICE kernels using planetmapper.base.load_kernels().

If manual_kernels is None (the default), then all kernels in the directory given by kernel_path which match the following patterns are loaded:

**/*.bsp
**/*.tpc
**/*.tls

Note that these patterns match an arbitrary number of nested directories (within kernel_path). If more control is required, you can instead specify a list of specific kernels to load with manual_kernels.

Hint

See the SPICE kernel documentation for more detail about downloading SPICE kernels and the automatic kernel loading behaviour.

Parameters:

kernel_path – Path to directory where kernels are stored. If this is None (the default) then the result of get_kernel_path() is used. It is usually recommended to use one of the methods described in the kernel directory documentation rather than using this kernel_path argument.
manual_kernels – Optional manual list of paths to kernels to load instead of using kernel_path.
only_if_needed – If this is True, kernels will only be loaded once per session.

static close_loop(arr: ndarray) → ndarray[source]

Return copy of array with first element appended to the end.

This is useful for cases like plotting the limb of a planet where the array of values forms a loop with the first and last values in arr adjacent to each other.

Parameters:: arr – Array of values of length $n$.
Returns:: Array of values of length $n + 1$ where the final value is the same as the first value.

static unit_vector(v: ndarray) → ndarray[source]

Return normalised copy of a vector.

For an input vector $\vec{v}$, return the unit vector $\hat{v} = \frac{\vec{v}}{|\vec{v}|}$.

Parameters:: v – Input vector to normalise.
Returns:: Normalised vector which is parallel to v and has a magnitude of 1.

static vector_magnitude(v: ndarray) → float[source]

Return the magnitude of a vector.

For an input vector $\vec{v}$, return magnitude $|\vec{v}| = \sqrt{\sum{v_i^2}}$.

Parameters:: v – Input vector.
Returns:: Magnitude (length) of vector.

static angular_dist(ra1: float, dec1: float, ra2: float, dec2: float) → float[source]

Calculate the angular distance between two RA/Dec coordinate pairs.

Parameters:

ra1 – RA of first point.
dec1 – Dec of first point.
ra2 – RA of second point
dec2 – Dec of second point.

Returns:

Angular distance in degrees between the two points.

class planetmapper.Body(target: str | int, utc: str | datetime.datetime | float | None = None, observer: str | int = 'EARTH', *, aberration_correction: str = 'CN', observer_frame: str = 'J2000', illumination_source: str = 'SUN', subpoint_method: str = 'INTERCEPT/ELLIPSOID', surface_method: str = 'ELLIPSOID', **kwargs)[source]

Bases: BodyBase

Class representing an astronomical body observed at a specific time.

Generally only target, utc and observer need to be changed. The additional parameters allow customising the exact settings used in the internal SPICE functions. Similarly, some methods (e.g. terminator_radec()) have parameters that are passed to SPICE functions which can almost always be left as their default values. See the SPICE documentation for more details about possible parameter values.

The target and observer names are passed to SpiceBase.standardise_body_name(), so a variety of formats are acceptable. For example 'jupiter', 'JUPITER', ' Jupiter ', '599' and 599 will all resolve to 'JUPITER'.

Body instances are hashable, so can be used as dictionary keys.

This class inherits from SpiceBase so the methods described above are also available.

Parameters:

target – Name of target body.
utc – Time of observation. This can be provided in a variety of formats and is assumed to be UTC unless otherwise specified. The accepted formats are: any string datetime representation compatible with SPICE (e.g. '2000-12-31T23:59:59' - see the documentation of acceptable string formats), a Python datetime object, or a float representing the Modified Julian Date (MJD) of the observation. Alternatively, if utc is None (the default), then the current time is used.
observer – Name of observing body. Defaults to 'EARTH'.
aberration_correction – Aberration correction used to correct light travel time in SPICE. Defaults to 'CN'.
observer_frame – Observer reference frame. Defaults to 'J2000',
illumination_source – Illumination source. Defaults to 'SUN'.
subpoint_method – Method used to calculate the sub-observer point in SPICE. Defaults to 'INTERCEPT/ELLIPSOID'.
surface_method – Method used to calculate surface intercepts in SPICE. Defaults to 'ELLIPSOID'.
**kwargs – Additional arguments are passed to SpiceBase.

target: str: Name of the target body, as standardised by SpiceBase.standardise_body_name().

utc: str: String representation of the time of the observation in the format '2000-01-01T00:00:00.000000'. This time is in the UTC timezone.

observer: str: Name of the observer body, as standardised by SpiceBase.standardise_body_name().

aberration_correction: str: Aberration correction used to correct light travel time in SPICE.

observer_frame: str: Observer reference frame.

et: float: Ephemeris time of the observation corresponding to utc.

dtm: datetime.datetime: Python timezone aware datetime of the observation corresponding to utc.

target_body_id: int: SPICE numeric ID of the target body.

target_light_time: float: Light time from the target to the observer at the time of the observation.

target_distance: float: Distance from the target to the observer at the time of the observation.

target_ra: float: Right ascension (RA) of the target centre.

target_dec: float: Declination (Dec) of the target centre.

illumination_source: str: Illumination source.

subpoint_method: str: Method used to calculate the sub-observer point in SPICE.

surface_method: str: Method used to calculate surface intercepts in SPICE.

radii: np.ndarray: Array of radii of the target body along the x, y and z axes in km.

r_eq: float: Equatorial radius of the target body in km.

r_polar: float: Polar radius of the target body in km.

flattening: float: Flattening of target body, calculated as (r_eq - r_polar) / r_eq.

prograde: bool: Boolean indicating if the target’s spin sense is prograde or retrograde.

positive_longitude_direction: Literal['E', 'W']

Positive direction of planetographic longitudes. 'W' implies positive west planetographic longitudes and 'E' implies positive east longitudes.

This is determined from the target’s spin sense (i.e. from prograde), with positive west longitudes for prograde rotation and positive east for retrograde. The earth, moon and sun are exceptions to this and are defined to have positive east longitudes

For more details, see https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/pgrrec_c.html#Particulars

target_diameter_arcsec: float: Equatorial angular diameter of the target in arcseconds.

subpoint_distance: float: Distance from the observer to the sub-observer point on the target.

subpoint_lon: float: Longitude of the sub-observer point on the target.

subpoint_lat: float: Latitude of the sub-observer point on the target.

subsol_lon: float: Longitude of the sub-solar point on the target.

subsol_lat: float: Latitude of the sub-solar point on the target.

named_ring_data: dict[str, list[float]]

Dictionary of ring radii for the target from data_loader.get_ring_radii().

The dictionary keys are the names of the rings, and values are list of ring radii in km. If the length of this list is 2, then the values give the inner and outer radii of the ring respectively. Otherwise, the length should be 1, meaning the ring has a single radius. These ring radii values are sourced from planetary factsheets. If no ring data is available for the target, this dictionary is empty.

Values from this dictionary can be easily accessed using the convenience function ring_radii_from_name().

ring_radii: set[float]

Set of ring radii in km to plot around the target body’s equator. Each radius is plotted as a single line, so for a wide ring you may want to add both the inner and outer edger of the ring. The radii are defined as the distance from the centre of the target body to the ring. For Saturn, the A, B and C rings from named_ring_data are included by default. For all other bodies, ring_radii is empty by default.

Ring radii data from the named_ring_data can easily be added to ring_radii using add_named_rings(). Example usage:

body.ring_radii.add(122340) # Add new ring radius to plot
body.ring_radii.add(136780) # Add new ring radius to plot
body.ring_radii.update([66900, 74510]) # Add multiple radii to plot at once

body.ring_radii.remove(122340) # Remove a ring radius
body.ring_radii.clear() # Remove all ring radii

# Add specific ring radii using data from planetary factsheets
body.add_named_rings('main', 'halo')

# Add all rings defined in the planetary factsheets
body.add_named_rings()

See also BodyXY.backplanes.

Parameters:

name – Short name identifying the backplane. This is used as the EXTNAME for the backplane when saving FITS files in Observation.save().
description – More detailed description of the backplane (e.g. including units).
get_img – Function which takes no arguments returns a numpy array containing a backplane image when called. This should generally be a method such as BodyXY.get_lon_img().
get_map – Function returns a numpy array containing a map of backplane values when called. This should take map projection keyword arguments, as described in BodyXY.generate_map_coordinates(). This function should generally be a method such as BodyXY.get_lon_map().

name: str: Alias for field number 0

description: str: Alias for field number 1

get_img: Callable[[], ndarray]: Alias for field number 2

get_map: _BackplaneMapGetter: Alias for field number 3

class planetmapper.BodyXY(target: str, utc: str | datetime.datetime | float | None = None, nx: int = 0, ny: int = 0, *, sz: int | None = None, **kwargs)[source]

Bases: Body

Class representing an astronomical body imaged at a specific time.

This is a subclass of Body with additional methods to interact with the image pixel coordinate frame xy. This class assumes the tangent plane approximation is valid for the conversion between pixel coordinates xy and RA/Dec sky coordinates radec.

The xy ↔ radec conversion is performed by setting the pixel coordinates of the centre of the planet’s disc (x0, y0), the (equatorial) pixel radius of the disc r0 and the rotation of the disc. These disc parameters can be adjusted using methods such as set_x0() and retrieved using methods such as get_x0(). It is important to note that conversions involving xy image pixel coordinates (e.g. backplane image generation) will produce different results before and after these disc parameter values are adjusted.

For larger images, the generation of backplane images can be computationally intensive and take a large amount of time to execute. Therefore, intermediate results are cached to make sure that the slowest parts of code are only called when needed. This cache is managed automatically, so the user never needs to worry about dealing with it. The cache behaviour can be seen in apparently similar lines of code having very different execution times:

# Create a new object
body = planetmapper.BodyXY('Jupiter', '2000-01-01', sz=500)
body.set_disc_params(x0=250, y0=250, r0=200)
# At this point, the cache is completely empty

# The intermediate results used in generating the incidence angle backplane
# are cached, speeding up any future calculations which use these
# intermediate results:
body.get_backplane_img('INCIDENCE') # Takes ~10s to execute
body.get_backplane_img('INCIDENCE') # Executes instantly
body.get_backplane_img('EMISSION') # Executes instantly

# When any of the disc parameters are changed, the xy <-> radec conversion
# changes so the cache is automatically cleared (as the cached intermediate
# results are no longer valid):
body.set_r0(190) # This automatically clears the cache
body.get_backplane_img('EMISSION') # Takes ~10s to execute
body.get_backplane_img('INCIDENCE') # Executes instantly

You can optionally display a progress bar for long running processes like backplane generation by show_progress=True when creating a BodyXY instance (or any other instance which derives from SpiceBase).

The size of the image can be specified by using the nx and ny parameters to specify the number of pixels in the x and y dimensions of the image respectively. If nx and ny are equal (i.e. the image is square), then the parameter sz can be used instead to set both nx and ny, where BodyXY(..., sz=50) is equivalent to BodyXY(..., nx=50, ny=50).

If nx and ny are not set, then some functionality (such as generating backplane images) will not be available and will raise a ValueError if called.

BodyXY instances are mutable and therefore not hashable, meaning that they cannot be used as dictionary keys. to_body() can be used to create a Body instance which is hashable.

Parameters:

target – Name of target body, passed to Body.
utc – Time of observation, passed to Body.
observer – Name of observing body, passed to Body.
nx – Number of pixels in the x dimension of the image.
ny – Number of pixels in the y dimension of the image.
sz – Convenience parameter to set both nx and ny to the same value. BodyXY(..., sz=50) is equivalent to BodyXY(..., nx=50, ny=50). If sz is defined along with nx or ny then a ValueError is raised.
**kwargs – Additional arguments are passed to Body.

backplanes: dict[str, Backplane]

Dictionary containing registered backplanes which can be used to calculate properties (e.g. longitude/latitude, illumination angles etc.) for each pixel in the image.

By default, this dictionary contains a series of default backplanes. These can be summarised using print_backplanes(). Custom backplanes can be added using register_backplane().

Generated backplane images can be easily retrieved using get_backplane_img() and plotted using plot_backplane_img(). Similarly, backplane maps cen be retrieved using get_backplane_map() and plotted using plot_backplane_map().

This dictionary of backplanes can also be used directly if more customisation is needed:

# Retrieve the image containing right ascension values
ra_image = body.backplanes['RA'].get_img()

# Retrieve the map containing emission angles on the target's surface
emission_map = body.backplanes['EMISSION'].get_img()

# Print the description of the doppler factor backplane
print(body.backplanes['DOPPLER'].description)

# Remove the distance backplane from an instance
del body.backplanes['DISTANCE']

# Print summary of all registered backplanes
print(f'{len(body.backplanes)} backplanes currently registered:')
for bp in body.backplanes.values():
    print(f'    {bp.name}: {bp.description}')

See Backplane for more detail about interacting with the backplanes directly.

Note that a generated backplane image will depend on the disc parameters (x0, y0, r0, rotation) at the time the backplane is generated (e.g. calling body.backplanes['LAT-GRAPHIC'].get_img() or using get_backplane_img()). Generating the same backplane when there are different disc parameter values will produce a different image.

This dictionary is used to define the backplanes saved to the output FITS file in Observation.save().

classmethod from_body(body: Body, nx: int = 0, ny: int = 0, *, sz: int | None = None) → Self[source]

Create a BodyXY instance with the same parameters as a Body instance.

Parameters:

body – Body instance to convert.
nx – Number of pixels in the x dimension of the image.
ny – Number of pixels in the y dimension of the image.
sz – Convenience parameter to set both nx and ny to the same value.

Returns:

BodyXY instance with the same parameters as the input Body instance and the specified image dimensions.

to_body() → Body[source]

Create a Body instance from a BodyXY instance.

Returns:: Body instance with the same parameters as the input BodyXY instance.

xy2radec(x: float, y: float) → tuple[float, float][source]

Convert image pixel coordinates to RA/Dec sky coordinates.

Parameters:

x – Image pixel coordinate in the x direction.
y – Image pixel coordinate in the y direction.

Returns:

(ra, dec) tuple containing the RA/Dec coordinates of the point.

radec2xy(ra: float, dec: float) → tuple[float, float][source]

Convert RA/Dec sky coordinates to image pixel coordinates.

Parameters:

ra – Right ascension of point in the sky of the observer
dec – Declination of point in the sky of the observer.

Returns:

(x, y) tuple containing the image pixel coordinates of the point.

xy2lonlat(x: float, y: float, **kwargs) → tuple[float, float][source]

Convert image pixel coordinates to longitude/latitude coordinates on the target body.

Parameters:

x – Image pixel coordinate in the x direction.
y – Image pixel coordinate in the y direction.
**kwargs – Additional arguments are passed to Body.radec2lonlat().

Returns:

(lon, lat) tuple containing the longitude and latitude of the point. If the provided pixel coordinates are missing the target body, then the lon and lat values will both be NaN (see Body.radec2lonlat()).

lonlat2xy(lon: float, lat: float) → tuple[float, float][source]

Convert longitude/latitude on the target body to image pixel coordinates.

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.

Returns:

(x, y) tuple containing the image pixel coordinates of the point.

xy2km(x: float, y: float) → tuple[float, float][source]

Convert image pixel coordinates to distances in the target plane.

Parameters:

x – Image pixel coordinate in the x direction.
y – Image pixel coordinate in the y direction.

Returns:

(km_x, km_y) tuple containing distances in km in the target plane in the East-West and North-South directions respectively.

km2xy(km_x: float, km_y: float) → tuple[float, float][source]

Convert distances in the target plane to image pixel coordinates.

Parameters:

km_x – Distance in target plane in km in the East-West direction.
km_y – Distance in target plane in km in the North-South direction.

Returns:

(x, y) tuple containing the image pixel coordinates of the point.

set_disc_params(x0: float | None = None, y0: float | None = None, r0: float | None = None, rotation: float | None = None) → None[source]

Convenience function to set multiple disc parameters at once.

For example, body.set_disc_params(x0=10, r0=5) is equivalent to calling body.set_x0(10) and body.set_r0(5). Any unspecified parameters will be left unchanged.

Parameters:

x0 – If specified, passed to set_x0().
y0 – If specified, passed to set_y0().
r0 – If specified, passed to set_r0().
rotation – If specified, passed to set_rotation().

adjust_disc_params(dx: float = 0, dy: float = 0, dr: float = 0, drotation: float = 0) → None[source]

Convenience function to adjust disc parameters.

This can be used to easily add an offset to disc parameter values without having to call multiple set_... and get_... functions. For example,

body.adjust_disc_params(dy=-3.1, drotation=42)

is equivalent to

body.set_y0(body.get_y0() - 3.1)
body.set_rotation(body.get_rotation() + 42)

The default values of all the arguments are zero, so any unspecified values (e.g. dx and dr in the example above) are unchanged.

Parameters:

dx – Adjustment to x0.
dy – Adjustment to y0.
dr – Adjustment to r0.
drotation – Adjustment to rotation.

get_disc_params() → tuple[float, float, float, float][source]

Convenience function to get all disc parameters at once.

Returns:: (x0, y0, r0, rotation) tuple.

centre_disc() → None[source]

Centre the target’s planetary disc and make it fill ~90% of the observation.

This adjusts x0 and y0 so that they lie in the centre of the image, and r0 is adjusted so that the disc fills 90% of the shortest side of the image. For example, if nx = 20 and ny = 30, then x0 will be set to 10, y0 will be set to 15 and r0 will be set to 9. The rotation of the disc is unchanged.

set_x0(x0: float) → None[source]

Parameters:: x0 – New x pixel coordinate of the centre of the target body.
Raises:: ValueError – if x0 is not finite.

get_x0() → float[source]

Returns:: x pixel coordinate of the centre of the target body.

set_y0(y0: float) → None[source]

Parameters:: y0 – New y pixel coordinate of the centre of the target body.
Raises:: ValueError – if y0 is not finite.

get_y0() → float[source]

Returns:: y pixel coordinate of the centre of the target body.

set_r0(r0: float) → None[source]

Parameters:: r0 – New equatorial radius in pixels of the target body.
Raises:: ValueError – if r0 is not greater than zero or r0 is not finite.

get_r0() → float[source]

Returns:: Equatorial radius in pixels of the target body.

set_rotation(rotation: float) → None[source]

Set the rotation of the target body.

This rotation defines the angle between the upwards (positive dec) direction in the RA/Dec sky coordinates and the upwards (positive y) direction in the image pixel coordinates.

Parameters:: rotation – New rotation of the target body.
Raises:: ValueError – if rotation is not finite.

get_rotation() → float[source]

Returns:: Rotation of the target body.

set_plate_scale_arcsec(arcsec_per_px: float) → None[source]

Sets the angular plate scale of the observation by changing r0.

Parameters:: arcsec_per_px – Arcseconds per pixel plate scale.

set_plate_scale_km(km_per_px: float) → None[source]

Sets the plate scale of the observation by changing r0.

Parameters:: km_per_px – Kilometres per pixel plate scale at the target body.

get_plate_scale_arcsec() → float[source]

Returns:: Plate scale of the observation in arcseconds/pixel.

get_plate_scale_km() → float[source]

Returns:: Plate scale of the observation in km/pixel at the target body.

set_img_size(nx: int | None = None, ny: int | None = None) → None[source]

Set the nx and ny values which specify the number of pixels in the x and y dimension of the image respectively. Unspecified values will remain unchanged.

Parameters:

nx – If specified, set the number of pixels in the x dimension.
ny – If specified, set the number of pixels in the y dimension.

get_img_size() → tuple[int, int][source]

Get the size of the image in pixels.

Returns:: (nx, ny) tuple containing the number of pixels in the x and y dimension of the image respectively

set_disc_method(method: str) → None[source]

Record the method used to find the coordinates of the target body’s disc. This recorded method can then be used when metadata is saved, such as in Observation.save().

set_disc_method is called automatically by functions which find the disc, such as set_x0() and Observation.centre_disc(), so does not normally need to be manually called by the user.

Parameters:: method – Short string describing the method used to find the disc.

get_disc_method() → str[source]

Retrieve the method used to find the coordinates of the target body’s disc.

Returns:: Short string describing the method.

add_arcsec_offset(dra_arcsec: float = 0, ddec_arcsec: float = 0) → None[source]

Adjust the disc location (x0, y0) by applying offsets in arcseconds to the RA/Dec celestial coordinates.

Parameters:

dra_arcsec – Offset in arcseconds in the positive right ascension direction.
ddec_arcsec – Offset in arcseconds in the positive declination direction.

get_img_limits_radec() → tuple[tuple[float, float], tuple[float, float]][source]

Get the limits of the image coordinates in the RA/Dec coordinate system.

This can be used to set the axis limits of a plot, for example:

xlim, ylim = obs.get_img_limits_radec()
plt.xlim(*xlim)
plt.ylim(*ylim)

Returns:: (ra_left, ra_right), (dec_min, dec_max) tuple containing the minimum and maximum RA and Dec coordinates of the pixels in the image respectively.

get_img_limits_km() → tuple[tuple[float, float], tuple[float, float]][source]

Get the limits of the image coordinates in the target centred plane. See get_img_limits_radec() for more details.

Returns:: (km_x_min, km_x_max), (km_y_min, km_y_max) tuple containing the minimum and maximum target plane distance coordinates of the pixels in the image.

get_img_limits_xy() → tuple[tuple[float, float], tuple[float, float]][source]

Get the limits of the image coordinates. See get_img_limits_radec() for more details.

Returns:: (x_min, x_max), (y_min, y_max) tuple containing the minimum and maximum pixel coordinates of the pixels in the image.

limb_xy(**kwargs) → tuple[numpy.ndarray, numpy.ndarray][source]

Pixel coordinate version of Body.limb_radec().

Parameters:: **kwargs – Passed to Body.limb_radec().
Returns:: (x, y) tuple of coordinate arrays.

limb_xy_by_illumination(**kwargs) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Pixel coordinate version of Body.limb_radec_by_illumination().

Parameters:: **kwargs – Passed to Body.limb_radec_by_illumination().
Returns:: (x_day, y_day, x_night, y_night) tuple of coordinate arrays of the dayside then nightside parts of the limb.

terminator_xy(**kwargs) → tuple[numpy.ndarray, numpy.ndarray][source]

Pixel coordinate version of Body.terminator_radec().

Parameters:: **kwargs – Passed to Body.terminator_radec().
Returns:: (x, y) tuple of coordinate arrays.

visible_lonlat_grid_xy(*args, **kwargs) → list[tuple[numpy.ndarray, numpy.ndarray]][source]

Pixel coordinate version of Body.visible_lonlat_grid_radec().

Parameters:

*args – Passed to Body.visible_lonlat_grid_radec().
**kwargs – Passed to Body.visible_lonlat_grid_radec().

Returns:

List of (x, y) coordinate array tuples.

ring_xy(radius: float, **kwargs) → tuple[numpy.ndarray, numpy.ndarray][source]

Pixel coordinate version of Body.ring_radec().

Parameters:

radius – Radius in km of the ring from the centre of the target body.
**kwargs – Passed to Body.ring_radec().

Returns:

(x, y) tuple of coordinate arrays.

matplotlib_xy2radec_transform(ax: matplotlib.axes._axes.Axes | None = None) → Transform[source]

Get matplotlib transform which converts image pixel coordinates to RA/Dec sky coordinates.

The transform is a mutable object which can be dynamically updated using update_transform() when the radec to xy coordinate conversion changes. This can be useful for plotting data (e.g. an observed image) using image xy coordinates onto an axis using RA/Dec coordinates.

# Plot an observed image on an RA/Dec axis with a wireframe of the target
ax = obs.plot_wireframe_radec()
ax.autoscale_view()
ax.autoscale(False) # Prevent imshow breaking autoscale
ax.imshow(
    img,
    origin='lower',
    transform=obs.matplotlib_xy2radec_transform(ax),
    )

Parameters:: ax – Optionally specify a matplotlib axis to return transform_xy2radec + ax.transData. This value can then be used in the transform keyword argument of a Matplotlib function without any further modification.
Returns:: Matplotlib transformation from xy to radec coordinates.

matplotlib_radec2xy_transform(ax: matplotlib.axes._axes.Axes | None = None) → Transform[source]

matplotlib_xy2km_transform(ax: matplotlib.axes._axes.Axes | None = None) → Transform[source]

matplotlib_km2xy_transform(ax: matplotlib.axes._axes.Axes | None = None) → Transform[source]

update_transform() → None[source]: Update the transformations returned by matplotlib_radec2xy_transform() and matplotlib_xy2radec_transform() to use the latest disc parameter values (x0, y0, r0, rotation).

map_img(img: ndarray, *, interpolation: Literal['nearest', 'linear', 'quadratic', 'cubic'] = 'linear', propagate_nan: bool = True, warn_nan: bool = False, **map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

Project an observed image to a map. See generate_map_coordinates() for details about customising the projection used.

If interpolation is 'linear', 'quadratic' or 'cubic', the map projection is performed using scipy.interpolate.RectBivariateSpline using the specified degree of interpolation.

If interpolation is 'nearest', no interpolation is performed, and the mapped image takes the value of the nearest pixel in the image to that location. This can be useful to easily visualise the pixel scale for low spatial resolution observations.

To map a cube, this function can be called repeatedly on each image in the cube:

mapped_cube = np.array([body.map_img(img) for img in cube])

Parameters:

img – Observed image where pixel coordinates correspond to the xy pixel coordinates (e.g. those used in get_x0()).
degree_interval – Interval in degrees between the longitude/latitude points in the mapped output. Passed to get_x_map() and get_y_map() when generating the coordinates used for the projection.
interpolation – Interpolation used when mapping. This can either any of 'nearest', 'linear', 'quadratic' or 'cubic'. The default is 'linear'.
propagate_nan – If using spline interpolation, propagate NaN values from the image to the mapped data. If propagate_nan is True (the default), the interpolation is performed as normal (i.e. with NaN values in the image set to 0), then any mapped locations where the nearest corresponding image pixel is NaN are set to NaN. Note that there may still be very small errors on the boundaries of NaN regions caused by the interpolation.
warn_nan – Print warning if any values in img are NaN when any of the spline interpolations are used.
**map_kwargs – Additional arguments are passed to generate_map_coordinates() to specify and customise the map projection.

Returns:

Array containing map of the values in img at each location on the surface of the target body. Locations which are not visible or outside the projection domain have a value of NaN.

plot_wireframe_xy(ax: matplotlib.axes._axes.Axes | None = None, *, add_axis_labels: bool = True, aspect_adjustable: Literal['box', 'datalim'] = 'box', show: bool = False, **wireframe_kwargs: Unpack[_WireframeKwargs]) → Axes[source]

Plot basic wireframe representation of the observation using image pixel coordinates. See Body.plot_wireframe_radec() for details of accepted arguments.

Returns:: The axis containing the plotted wireframe.

plot_map_wireframe(ax: matplotlib.axes._axes.Axes | None = None, label_poles: bool = True, add_title: bool = True, add_axis_labels: bool = True, grid_interval: float = 30, indicate_equator: bool = True, indicate_prime_meridian: bool = True, aspect_adjustable: Literal['box', 'datalim'] = 'box', formatting: dict[Literal['all', 'grid', 'equator', 'prime_meridian', 'limb', 'limb_illuminated', 'terminator', 'ring', 'pole', 'coordinate_of_interest_lonlat', 'coordinate_of_interest_radec', 'other_body_of_interest_marker', 'other_body_of_interest_label', 'hidden_other_body_of_interest_marker', 'hidden_other_body_of_interest_label', 'map_boundary'], dict[str, Any]] | None = None, common_formatting: dict[str, Any] | None = None, **map_kwargs: Unpack[_MapKwargs]) → Axes[source]

Plot wireframe (e.g. gridlines) of the map projection of the observation. See Body.plot_wireframe_radec() for details of accepted arguments.

For example, to plot an orthographic map’s wireframe with a red boundary and dashed gridlines, you can use:

body.plot_map_wireframe(
    projection='orthographic',
    lat=45,
    formatting={
        'grid': {'linestyle': '--'},
        'map_boundary': {'color': 'red'},
    }
)

plot_map(map_img: ndarray, ax: matplotlib.axes._axes.Axes | None = None, *, wireframe_kwargs: dict[str, Any] | None = None, add_wireframe: bool = True, **kwargs) → QuadMesh[source]

Utility function to easily plot a mapped image using plt.imshow with appropriate extents, axis labels, gridlines etc.

Parameters:

map_img – Image to plot.
ax – Matplotlib axis to use for plotting. If ax is None (the default), then a new figure and axis is created.
wireframe_kwargs – Dictionary of arguments passed to plot_map_wireframe().
add_wireframe – Enable/disable plotting of wireframe.
**kwargs – Additional arguments are passed to generate_map_coordinates() to specify the map projection used, and to Matplotlib’s pcolormesh to customise the plot. For example, can be used to set the colormap of the plot using e.g. body.plot_map(..., projection='orthographic', cmap='Greys').

Returns:

Handle returned by Matplotlib’s pcolormesh.

get_wireframe_overlay_img(output_size: int | None = 1500, dpi: int = 200, rgba: bool = False, **plot_kwargs) → ndarray[source]

Warning

This is a beta feature and the API may change in future.

Generate a wireframe image of the target.

This effectively generates an image version of plot_wireframe_xy() which can then be used as an overlay on top of the observation when creating figures in other applications.

See also get_backplane_img().

Returns:: Array containing the planetographic longitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lon_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of planetographic longitude values.

get_lat_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the planetographic latitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lat_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of planetographic latitude values.

get_lon_centric_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the planetocentric longitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lon_centric_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of planetocentric longitude values.

get_lat_centric_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the planetocentric latitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lat_centric_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of planetocentric latitude values.

get_ra_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the right ascension (RA) value of each pixel in the image.

get_ra_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of right ascension values as viewed by the observer. Locations which are not visible have a value of NaN.

get_dec_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the declination (Dec) value of each pixel in the image.

get_dec_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of declination values as viewed by the observer. Locations which are not visible have a value of NaN.

get_x_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the x pixel coordinate value of each pixel in the image.

get_x_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the x pixel coordinates each location corresponds to in the observation. Locations which are not visible or are not in the image frame have a value of NaN.

get_y_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the y pixel coordinate value of each pixel in the image.

get_y_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the y pixel coordinates each location corresponds to in the observation. Locations which are not visible or are not in the image frame have a value of NaN.

get_km_x_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the distance in target plane in km in the East-West direction.

get_km_x_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the distance in target plane in km in the East-West direction. Locations which are not visible have a value of NaN.

get_km_y_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the distance in target plane in km in the North-South direction.

get_km_y_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the distance in target plane in km in the North-South direction. Locations which are not visible have a value of NaN.

get_phase_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the phase angle value of each pixel in the image. Points off the disc have a value of NaN.

get_phase_angle_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the phase angle value at each point on the target’s surface.

get_incidence_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the incidence angle value of each pixel in the image. Points off the disc have a value of NaN.

get_incidence_angle_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the incidence angle value at each point on the target’s surface.

get_emission_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the emission angle value of each pixel in the image. Points off the disc have a value of NaN.

get_emission_angle_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the emission angle value at each point on the target’s surface.

get_azimuth_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the azimuth angle value of each pixel in the image. Points off the disc have a value of NaN.

get_azimuth_angle_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the azimuth angle value at each point on the target’s surface.

get_local_solar_time_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the local solar time value of each pixel in the image, as calculated by Body.local_solar_time_from_lon(). Points off the disc have a value of NaN.

get_local_solar_time_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the local solar time at each point on the target’s surface, as calculated by Body.local_solar_time_from_lon().

get_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the observer-target distance in km of each pixel in the image. Points off the disc have a value of NaN.

get_distance_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the observer-target distance in km of each point on the target’s surface.

get_radial_velocity_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the observer-target radial velocity in km/s of each pixel in the image. Velocities towards the observer are negative. Points off the disc have a value of NaN.

get_radial_velocity_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the observer-target radial velocity in km/s of each point on the target’s surface.

get_doppler_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the doppler factor for each pixel in the image, calculated using SpiceBase.calculate_doppler_factor() on velocities from get_radial_velocity_img(). Points off the disc have a value of NaN.

get_doppler_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the doppler factor of each point on the target’s surface. This is calculated using SpiceBase.calculate_doppler_factor() on velocities from get_radial_velocity_map().

get_limb_lon_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the planetographic longitude of the point on the target’s limb that is closest to each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_lon_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the planetographic longitude of the point on the target’s limb that is closest to each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_limb_lat_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the planetographic latitude of the point on the target’s limb that is closest to each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_lat_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the planetographic latitude of the point on the target’s limb that is closest to each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_limb_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the distance in km above the target’s limb for each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_distance_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the distance in km above the target’s limb for each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_ring_plane_radius_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the ring plane radius in km for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_radius_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the ring plane radius in km obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

get_ring_plane_longitude_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the ring plane planetographic longitude in degrees for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_longitude_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the ring plane planetographic longitude in degrees obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

get_ring_plane_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Array containing the ring plane distance from the observer in km for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_distance_map(**map_kwargs: Unpack[_MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Array containing map of the ring plane distance from the observer in km obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

class planetmapper.Observation(path: str | None = None, *, data: numpy.ndarray | None = None, header: astropy.io.fits.header.Header | None = None, **kwargs)[source]

Bases: BodyXY

Class representing an actual observation of an astronomical body at a specific time.

This is a subclass of BodyXY, with additional methods to interact with the observed data, such as by saving a FITS file containing calculated backplane data. All methods described in BodyXY, Body and SpiceBase are therefore available in instances of this class.

This class can be created by either providing a path to a data file to be loaded, or by directly providing the data itself (and optionally a FITS header). The nx and ny values for BodyXY will automatically be calculated from the input data.

If the input data is a FITS file (or a header is specified), then this class will attempt to generate appropriate parameters (e.g. target, utc) by using the values in the header. This allows an instance of this class to be created with a single argument specifying the path to the FITS file e.g. Observation('path/to/file.fits'). Manually specified parameters will take precedence, so Observation('path/to/file.fits', target='JUPITER') will have Jupiter as a target, regardless of any values saying otherwise in the FITS header.

If a FITS header is not provided (e.g. if the input path corresponds to an image file), then at least the target and utc parameters need to be specified.

When an Observation object is created, the disc parameters (x0, y0, r0, rotation) initialised to the most useful values possible:

If the input file has previously been fit by PlanetMapper, the previous parameter values saved in the FITS header are loaded using disc_from_header().
Otherwise, if there is WCS information in the FITS header, this is loaded with disc_from_wcs().
Finally, if there is no useful information in the FITS header (or no header is provided), the disc parameters are initialised using centre_disc().

Parameters:

path – Path to data file to load. If this is None then data must be specified instead. Any user (~) and shell variables (e.g. $var) in the path are automatically expanded if possible.
data – Array containing observation data to use instead of loading the data from path. This should only be provided if path is None.
header – FITS header which corresponds to the provided data. This is optional and should only be provided if path is None.
target – Name of target body, passed to Body. If this is unspecified, then the target will be derived from the values in the FITS header.
utc – Time of observation, passed to Body. If this is unspecified, then the time will be derived from the values in the FITS header.
**kwargs – Additional parameters are passed to BodyXY. These can be used to specify additional parameters such as`observer`.

FITS_FILE_EXTENSIONS = ('.fits', '.fits.gz'): File extensions which will be read as FITS files. All other file extensions will be assumed to be images.

FITS_KEYWORD = 'PLANMAP': FITS keyword used in metadata added to header of output FITS files.

path: str | None: Path of input data file, or None if no file was provided.

data: np.ndarray: Observed data.

header: fits.Header: FITS header containing data about the observation. If this is not provided, then a basic header will be produced containing data derived from the target and utc parameters.

disc_from_header() → None[source]

Sets the target’s planetary disc data in the FITS header generated by previous runs of planetmapper.

This uses values such as HIERARCH PLANMAP DISC X0 to set the disc location to be the same as the previous run.

Raises:: ValueError – if the header does not contain appropriate metadata values. This is likely because the file was not created by planetmapper.

disc_from_wcs(suppress_warnings: bool = False, validate: bool = True, use_header_offsets: bool = True) → None[source]

Set disc parameters using WCS information in the observation’s FITS header.

Note

There may be very slight differences between the coordinates converted directly from the WCS information and the coordinates converted by PlanetMapper.

Parameters:

suppress_warnings – Hide warnings produced by astropy when calculating WCS conversions.
validate – Run checks to ensure the WCS conversion has appropriate RA/Dec coordinate dimensions.
use_header_offsets – If present, use the HIERARCH NAV RA_OFFSET and HIERARCH NAV DEC_OFFSET values from the FITS headerr to adjust the target’s disc location by the specified arcsecond offsets. If these keywords are not present or use_header_offsets is False, no adjustment is made.

Raises:

ValueError – if no WCS information is found in the FITS header, or validation fails.

position_from_wcs(*args, **kwargs) → None[source]

Set disc position (x0, y0) using WCS information in the observation’s FITS header.

planetmapper

`planetmapper`