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. IfFalse
(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
isTrue
, 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()
ifload_kernels
is True. It is recommended to useset_kernel_path()
instead of passing this argument.manual_kernels – Passed to
load_spice_kernels()
ifload_kernels
is True. It is recommended to useplanetmapper.base.prevent_kernel_loading()
then manually load kernels yourself instead of passing this argument.
- 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 withspice.bods2c
, then back into a string withspice.bodc2s
. This standardises to the version of the name preferred by SPICE. For example,'jupiter'
,'JuPiTeR'
,' Jupiter '
,'599'
and599
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.See also https://en.wikipedia.org/wiki/Relativistic_Doppler_effect#Relativistic_longitudinal_Doppler_effect
- 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 afloat
is returned. If the inputradial_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
isNone
(the default), then all kernels in the directory given bykernel_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 withmanual_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 ofget_kernel_path()
is used. It is usually recommended to use one of the methods described in the kernel directory documentation rather than using thiskernel_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
andobserver
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
andobserver
names are passed toSpiceBase.standardise_body_name()
, so a variety of formats are acceptable. For example'jupiter'
,'JUPITER'
,' Jupiter '
,'599'
and599
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 Pythondatetime
object, or afloat
representing the Modified Julian Date (MJD) of the observation. Alternatively, ifutc
isNone
(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()
.
- dtm: datetime.datetime
Python timezone aware datetime of the observation corresponding to
utc
.
- target_light_time: float
Light time from the target to the observer at the time of the observation.
- radii: np.ndarray
Array of radii of the target body along the x, y and z axes in km.
- 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 longitudesFor more details, see https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/pgrrec_c.html#Particulars
- 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 toring_radii
usingadd_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
ring_radec()
.
- other_bodies_of_interest: list[Body | BasicBody]
List of other bodies of interest to mark when plotting. Add to this list using
add_other_bodies_of_interest()
.
- coordinates_of_interest_lonlat: list[tuple[float, float]]
List of
(lon, lat)
coordinates of interest on the surface of the target body to mark when plotting (points which are not visible will not be plotted). To add a new point of interest, simply append a coordinate pair to this list:body.coordinates_of_interest_lonlat.append((0, -22))
- coordinates_of_interest_radec: list[tuple[float, float]]
List of
(ra, dec)
sky coordinates of interest to mark when plotting (e.g. background stars). To add new point of interest, simply append a coordinate pair to this list:body.coordinates_of_interest_radec.append((200, -45))
- create_other_body(other_target: str | int, fallback_to_basic_body: Literal[False]) Body [source]
- create_other_body(other_target: str | int, fallback_to_basic_body: bool = True) planetmapper.body.Body | planetmapper.basic_body.BasicBody
Create a
Body
instance using identical parameters but just with a different target. For example, theeuropa
body created here will have identical parameters (see below) to thejupiter
body, just with a different target.jupiter = Body('Jupiter', '2000-01-01', observer='Moon') europa = jupiter.create_other_body('Europa')
The parameters kept the same are
utc
,observer
,observer_frame
,illumination_source
,aberration_correction
,subpoint_method
, andsurface_method
.If a full
Body
instance cannot be created due to insufficient data in the SPICE kernel, aBasicBody
instance will be created instead. This is useful for objects such as minor satellites which do not have known radius data.
- add_other_bodies_of_interest(*other_targets: str | int, only_visible: bool = False) None [source]
Add targets to the list of
other_bodies_of_interest
of interest to mark when plotting. The other targets are created usingcreate_other_body()
. For example, to add the Galilean moons as other targets to a Jupiter body, usebody = planetmapper.Body('Jupiter') body.add_other_bodies_of_interest('Io', 'Europa', 'Ganymede', 'Callisto')
Integer SPICE ID codes can also be provided, which can be used to simplify adding multiple satellites to plots.
body = planetmapper.Body('Uranus') body.add_other_bodies_of_interest(*range(701, 711)) # Uranus' satellites have ID codes 701, 702, 703 etc, so this adds 10 moons # with a single function call
See also
add_satellites_to_bodies_of_interest()
.- Parameters:
*other_targets – Names of the other targets, passed to
Body
only_visible – If
True
, other targets which are hidden behind the target will not be added toother_bodies_of_interest
.
- add_satellites_to_bodies_of_interest(skip_insufficient_data: bool = False, only_visible: bool = False) None [source]
Automatically add all satellites in the target planetary system to
other_bodies_of_interest
.This uses the NAIF ID codes to identify the satellites. For example, Uranus has an ID of 799, and its satellites have codes 701, 702, 703…, so any object with a code in the range 701 to 798 is added for Uranus.
See also
add_other_bodies_of_interest()
.- Parameters:
skip_insufficient_data – If True, satellites with insufficient data in the SPICE kernel will be skipped. If False, an exception will be raised.
only_visible – If
True
, satellites which are hidden behind the target body will not be added.
- ring_radii_from_name(name: str) list[float] [source]
Get list of ring radii in km for a named ring.
This is a convenience function to load data from
named_ring_data
.- Parameters:
name – Name of ring. This is case insensitive and, “ring” suffix is optional and non-ASCII versions are allowed. For example,
'liberte'
will load the'Liberté'
ring radii for Uranus and'amalthea'
will load the'Amalthea Ring'
radii for Jupiter.- Raises:
ValueError – if no ring with the provided name is found.
- Returns:
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.
- add_named_rings(*names: str) None [source]
Add named rings to
ring_radii
so that they appear when creating wireframe plots. If no arguments are provided (i.e. callingbody.add_named_rings()
), then all rings innamed_ring_data
are added toring_radii
.This is a convenience function to add data from
named_ring_data
toring_radii
.- Parameters:
*names – Ring names which are passed to
ring_radii_from_name()
. If no names are provided then all rings innamed_ring_data
are added.
- lonlat2radec(lon: float, lat: float) tuple[float, float] [source]
Convert longitude/latitude coordinates on the target body to RA/Dec sky coordinates for the observer.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
(ra, dec)
tuple containing the RA/Dec coordinates of the point.
- radec2lonlat(ra: float, dec: float, not_found_nan: bool = True) tuple[float, float] [source]
Convert RA/Dec sky coordinates for the observer to longitude/latitude coordinates on the target body.
The provided RA/Dec will not necessarily correspond to any longitude/latitude coordinates, as they could be ‘missing’ the target and instead be observing the background sky. In this case, the returned longitude/latitude values will be NaN if
not_found_nan
is True (the default) or this function will raise an error ifnot_found_nan
is False.- Parameters:
ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
not_found_nan – Controls behaviour when the input
ra
anddec
coordinates are missing the target body.
- Returns:
(lon, lat)
tuple containing the longitude/latitude coordinates on the target body. If the provided RA/Dec coordinates are missing the target body andnot_found_nan
is True, then thelon
andlat
values will both be NaN.- Raises:
NotFoundError – If the provided RA/Dec coordinates are missing the target body and
not_found_nan
is False, then NotFoundError will be raised.
- lonlat2targvec(lon: float, lat: float) ndarray [source]
Convert longitude/latitude coordinates on the target body to rectangular vector centred in the target frame (e.g. for use as an input to a SPICE function).
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
Numpy array corresponding to the 3D rectangular vector describing the longitude/latitude point in the target frame of reference.
- targvec2lonlat(targvec: ndarray) tuple[float, float] [source]
Convert rectangular vector centred in the target frame to longitude/latitude coordinates on the target body (e.g. to convert the output from a SPICE function).
- Parameters:
targvec – 3D rectangular vector in the target frame of reference.
- Returns:
(lon, lat)
tuple containing the longitude and latitude corresponding to the input vector.
- km2radec(km_x: float, km_y: float) tuple[float, float] [source]
Convert distance in target plane to RA/Dec sky coordinates for the observer.
- 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:
(ra, dec)
tuple containing the RA/Dec coordinates of the point.
- radec2km(ra: float, dec: float) tuple[float, float] [source]
Convert RA/Dec sky coordinates for the observer to distances in the target plane.
- Parameters:
ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
- Returns:
(km_x, km_y)
tuple containing distances in km in the target plane in the East-West and North-South directions respectively.
- km2lonlat(km_x: float, km_y: float, **kwargs) tuple[float, float] [source]
Convert distance in target plane to longitude/latitude coordinates on the target body.
- 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.
**kwargs – Additional arguments are passed to
Body.radec2lonlat()
.
- Returns:
(lon, lat)
tuple containing the longitude and latitude of the point. If the provided km coordinates are missing the target body, then thelon
andlat
values will both be NaN (seeBody.radec2lonlat()
).
- lonlat2km(lon: float, lat: float) tuple[float, float] [source]
Convert longitude/latitude coordinates on the target body to distances in the target plane.
- Parameters:
lon – Longitude of point on the target body.
lat – Latitude of point on the target body.
- Returns:
(km_x, km_y)
tuple containing distances in km in the target plane in the East-West and North-South directions respectively.
- matplotlib_radec2km_transform(ax: matplotlib.axes._axes.Axes | None = None) Transform [source]
Get matplotlib transform which converts RA/Dec sky coordinates to target plane distance coordinates.
- Parameters:
ax – Optionally specify a matplotlib axis to return
transform_radec2km + ax.transData
. This value can then be used in thetransform
keyword argument of a Matplotlib function without any further modification.- Returns:
Matplotlib transformation from
radec
tokm
coordinates.
- matplotlib_km2radec_transform(ax: matplotlib.axes._axes.Axes | None = None) Transform [source]
Get matplotlib transform which converts target plane distance coordinates to RA/Dec sky coordinates.
- Parameters:
ax – Optionally specify a matplotlib axis to return
transform_km2radec + ax.transData
. This value can then be used in thetransform
keyword argument of a Matplotlib function without any further modification.- Returns:
Matplotlib transformation from
km
toradec
coordinates.
- limb_radec(**kwargs) tuple[numpy.ndarray, numpy.ndarray] [source]
Calculate the RA/Dec coordinates of the target body’s limb.
- Parameters:
npts – Number of points in the generated limb.
- Returns:
(ra, dec)
tuple of coordinate arrays.
- limb_radec_by_illumination(**kwargs) tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray] [source]
Calculate RA/Dec coordinates of the dayside and nightside parts of the target body’s limb.
Output arrays are like the outputs of
limb_radec()
, but the dayside coordinate arrays have non-illuminated locations replaced with NaN and the nightside arrays have illuminated locations replaced with NaN.- Parameters:
npts – Number of points in the generated limbs.
- Returns:
(ra_day, dec_day, ra_night, dec_night)
tuple of coordinate arrays of the dayside then nightside parts of the limb.
- limb_coordinates_from_radec(ra: float, dec: float) tuple[float, float, float] [source]
Calculate the coordinates relative to the target body’s limb for a point in the sky.
The coordinates are calculated for the point on the ray (as defined by RA/Dec) which is closest to the target body’s limb.
- Parameters:
ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
- Returns:
(lon, lat, dist)
tuple of coordinates relative to the target body’s limb.lon
andlat
give the planetographic longitude and latitude of the point on the limb closest to the point defined byra
anddec
.dist
gives the distance from the point defined byra
anddec
to the target’s limb. Positive values ofdist
mean that the point is above the limb and negative values mean that the point is below the limb (i.e. on the target body’s disc).
- test_if_lonlat_visible(lon: float, lat: float) bool [source]
Test if longitude/latitude coordinate on the target body are visible.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
True if the point is visible from the observer, otherwise False.
- other_body_los_intercept(other: str | int | planetmapper.body.Body | planetmapper.basic_body.BasicBody) Union[None, Literal['transit', 'hidden', 'part transit', 'part hidden', 'same']] [source]
Test for line-of-sight intercept between the target body and another body.
This can be used to test for if another body (e.g. a moon) is in front of or behind the target body (e.g. a planet).
See also
test_if_other_body_visible()
.Warning
This method does not perform any checks to ensure that any input
Body
orBasicBody
instances have a consistent observer location and observation time as the target body.- Parameters:
other – Other body to test for intercept with. Can be a :class`Body` (or
BasicBody
) instance, or a string/integer NAIF ID code which is passed tocreate_other_body()
.- Returns:
None
if there is no intercept, otherwise a string indicating the type of intercept. For example, withjupiter.other_body_los_intercept('europa')
, the possible return values mean:None
- there is no intercept, meaning that Europa and Jupiter do not overlap in the sky.'hidden'
- all of Europa’s disk is hidden behind Jupiter.'part hidden'
- part of Europa’s disk is hidden behind Jupiter and part is visible.'transit'
- all of Europa’s disk is in front of Jupiter.'part transit'
- part of Europa’s disk is in front of Jupiter.
The return value can also be
'same'
, which means that the other body is the same object as the target body (or has an identical location).
- test_if_other_body_visible(other: str | int | planetmapper.body.Body | planetmapper.basic_body.BasicBody) bool [source]
Test if another body is visible, or is hidden behind the target body.
This is a convenience method equivalent to:
body.other_body_los_intercept(other) != 'hidden'
- Parameters:
other – Other body to test for visibility, passed to
other_body_los_intercept()
.- Returns:
False
if the other body is hidden behind the target body, otherwiseTrue
. If any part of the other body is visible, this method will returnTrue
.
- illumination_angles_from_lonlat(lon: float, lat: float) tuple[float, float, float] [source]
Calculate the illumination angles of a longitude/latitude coordinate on the target body.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
(phase, incidence, emission)
tuple containing the illumination angles.
- azimuth_angle_from_lonlat(lon: float, lat: float) float [source]
Calculate the azimuth angle of a longitude/latitude coordinate on the target body.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
Azimuth angle in degrees.
- local_solar_time_from_lon(lon: float) float [source]
Calculate the numerical local solar time for a longitude on the target body. For example,
0.0
corresponds to midnight and12.5
corresponds to 12:30pm.See also
local_solar_time_string_from_lon()
.Note
A ‘local hour’ of solar time is a defined as 1/24th of the solar day on the target body, so will not correspond to a ‘normal’ hour as measured by a clock. See the SPICE documentation for more details.
- Parameters:
lon – Longitude of point on target body.
- Returns:
Numerical local solar time in ‘local hours’.
- local_solar_time_string_from_lon(lon: float) str [source]
Local solar time string representation for a longitude on the target body. For example,
'00:00:00'
corresponds to midnight and'12:30:00'
corresponds to 12:30pm.See
local_solar_time_from_lon()
for more details.- Parameters:
lon – Longitude of point on target body.
- Returns:
String representation of local solar time.
- terminator_radec(npts: int = 360, only_visible: bool = True, close_loop: bool = True, method: str = 'UMBRAL/TANGENT/ELLIPSOID', corloc: str = 'ELLIPSOID TERMINATOR') tuple[numpy.ndarray, numpy.ndarray] [source]
Calculate the RA/Dec coordinates of the terminator (line between day and night) on the target body. By default, only the visible part of the terminator is returned (this can be changed with
only_visible
).- Parameters:
npts – Number of points in generated terminator.
only_visible – Toggle only returning visible part of terminator.
close_loop – If True, passes coordinate arrays through
close_loop()
(e.g. to enable nicer plotting).method – Passed to SPICE function.
corloc – Passed to SPICE function.
- Returns:
(ra, dec)
tuple of RA/Dec coordinate arrays.
- test_if_lonlat_illuminated(lon: float, lat: float) bool [source]
Test if longitude/latitude coordinate on the target body are illuminated.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
True if the point is illuminated, otherwise False.
- ring_plane_coordinates(ra: float, dec: float, only_visible: bool = True) tuple[float, float, float] [source]
Calculate coordinates in the target body’s equatorial (ring) plane. This is mainly useful for calculating the coordinates in a body’s ring system at a given point in the sky.
To calculate the coordinates corresponding to a location on the target body, you can use
body.ring_plane_coordinates(*body.radec2lonlat(lon, lat))
This form can be useful to identify parts of a planet’s surface which are obscured by its rings
radius, _, _ = body.ring_plane_coordinates(*body.lonlat2radec(lon, lat)) ring_data = planetmapper.data_loader.get_ring_radii()['SATURN'] for name, radii in ring_data.items(): if min(radii) < radius < max(radii): print(f'Point obscured by {name} ring') break else: print('Point not obscured by rings')
- Parameters:
ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
only_visible – If
True
(the default), coordinates for parts of the equatorial plane hidden behind the target body are set to NaN.
- Returns:
(ring_radius, ring_longitude, ring_distance)
tuple for the point on the target body’s equatorial (ring) plane.ring_radius
gives the distance of the point in km from the centre of the target body.ring_longitude
gives the planetographic longitude of the point in degrees.ring_distance
gives the distance from the observer to the point in km.
- ring_radec(radius: float, npts: int = 360, only_visible: bool = True) tuple[numpy.ndarray, numpy.ndarray] [source]
Calculate RA/Dec coordinates of a ring around the target body.
The ring is assumed to be directly above the planet’s equator and has a constant
radius
for all longitudes. Usering_radii
to set the rings automatically plotted.- Parameters:
radius – Radius in km of the ring from the centre of the target body.
npts – Number of points in the generated ring.
only_visible – If
True
(default), the coordinates for the part of the ring hidden behind the target body are set to NaN. This routine will execute slightly faster withonly_visible
set toFalse
.
- Returns:
(ra, dec)
tuple of coordinate arrays.
- visible_lonlat_grid_radec(interval: float = 30, **kwargs) list[tuple[numpy.ndarray, numpy.ndarray]] [source]
Convenience function to calculate a grid of equally spaced lines of constant longitude and latitude for use in plotting lon/lat grids.
This function effectively combines
visible_lon_grid_radec()
andvisible_lat_grid_radec()
to produce both longitude and latitude gridlines.For example, to plot gridlines with a 45 degree interval, use:
lines = body.visible_lonlat_grid_radec(interval=45) for ra, dec in lines: plt.plot(ra, dec)
- Parameters:
interval – Spacing of gridlines. Generally, this should be an integer factor of 90 to produce nice looking plots (e.g. 10, 30, 45 etc).
**kwargs – Additional arguments are passed to
visible_lon_grid_radec()
andvisible_lat_grid_radec()
.
- Returns:
List of
(ra, dec)
tuples, each of which corresponds to a gridline.ra
anddec
are arrays of RA/Dec coordinate values for that gridline.
- visible_lon_grid_radec(lons: list[float] | numpy.ndarray, npts: int = 60) list[tuple[numpy.ndarray, numpy.ndarray]] [source]
Calculates the RA/Dec coordinates for visible lines of constant longitude.
For each longitude in
lons
, a(ra, dec)
tuple is calculated which contains arrays of RA and Dec coordinates. Coordinates which correspond to points which are not visible are replaced with NaN.See also
visible_lonlat_grid_radec()
,- Parameters:
lons – List of longitudes to plot.
npts – Number of points in each full line of constant longitude.
- Returns:
List of
(ra, dec)
tuples, corresponding to the list of inputlons
.ra
anddec
are arrays of RA/Dec coordinate values for that gridline.
- visible_lat_grid_radec(lats: list[float] | numpy.ndarray, npts: int = 120) list[tuple[numpy.ndarray, numpy.ndarray]] [source]
Constant latitude version of
visible_lon_grid_radec()
. See alsovisible_lonlat_grid_radec()
.- Parameters:
lats – List of latitudes to plot.
npts – Number of points in each full line of constant latitude.
- Returns:
List of
(ra, dec)
tuples, corresponding to the list of inputlats
.ra
anddec
are arrays of RA/Dec coordinate values for that gridline.
- radial_velocity_from_lonlat(lon: float, lat: float) float [source]
Calculate radial (i.e. line-of-sight) velocity of a point on the target’s surface relative to the observer. This can be used to calculate the doppler shift.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
Radial velocity of the point in km/s.
- distance_from_lonlat(lon: float, lat: float) float [source]
Calculate distance from observer to a point on the target’s surface.
- Parameters:
lon – Longitude of point on target body.
lat – Latitude of point on target body.
- Returns:
Distance of the point in km.
- graphic2centric_lonlat(lon: float, lat: float) tuple[float, float] [source]
Convert planetographic longitude/latitude to planetocentric.
- Parameters:
lon – Planetographic longitude.
lat – Planetographic latitude.
- Returns:
(lon_centric, lat_centric)
tuple of planetocentric coordinates.
- centric2graphic_lonlat(lon_centric: float, lat_centric: float) tuple[float, float] [source]
Convert planetocentric longitude/latitude to planetographic.
- Parameters:
lon_centric – Planetocentric longitude.
lat_centric – Planetographic latitude.
- Returns:
(lon, lat)
tuple of planetographic coordinates.
- north_pole_angle() float [source]
Calculate the angle of the north pole of the target body relative to the positive declination direction.
- Returns:
Angle of the north pole in degrees.
- get_description(multiline: bool = True) str [source]
Generate a useful description of the body.
- Parameters:
multiline – Toggles between multi-line and single-line version of the description.
- Returns:
String describing the observation of the body.
- get_poles_to_plot() list[tuple[float, float, str]] [source]
Get list of poles on the target body for use in plotting.
If at least one pole is visible, return the visible poles. If no poles are visible, return both poles but in brackets. This ensures that at lease one pole is always returned (to orientate the observation).
- Returns:
List of
(lon, lat, label)
tuples describing the poles wherelon
andlat
give the coordinates of the pole on the target andlabel
is a string describing the pole. If the pole is visible, thelabel
is either ‘N’ or ‘S’. If neither pole is visible, then both poles are returned with labels of ‘(N)’ and ‘(S)’.
- plot_wireframe_radec(ax: matplotlib.axes._axes.Axes | None = None, *, dms_ticks: bool = True, add_axis_labels: bool = True, aspect_adjustable: Literal['box', 'datalim'] = 'datalim', show: bool = False, **wireframe_kwargs: Unpack[_WireframeKwargs]) Axes [source]
Plot basic wireframe representation of the observation using RA/Dec sky coordinates.
See also
plot_wireframe_km()
andBodyXY.plot_wireframe_xy()
to plot the wireframe in other coordinate systems.To plot a wireframe with the default appearance, simply use:
body.plot_wireframe_radec()
To customise the appearance of the plot, you can use the
formatting
and**kwargs
arguments which can be used to pass arguments to the Matplotlib plotting functions. Theformatting
argument can be used to customise individual components, and the**kwargs
argument can be used to customise all components at once.For example, to change the colour of the entire wireframe to red, you can use:
body.plot_wireframe_radec(color='r')
To change just the plotted terminator and dayside limb to red, use:
body.plot_wireframe_radec( formatting={ 'terminator': {'color': 'r'}, 'limb_illuminated': {'color': 'r'}, }, )
The order of precedence for the formatting is the
formatting
argument, then**kwargs
, then the default formatting. For example, the following plot will be red with a thin blue grid and green poles:body.plot_wireframe_radec( color='r', formatting={ 'grid': {'color': 'b', 'linewidth': 0.5, 'linestyle': '-'}, 'pole': {'color': 'g'}, }, )
Individual components can be hidden by setting
visible
toFalse
. For example, to hide the terminator, use:body.plot_wireframe_radec(formatting={'terminator': {'visible': False}})
The default formatting is defined in
DEFAULT_WIREFRAME_FORMATTING
. This can be modified after importing PlanetMapper to change the default appearance of all wireframes:import planetmapper planetmapper.DEFAULT_WIREFRAME_FORMATTING['grid']['color'] = 'b' planetmapper.DEFAULT_WIREFRAME_FORMATTING['grid']['linestyle'] = '--' body.plot_wireframe_radec() # This would have a blue dashed grid body.plot_wireframe_radec(color='r') # This would be red with a dashed grid
- Parameters:
ax – Matplotlib axis to use for plotting. If
ax
is None (the default), usesplt.gca()
to get the currently active axis.label_poles – Toggle labelling the poles of the target body.
add_title – Add title generated by
get_description()
to the axis.add_axis_labels – Add axis labels.
grid_interval – Spacing between grid lines in degrees.
indicate_equator – Toggle indicating the equator with a solid line.
indicate_prime_meridian – Toggle indicating the prime meridian with a solid line.
aspect_adjustable – Set
adjustable
parameter when setting the aspect ratio. Passed tomatplotlib.axes.Axes.set_aspect()
.dms_ticks – Toggle between showing ticks as degrees, minutes and seconds (e.g. 12°34′56″) or decimal degrees (e.g. 12.582). This argument is only applicable for
plot_wireframe_radec()
.show – Toggle immediately showing the plotted figure with
plt.show()
.formatting –
Dictionary of formatting options for the wireframe components. The keys of this dictionary are the names of the wireframe components and the values are dictionaries of keyword arguments to pass to the Matplotlib plotting function for that component. For example, to set the
color
of the plotted rings to red, you could use:body.plot_wireframe_radec(formatting={'ring': {'color': 'r'}})
The following components can be formatted:
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
.**kwargs –
Additional arguments are passed to Matplotlib plotting functions for all components. This is useful for specifying properties like
color
to customise the entire wireframe rather than a single component. For example, to make the entire wireframe red, you could use:body.plot_wireframe_radec(color='r')
- Returns:
The axis containing the plotted wireframe.
- plot_wireframe_km(ax: matplotlib.axes._axes.Axes | None = None, *, add_axis_labels: bool = True, aspect_adjustable: Literal['box', 'datalim'] = 'datalim', show: bool = False, **wireframe_kwargs: Unpack[_WireframeKwargs]) Axes [source]
Plot basic wireframe representation of the observation on a target centred frame. See
plot_wireframe_radec()
for details of accepted arguments.- Returns:
The axis containing the plotted wireframe.
- class planetmapper.Backplane(name: str, description: str, get_img: Callable[[], ndarray], get_map: _BackplaneMapGetter)[source]
Bases:
NamedTuple
NamedTuple containing information about a backplane.
Backplanes provide a way to generate and save additional information about an observation, such as the longitudes/latitudes corresponding to each pixel in the observed image. This class provides a standardised way to store a backplane generation function, along with some metadata (
name
anddescription
) which describes what the backplane represents.See also
BodyXY.backplanes
.- Parameters:
name – Short name identifying the backplane. This is used as the
EXTNAME
for the backplane when saving FITS files inObservation.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 asBodyXY.get_lon_map()
.
- 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 framexy
. This class assumes the tangent plane approximation is valid for the conversion between pixel coordinatesxy
and RA/Dec sky coordinatesradec
.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 discr0
and therotation
of the disc. These disc parameters can be adjusted using methods such asset_x0()
and retrieved using methods such asget_x0()
. It is important to note that conversions involvingxy
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 aBodyXY
instance (or any other instance which derives fromSpiceBase
).The size of the image can be specified by using the
nx
andny
parameters to specify the number of pixels in the x and y dimensions of the image respectively. Ifnx
andny
are equal (i.e. the image is square), then the parametersz
can be used instead to set bothnx
andny
, whereBodyXY(..., sz=50)
is equivalent toBodyXY(..., nx=50, ny=50)
.If
nx
andny
are not set, then some functionality (such as generating backplane images) will not be available and will raise aValueError
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 aBody
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
andny
to the same value.BodyXY(..., sz=50)
is equivalent toBodyXY(..., nx=50, ny=50)
. Ifsz
is defined along withnx
orny
then aValueError
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 usingregister_backplane()
.Generated backplane images can be easily retrieved using
get_backplane_img()
and plotted usingplot_backplane_img()
. Similarly, backplane maps cen be retrieved usingget_backplane_map()
and plotted usingplot_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. callingbody.backplanes['LAT-GRAPHIC'].get_img()
or usingget_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 aBody
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
andny
to the same value.
- Returns:
BodyXY
instance with the same parameters as the inputBody
instance and the specified image dimensions.
- 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 thelon
andlat
values will both be NaN (seeBody.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 callingbody.set_x0(10)
andbody.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_...
andget_...
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
anddr
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
andy0
so that they lie in the centre of the image, andr0
is adjusted so that the disc fills 90% of the shortest side of the image. For example, ifnx = 20
andny = 30
, thenx0
will be set to 10,y0
will be set to 15 andr0
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.
- 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.
- 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 orr0
is not finite.
- 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 (positivey
) direction in the image pixel coordinates.- Parameters:
rotation – New rotation of the target body.
- Raises:
ValueError – if
rotation
is not finite.
- 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
andny
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 asset_x0()
andObservation.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)
See also
get_img_limits_km()
andget_img_limits_xy()
.- 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 theradec
toxy
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 thetransform
keyword argument of a Matplotlib function without any further modification.- Returns:
Matplotlib transformation from
xy
toradec
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()
andmatplotlib_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 usingscipy.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])
See also
Observation.get_mapped_data()
.- Parameters:
img – Observed image where pixel coordinates correspond to the
xy
pixel coordinates (e.g. those used inget_x0()
).degree_interval – Interval in degrees between the longitude/latitude points in the mapped output. Passed to
get_x_map()
andget_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
isTrue
(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’spcolormesh
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_wireframe_overlay_map()
.Note
The returned image data follows the FITS orientation convention (with the origin at the bottom left) so may need to be flipped vertically in some applications. If needed, the image can be flipped in Python using:
np.flipud(body.get_wireframe_overlay_img())
Hint
If you are creating plots with Matplotlib, it is generally better to use
plot_wireframe_xy()
directly rather than generating an image as it will produce a higher quality plot.- Parameters:
output_size – Size of the output image in pixels. This will be the length of the longest side of the image. The other side will be scaled accordingly to maintain the aspect ratio of the observed data. If
size
isNone
, then the size is set to match the size of the observed data.dpi – Dots per inch of the output image. This can be used to control the size of plotted elements in the output image - larger
dpi
values will produce larger plotted elements.rgba – By default, the returned image only has a single greyscale channel. If
rgba
isTrue
, then the returned image has 4 channels (red, green, blue, alpha) which can be used to more easily overlay the wireframe on top of the observed data in other applications.**plot_kwargs – Additional arguments passed to
plot_wireframe_xy()
.
- Returns:
Image of the wireframe which has the same aspect ratio as the observed data.
- get_wireframe_overlay_map(output_size: int | None = 1500, dpi: int = 200, rgba: bool = False, plot_kwargs: dict[str, Any] | None = None, **map_kwargs: Unpack[_MapKwargs]) ndarray [source]
Warning
This is a beta feature and the API may change in future.
Generate a wireframe map of the target.
This effectively generates an image version of
plot_map_wireframe()
which can then be used as an overlay on top of the mapped observation when creating figures in other applications.See also
get_wireframe_overlay_img()
.Note
The returned image data follows the FITS orientation convention (with the origin at the bottom left) so may need to be flipped vertically in some applications. If needed, the image can be flipped in Python using:
np.flipud(body.get_wireframe_overlay_map())
Hint
If you are creating plots with Matplotlib, it is generally better to use
plot_map_wireframe()
directly rather than generating an image as it will produce a higher quality plot.- Parameters:
output_size – Size of the output image in pixels. This will be the length of the longest side of the map. The other side will be scaled accordingly to maintain the aspect ratio of the observed data. If
size
isNone
, then the size is set to match the pixel size of the map.dpi – Dots per inch of the output image. This can be used to control the size of plotted elements in the output image - larger
dpi
values will produce larger plotted elements.rgba – By default, the returned image only has a single greyscale channel. If
rgba
isTrue
, then the returned image has 4 channels (red, green, blue, alpha) which can be used to more easily overlay the wireframe on top of the observed data in other applications.plot_kwargs – Dictionary of arguments passed to
plot_map_wireframe()
.**map_kwargs – Additional arguments passed to
generate_map_coordinates()
to specify map projection to use.
- Returns:
Image of the map wireframe which has the same aspect ratio as the map.
- static standardise_backplane_name(name: str) str [source]
Create a standardised version of a backplane name when finding and registering backplanes.
This standardisation is used in functions like
get_backplane_img()
andplot_backplane()
so that, for examplebody.plot_backplane('DEC')
,body.plot_backplane('Dec')
andbody.plot_backplane('dec')
all produce the same plot.- Parameters:
name – Input backplane name.
- Returns:
Standardised name with leading/trailing spaces removed and converted to upper case.
- register_backplane(name: str, description: str, get_img: Callable[[], ndarray], get_map: _BackplaneMapGetter) None [source]
Create a new
Backplane
and register it tobackplanes
.See
Backplane
for more detail about parameters.- Parameters:
name – Name of backplane. This is standardised using
standardise_backplane_name()
before being registered.description – Longer description of backplane, including units.
get_img – Function to generate backplane image.
get_map – Function to generate backplane map.
- Raises:
ValueError – if provided backplane name is already registered.
- backplane_summary_string() str [source]
- Returns:
String summarising currently registered
backplanes
.
- print_backplanes() None [source]
Prints output of
backplane_summary_string()
.
- get_backplane(name: str) Backplane [source]
Convenience function to retrieve a backplane registered to
backplanes
.This method is equivalent to
body.backplanes[self.standardise_backplane_name(name)]
- Parameters:
name – Name of the desired backplane. This is standardised with
standardise_backplane_name()
and used to choose a registered backplane frombackplanes
.- Returns:
Backplane registered with
name
.- Raises:
BackplaneNotFoundError – if
name
is not registered as a backplane.
- get_backplane_img(name: str) ndarray [source]
Generate backplane image.
Note that a generated backplane image will depend on the disc parameters
(x0, y0, r0, rotation)
at the time this function is called. Generating the same backplane when there are different disc parameter values will produce a different image. This method creates a copy of the generated image, so the returned image can be safely modified without affecting the cached value (unlike the return values from functions such asget_lon_img()
).This method is equivalent to
body.get_backplane(name).get_img().copy()
- Parameters:
name – Name of the desired backplane. This is standardised with
standardise_backplane_name()
and used to choose a registered backplane frombackplanes
.- Returns:
Array containing the backplane’s values for each pixel in the image.
- get_backplane_map(name: str, **map_kwargs: Unpack[_MapKwargs]) ndarray [source]
Generate map of backplane values.
This method creates a copy of the generated image, so the returned map can be safely modified without affecting the cached value (unlike the return values from functions such as
get_lon_map()
).This method is equivalent to
body.get_backplane(name).get_map(degree_interval).copy()
- Parameters:
name – Name of the desired backplane. This is standardised with
standardise_backplane_name()
and used to choose a registered backplane frombackplanes
.**map_kwargs – Additional arguments are passed to
generate_map_coordinates()
to specify and customise the map projection.
- Returns:
Array containing map of the backplane’s values over the surface of the target body.
- plot_backplane_img(name: str, ax: matplotlib.axes._axes.Axes | None = None, show: bool = False, **kwargs) Axes [source]
Plot a backplane image with the wireframe outline of the target.
Note that a generated backplane image will depend on the disc parameters
(x0, y0, r0, rotation)
at the time this function is called. Generating the same backplane when there are different disc parameter values will produce a different image.- Parameters:
name – Name of the desired backplane.
ax – Passed to
plot_wireframe_xy()
.show – Passed to
plot_wireframe_xy()
.**kwargs – Passed to Matplotlib’s
imshow
when plotting the backplane image. For example, can be used to set the colormap of the plot usingbody.plot_backplane_img(..., cmap='Greys')
.
- Returns:
The axis containing the plotted data.
- plot_backplane_map(name: str, ax: matplotlib.axes._axes.Axes | None = None, show: bool = False, plot_kwargs: dict | None = None, **map_kwargs: Unpack[_MapKwargs]) Axes [source]
Plot a map of backplane values on the target body.
- Parameters:
name – Name of the desired backplane.
ax – Matplotlib axis to use for plotting. If
ax
is None (the default), then a new figure and axis is created.show – Toggle showing the plotted figure with
plt.show()
plot_kwargs – Passed to
plot_map()
when plotting the backplane map. For example, can be used to set the colormap of the plot usingbody.plot_backplane_map(..., plot_kwargs=dict(cmap='Greys'))
.**map_kwargs – Additional arguments are passed to
generate_map_coordinates()
to specify and customise the map projection.
- Returns:
The axis containing the plotted data.
- generate_map_coordinates(projection: str = 'rectangular', degree_interval: float = 1, lon: float = 0, lat: float = 0, size: int = 100, lon_coords: numpy.ndarray | tuple | None = None, lat_coords: numpy.ndarray | tuple | None = None, projection_x_coords: numpy.ndarray | tuple | None = None, projection_y_coords: numpy.ndarray | tuple | None = None, xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None) tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, pyproj.transformer.Transformer, dict[str, Any]] [source]
Generate underlying coordinates and transformation for a given map projection.
The built-in map projections (i.e. possible values for the
projection
argument) are:'rectangular'
: cylindrical equirectangular projection onto a regular longitude and latitude grid. The resolution of the map can be controlled with thedegree_interval
argument which sets the spacing in degrees between grid points. This is the default map projection.'orthographic'
: orthographic projection where the central longitude and latitude can be customized with thelon
andlat
arguments. The size of the map can be controlled with thesize
argument.'azimuthal'
: azimuthal equidistant projection where the central longitude and latitude can be customized with thelon
andlat
arguments. The size of the map can be controlled with thesize
argument.'azimuthal equal area'
: Lambert azimuthal equal area projection where the central longitude and latitude can be customized with thelon
andlat
arguments. The size of the map can be controlled with thesize
argument.'manual'
: manually specify the longitude and latitude coordinates to use for each point on the map with thelon_coords
andlat_coords
arguments.
Projections can also be specified by passing a pyproj projection string to the
projection
argument. If you are manually specifying a projection, you must also specifyprojection_x_coords
andprojection_y_coords
to provide the x and y coordinates to project the data to. See https://proj.org/operations/projections for a list of projections that can be used. The provided projection string will be passed topyproj.CRS
.Hint
You generally don’t need to call this method directly. Instead, pass your desired arguments directly to functions like
get_backplane_map()
ormap_img()
.Usage examples:
# Generate default rectangular map for emission backplane body.get_backplane_map('EMISSION') # Generate default rectangular map at lower resolution and only covering # the northern hemisphere body.get_backplane_map('EMISSION', degree_interval=10, ylim=(0, np.inf)) # Generate orthographic map of northern hemisphere body.get_backplane_map('EMISSION', projection='orthographic', lat=90) # Plot orthographic map of southern hemisphere with higher resolution body.plot_backplane_map( 'EMISSION', projection='orthographic', lat=-90, size=500 ) # Get azimuthal equidistant map projection of image, centred on specific # coordinate body.map_img(img, projection='azimuthal', lon=45, lat=30)
- Parameters:
projection – String describing map projection to use (see list of supported projections above).
degree_interval – Degree interval for
'rectangular
projection.lon – Central longitude of
'orthographic'
,'azimuthal'
and'azimuthal equal area'
projections.lat – Central latitude of
'orthographic'
,'azimuthal'
and'azimuthal equal area'
projections.size – Pixel size (width and height) of generated
'orthographic'
,'azimuthal'
and'azimuthal equal area'
projections.lon_coords – Longitude coordinates to use for
'manual'
projection. This must be a tuple (e.g. uselon_coords=tuple(np.linspace(0, 360, 100))
) - this allows mapping arguments and outputs to be cached).lat_coords – Latitude coordinates to use for
'manual'
projection. This must be a tuple.projection_x_coords – Projected x coordinates to use with a pyproj projection string. This must be a tuple.
projection_y_coords – Projected x coordinates to use with a pyproj projection string. This must be a tuple.
xlim – Tuple of
(x_min, x_max)
limits in the projected x coordinates of the map. IfNone
, the default, then the no limits are applied (i.e. the entire globe will be mapped). Ifxlim
is provided, it should be a tuple of two floats specifying the minimum and maximum x coordinates to project the map to. For example, to only plot the western hemisphere, you can use usexlim=(0, 180)
in a rectangular projection. Note that these limits are expressed in the projected coordinates of the map. Setting the limits can be useful to speed up the performance of mapping when only a subset of the map is needed (such as for observations with limited spatial extent). If you only want to set one limit, then you can pass infinity e.g.xlim=(315, np.inf)
to only set the minimum limit. The limits are implemented usingx_to_keep = (x >= min(xlim)) & (x <= max(xlim))
, so the ordering of the limits does not matter. Note that the limit calculations assume that the data is on a rectangular grid (i.e. all rows have the same x coordinates and all columns have the same y coordinates), so may produce unexpected results if a custom projection is used.ylim – Tuple of
(y_min, y_max)
limits in the projected y coordinates of the map. IfNone
, the default, then the no limits are applied. Seexlim
for more details.
- Returns:
(lons, lats, xx, yy, transformer, info)
tuple wherelons
andlats
are the longitude and latitude coordinates of the map,xx
andyy
are the projected coordinates of the map,transformer
is apyproj.Transformer
object that can be used to transform between the two coordinate systems, andinfo
is a dictionary containing the arguments used to build the map (e.g. for the default case this would be{'projection': 'rectangular', 'degree_interval': 1, 'xlim': None, 'ylim': None}
).
- get_lon_img() ndarray [source]
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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 fromget_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 alsoget_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 fromget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 alsoget_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 inBodyXY
,Body
andSpiceBase
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 thedata
itself (and optionally a FITSheader
). Thenx
andny
values forBodyXY
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 thepath
to the FITS file e.g.Observation('path/to/file.fits')
. Manually specified parameters will take precedence, soObservation('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
andutc
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
thendata
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 ifpath
is None.header – FITS header which corresponds to the provided
data
. This is optional and should only be provided ifpath
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.
- 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
andutc
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.
See also
rotation_from_wcs()
andplate_scale_from_wcs()
.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
andHIERARCH 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 oruse_header_offsets
isFalse
, 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.See also
disc_from_wcs()
.- Parameters:
*args – See
disc_from_wcs()
for additional arguments.**kwargs –
See
disc_from_wcs()
for additional arguments.
- Raises:
ValueError – if no WCS information is found in the FITS header, or validation fails.
- rotation_from_wcs(*args, **kwargs) None [source]
Set disc rotation using WCS information in the observation’s FITS header.
See also
disc_from_wcs()
.- Parameters:
*args – See
disc_from_wcs()
for additional arguments.**kwargs –
See
disc_from_wcs()
for additional arguments.
- Raises:
ValueError – if no WCS information is found in the FITS header, or validation fails.
- plate_scale_from_wcs(*args, **kwargs) None [source]
Set plate scale (i.e.
r0
) using WCS information in the observation’s FITS header.See also
disc_from_wcs()
.- Parameters:
*args – See
disc_from_wcs()
for additional arguments.**kwargs –
See
disc_from_wcs()
for additional arguments.
- Raises:
ValueError – if no WCS information is found in the FITS header, or validation fails.
- get_wcs_offset(*args, **kwargs) tuple[float, float, float, float] [source]
Warning
This is a beta feature and the API may change in future.
Get the difference between the current disc parameters and the disc parameters calculated from the WCS information in the observation’s FITS header.
For example, this function can be used to retrieve the cumulative offset after adjusting the disc position:
# Initialise disc with parameters from WCS observation.disc_from_wcs() # Adjust the disc position observation.adjust_disc_params(1, 2, 3, 4) observation.adjust_disc_params(dx=0.1) # Retrieve the cumulative offset print(observation.get_wcs_offset()) # (1.1, 2.0, 3.0, 4.0)
Similarly, this function can be used to retrieve the offset after running the GUI to fit the disc:
observation.run_gui() print(observation.get_wcs_offset())
See also
get_wcs_arcsec_offset()
.- Parameters:
*args – See
disc_from_wcs()
for additional arguments.**kwargs –
See
disc_from_wcs()
for additional arguments.
- Returns:
(dx, dy, dr, drotation)
tuple containing the differences in disc parameters between the current disc parameters (i.e. those returned byBodyXY.get_disc_params()
) and the disc parameters calculated from the WCS information in the observation’s FITS header.dx
anddy
give the difference in the disc centre position in pixels,dr
gives the difference in the disc radius in pixels, anddrotation
gives the difference in the rotation angle in degrees.- Raises:
ValueError – if no WCS information is found in the FITS header, or validation fails.
- get_wcs_arcsec_offset(*args, check_is_position_offset_only: bool = True, **kwargs) tuple[float, float] [source]
Warning
This is a beta feature and the API may change in future.
Get the offset in RA/Dec celestial coordinates between the current disc location and the disc location calculated from the WCS information in the observation’s FITS header.
For example, this function can be used to retrieve the cumulative offset after adjusting the disc position:
# Initialise disc with parameters from WCS observation.disc_from_wcs() # Adjust the disc position observation.add_arcsec_offset(10, 10) observation.add_arcsec_offset(dra_arcsec=1.23) # Retrieve the cumulative offset print(observation.get_wcs_arcsec_offset()) # (11.23, 10.0)
Similarly, this function can be used to retrieve the offset after running the GUI to fit the disc:
observation.run_gui() print(observation.get_wcs_arcsec_offset())
The RA/Dec offsets returned by this function are generally only meaningful if the disc location
(x0, y0)
is the only difference between the current disc parameters and those derived from the WCS. Therefore, by default this function checks that thedr
anddrotation
values returned byget_wcs_offset()
are sufficiently small to be considered a position offset only, and raises aValueError
if this is not the case. This check can be disabled by settingcheck_is_position_offset_only
toFalse
.See also
get_wcs_offset()
.- Parameters:
*args – See
disc_from_wcs()
for additional arguments.**kwargs –
See
disc_from_wcs()
for additional arguments.check_is_position_offset_only – If
True
(the default), check that thedr
anddrotation
values returned byget_wcs_offset()
are sufficiently small to be considered a position offset only. If this isFalse
, then thedr
anddrotation
values are not checked.
- Returns:
(dra_arcsec, ddec_arcsec)
tuple containing the offsets in arcseconds in the RA and Dec celestial coordinates between the current disc location (i.e. those returned byBodyXY.get_disc_params()
) and the disc location calculated from the WCS information in the observation’s FITS header.- Raises:
ValueError – if no WCS information is found in the FITS header, or validation fails. A ValueError is also raised if
check_is_position_offset_only
isTrue
and thedr
ordrotation
values returned byget_wcs_offset()
are not sufficiently small.
- fit_disc_position() None [source]
Automatically find and set
x0
andy0
so that the planet’s disc is fit to the brightest part of the data.
- fit_disc_radius() None [source]
Automatically find and set
r0
using aperture photometry.This routine calculates the brightness in concentric annular apertures around
(x0, y0)
and setsr0
as the radius where the brightness decreases the fastest. Note that this uses circular apertures, so will be less reliable for targets with greater flattening and may not work well for targets which are not entirely in the image frame.- Raises:
ValueError – if
x0
ory0
are not within the image frame.
- get_mapped_data(interpolation: Literal['nearest', 'linear', 'quadratic', 'cubic'] = 'linear', **map_kwargs: Unpack[_MapKwargs]) ndarray [source]
Projects the observed
data
onto a map. SeeBodyXY.generate_map_coordinates()
for details about customising the projection used.For larger datasets, it can take some time to map every wavelength. Therefore, the mapped data is automatically cached (in a similar way to backplanes - see
BodyXY
) so that subsequent calls to this function do not have to recompute the mapped data. As with cached backplanes, the cached mapped data is automatically cleared if any disc parameters are changed (i.e. you shouldn’t need to worry about the cache, it all happens ‘magically’ behind the scenes).- Parameters:
degree_interval – Interval in degrees between the longitude/latitude points. Passed to
BodyXY.map_img()
.interpolation – Interpolation used when mapping. This can either any of
'nearest'
,'linear'
,'quadratic'
or'cubic'
. Passed toBodyXY.map_img()
.**map_kwargs – Additional arguments are passed to
BodyXY.generate_map_coordinates()
to specify and customise the map projection.
- Returns:
Array containing cube of maped 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.
- append_to_header(keyword: str, value: str | float | bool | complex, comment: str | None = None, hierarch_keyword: bool = True, header: astropy.io.fits.header.Header | None = None, truncate_strings: bool = True, remove_existing: bool = True)[source]
Add a card to a FITS header. If a
header
is not specified, thenheader
is modified.By default, the keyword is modified to provide a consistent keyword prefix for all header cards added by this routine.
- Parameters:
keyword – Card keyword.
value – Card value.
comment – Card comment. If unspecified not comment will be added.
hierarch_keyword – Toggle adding the keyword prefix from
FITS_KEYWORD
to the keyword.header – FITS Header which the card will be added to in-place. If
header
isNone
, thenheader
will be modified.truncate_strings – Allow string values to be truncated if they will create a card longer than 80 characters.
remove_existing – Remove any existing cards with the same key before adding the new card.
- add_header_metadata(header: astropy.io.fits.header.Header | None = None)[source]
Add automatically generated metadata a FITS header. This is automatically called by
save()
soadd_header_metadata
does not normally need to be called manually.- Parameters:
header – FITS Header which the metadata will be added to in-place. If
header
isNone
, thenheader
will be modified.
- make_filename(extension: str = '.fits', prefix: str = '', suffix: str = '') str [source]
Automatically generates a useful filename from the target name and date of the observation, e.g.
'JUPITER_2000-01-01T123456.fits'
.- Parameters:
extension – Optionally specify the file extension to add to the filename.
prefix – Optionally specify filename prefix.
suffix – Optionally specify filename suffix.
- Returns:
Filename built from the target name and observation date.
- save_observation(path: str, *, include_wireframe: bool = True, wireframe_kwargs: dict[str, Any] | None = None, show_progress: bool = False, print_info: bool = True) None [source]
Save a FITS file containing the observed data and generated backplanes.
The primary HDU in the FITS file will be the
data
andheader
of the observed data, with appropriate metadata automatically added to the header byadd_header_metadata()
. The backplanes are generated from all the registered backplanes inBodyXY.backplanes
and are saved as additional HDUs in the FITS file.For larger image sizes, the backplane generation can be slow, so this function may take some time to complete.
- Parameters:
path – Filepath of output file.
include_wireframe – Toggle generating and saving wireframe overlay image as an additional backplane of the output FITS file. The wireframe is generated by
BodyXY.get_wireframe_overlay_img()
.wireframe_kwargs – Dictionary of keyword arguments passed to
BodyXY.get_wireframe_overlay_img()
to customise the wireframe overlay.show_progress – Display a progress bar rather than printing progress info. This does not have an effect if
show_progress=True
was set when creating thisObservation
.print_info – Toggle printing of progress information (defaults to
True
).
- save_mapped_observation(path: str, *, interpolation: Literal['nearest', 'linear', 'quadratic', 'cubic'] = 'linear', include_backplanes: bool = True, include_wireframe: bool = True, wireframe_kwargs: dict[str, Any] | None = None, show_progress: bool = False, print_info: bool = True, **map_kwargs: Unpack[_MapKwargs]) None [source]
Save a FITS file containing the mapped observation in a cylindrical projection.
The mapped data is generated using
get_mapped_data()
, and mapped backplane data is saved by default.For larger image sizes, the map projection and backplane generation can be slow, so this function may take some time to complete.
- Parameters:
path – Filepath of output file.
interpolation – Interpolation used when mapping. This can either any of
'nearest'
,'linear'
,'quadratic'
or'cubic'
. Passed toBodyXY.map_img()
.include_backplanes – Toggle generating and saving backplanes to output FITS file.
include_wireframe – Toggle generating and saving wireframe overlay map as an additional backplane of the output FITS file. The wireframe is generated by
BodyXY.get_wireframe_overlay_map()
.wireframe_kwargs – Dictionary of keyword arguments passed to
BodyXY.get_wireframe_overlay_map()
to customise the wireframe overlay.show_progress – Display a progress bar rather than printing progress info. This does not have an effect if
show_progress=True
was set when creating thisObservation
.print_info – Toggle printing of progress information (defaults to
True
).**map_kwargs – Additional arguments are passed to
BodyXY.generate_map_coordinates()
to specify and customise the map projection.
- run_gui() list[tuple[float, float]] [source]
Run an interactive GUI to display and adjust the fitted observation.
This modifies the
Observation
object in-place, so can be used within a script to e.g. interactively fit the planet’s disc. Simply run the GUI, adjust the parameters until the disc is fit, then close the GUI and theObservation
object will have your new values:# Load in some data observation = planetmapper.Observation('exciting_data.fits') # Use the GUI to manually fit the disc and set the x0,y0,r0,rotation values observation.run_gui() # At this point, you can use the manually fitted observation observation.plot_wireframe_xy()
Hint
Once you have manually fitted the disc, you can simply close the user interface window and the disc parameters will be updated to the new values. This means that you don’t need to click the
Save...
button unless you specifically want to save a navigated file to disk.The return value can also be used to interactively select a locations::
observation = planetmapper.Observation('exciting_data.fits') clicks = observation.run_gui() ax = observation.plot_wireframe_radec() for x, y in clicks: ra, dec = observation.xy2radec() ax.scatter(ra, dec)
Note
The
Open...
button is disabled for user interfaces created by this method to ensure that only oneObservation
object is modified by the user interface.If you want the full user interface functionality instead, then call
planetmapper
from the command line or create and run a user interface manually usingplanetmapper.gui.GUI.run()
.- Returns:
List of
(x, y)
pixel coordinate tuples corresponding to where the user clicked on the plot window to mark a location.
- class planetmapper.BasicBody(target: str | int, utc: str | datetime.datetime | float | None = None, observer: str | int = 'EARTH', *, aberration_correction: str = 'CN', observer_frame: str = 'J2000', **kwargs)[source]
Bases:
BodyBase
Class representing astronomical body which is treated as a point source.
This is typically used for objects which have limited data in the SPICE kernels (e.g. minor satellites which do not have well known radii). Usually, you are unlikely to need to create
BasicBody
instances directly, but they may be returned when usingBody.create_other_body()
.This is a very simplified version of
Body
.- Parameters:
- 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()
.
- dtm: datetime.datetime
Python timezone aware datetime of the observation corresponding to
utc
.