pyRTX.visual.utils

Functions

`color_convert`(color[, size])	Converts a color to a list of colors of a specified size.
`plot_mesh`(mesh[, title, figsize, alpha, ...])	Plots one or more trimesh meshes using matplotlib.
`visualize_planet_field`(planet[, field, ...])	Visualize a planet mesh with color-mapped field values on its surface.

pyRTX.visual.utils.color_convert(color, size=1)[source]

Converts a color to a list of colors of a specified size.

Parameters:

color (str or tuple) – The color to be converted.
size (int, default 1) – The size of the list of colors to be returned.

Returns:

A list of RGBA color values.

Return type:

list

pyRTX.visual.utils.plot_mesh(mesh, title='3D Mesh', figsize=(10, 8), alpha=0.7, edge_color='k', face_color=None, labels=None, elev=30, azim=45)[source]

Plots one or more trimesh meshes using matplotlib.

Parameters:

mesh (trimesh.Trimesh or list of trimesh.Trimesh) – The mesh or meshes to plot.
title (str, default "3D Mesh") – The title of the plot.
figsize (tuple, default (10, 8)) – The size of the figure in inches.
alpha (float, default 0.7) – The transparency of the mesh faces.
edge_color (str or list of str, default 'k') – The color of the mesh edges.
face_color (str, list of str, or None, optional) – The color of the mesh faces. If None, automatic colors are used.
labels (list of str, optional) – Labels for each mesh, for use in the legend.
elev (float, default 30) – The elevation viewing angle in degrees.
azim (float, default 45) – The azimuthal viewing angle in degrees.

Returns:

A tuple containing the matplotlib figure and axis objects.

Return type:

tuple

Examples

>>> # Single mesh with default colors
>>> fig, ax = plot_mesh(mesh)

>>> # Single mesh with custom color
>>> fig, ax = plot_mesh(mesh, face_color='lightblue')

>>> # Multiple meshes with automatic colors
>>> fig, ax = plot_mesh([mesh1, mesh2, mesh3])

>>> # Multiple meshes with custom colors
>>> fig, ax = plot_mesh([mesh1, mesh2],
...                     face_color=['red', 'blue'],
...                     labels=['Mesh 1', 'Mesh 2'])

>>> # Custom viewing angle (top-down view)
>>> fig, ax = plot_mesh(mesh, elev=90, azim=0)

>>> # Side view
>>> fig, ax = plot_mesh(mesh, elev=0, azim=0)

pyRTX.visual.utils.visualize_planet_field(planet, field='temperature', epoch=None, cmap='viridis', figsize=(12, 10), show_colorbar=True, title=None, vmin=None, vmax=None, lighting=True, show_sun=False, elev=30, azim=45)[source]

Visualize a planet mesh with color-mapped field values on its surface.

Creates a 3D visualization of the planet with face colors representing physical properties such as temperature, albedo, or emissivity. Optionally displays the Sun direction vector. Useful for verifying planetary models and understanding spatial distributions of surface properties.

Parameters:

planet (Planet) – Planet object containing mesh geometry and surface properties.
field (str, default 'temperature') –
Surface field to visualize. Options:
- ’temperature’: Surface temperature (K)
- ’albedo’: Bond albedo (0-1)
- ’emissivity’: Infrared emissivity (0-1)
- ’area’: Face areas (for geometric verification)
epoch (float or None, default None) – SPICE ephemeris time for time-dependent fields. Required if temperature varies with time or if show_sun=True. If None, uses static values.
cmap (str, default 'viridis') –
Matplotlib colormap name. Common choices:
- ’viridis’: Good for temperature (dark to bright)
- ’plasma’: Alternative for temperature
- ’coolwarm’: Diverging colormap
- ’RdYlBu_r’: Red-yellow-blue (reversed)
figsize (tuple, default (12, 10)) – Figure size in inches (width, height).
show_colorbar (bool, default True) – If True, display colorbar showing the mapping from values to colors.
title (str or None, default None) – Custom plot title. If None, automatically generated based on field name.
vmin (float or None, default None) – Minimum value for color scale. If None, uses data minimum.
vmax (float or None, default None) – Maximum value for color scale. If None, uses data maximum.
lighting (bool, default True) – If True, apply directional lighting for better 3D perception. If False, use flat shading showing colors directly.
show_sun (bool, default False) – If True, draw an arrow showing the Sun direction. Requires epoch, spacecraft_name, and reference_frame to be specified.
spacecraft_name (str or None, default None) – Name of spacecraft for SPICE queries (e.g., ‘LRO’). Required if show_sun=True.
reference_frame (str or None, default None) – Reference frame for Sun direction vector (e.g., ‘LRO_SC_BUS’). Required if show_sun=True.
elev (float) – Elevation viewing angle in degrees (default: 30)
azim (float) – Azimuthal viewing angle in degrees (default: 45)

Returns:

fig (matplotlib.figure.Figure) – The figure object.
ax (matplotlib.axes.Axes) – The 3D axes object.

Notes

The function retrieves field values using Planet object methods: - Temperature: planet.getFaceTemperatures(epoch) - Albedo: planet.getFaceAlbedo() - Emissivity: planet.getFaceEmissivity()

Face colors are computed by mapping field values to the colormap range. The mesh is displayed using matplotlib’s 3D projection with face colors.

When show_sun=True, a yellow arrow is drawn from the planet center pointing toward the Sun. The arrow length is scaled to 1.5× the planet’s maximum dimension for visibility. The Sun position is queried from SPICE using the provided spacecraft_name and reference_frame.

For large meshes (>10000 faces), rendering may be slow. Consider using mesh subdivision or decimation to reduce face count.

Examples

>>> import spiceypy as sp
>>> from pyRTX.classes import Planet
>>>
>>> # Create planet with temperature map
>>> moon = Planet(name='Moon', radius=1737.4)
>>> moon.dayside_temperature = 400
>>> moon.nightside_temperature = 100
>>>
>>> # Visualize temperature at specific epoch with Sun direction
>>> epoch = sp.str2et('2024-01-01T12:00:00')
>>> fig, ax = visualize_planet_field(moon, field='temperature',
...                                  epoch=epoch, cmap='plasma',
...                                  show_sun=True,
...                                  spacecraft_name='LRO',
...                                  reference_frame='MOON_PA')
>>>
>>> # Visualize constant albedo
>>> moon.albedo = 0.12
>>> fig, ax = visualize_planet_field(moon, field='albedo', cmap='gray')