spice.spicer
spice.spicer
Spicer: surface illumination calculations via SPICE.
Provides a clean OO interface for computing illumination geometry, solar flux, and related quantities at surface points on solar system bodies.
Requires spiceypy and the NAIF generic kernels (LSK + PCK). The set of supported bodies is determined by the loaded PCK kernel — the default pck00011.tpc includes the Sun, all 8 planets, Pluto, 70+ moons, and a few asteroids (Ceres, Vesta, Lutetia). Additional bodies become available if you load further kernels via spiceypy.
Examples
>>> from planetarypy.spice.spicer import Spicer
>>> mars = Spicer("MARS")
>>> illum = mars.illumination(lon=137.4, lat=-4.6, time="2024-01-15T12:00:00")
>>> illum.solar_incidence
45.2
>>> illum.solar_flux
450.3Use units=True to get astropy Quantities instead of plain floats:
>>> mars = Spicer("MARS", units=True)
>>> illum = mars.illumination(lon=137.4, lat=-4.6, time="2024-01-15T12:00:00")
>>> illum.solar_incidence
<Quantity 45.2 deg>Classes
| Name | Description |
|---|---|
| IlluminationResult | Result of an illumination calculation. |
| Spicer | Surface illumination calculator for any solar system body. |
IlluminationResult
spice.spicer.IlluminationResult(
solar_incidence,
emission,
phase,
solar_flux,
subsolar_lon,
subsolar_lat,
l_s,
local_solar_time,
)Result of an illumination calculation.
All angles in degrees, flux in W/m². When created with units=True, values are astropy Quantities.
Attributes
| Name | Description |
|---|---|
| emission | Emission angle [deg] (0 if no observer specified). |
| l_s | Solar longitude (season) [deg]. |
| local_solar_time | Local solar time string. |
| phase | Phase angle [deg] (0 if no observer specified). |
| solar_flux | Solar flux at the surface [W/m²] (0 if incidence > 90°). |
| solar_incidence | Solar incidence angle [deg]. |
| subsolar_lat | Sub-solar latitude [deg]. |
| subsolar_lon | Sub-solar longitude [deg]. |
Spicer
spice.spicer.Spicer(body, units=False)Surface illumination calculator for any solar system body.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| body | str | NAIF body name (e.g. “MARS”, “MOON”, “ENCELADUS”). | required |
| units | bool | If True, return astropy Quantities with units. If False (default), return plain floats. | False |
Examples
>>> mars = Spicer("MARS")
>>> mars.radii
Radii(a=3396.19, b=3396.19, c=3376.2)
>>> mars.ref_frame
'IAU_MARS'Attributes
| Name | Description |
|---|---|
| Ls | Current solar longitude L_s [deg]. |
| radii | Body radii [km]. |
Methods
| Name | Description |
|---|---|
| center_to_sun | Vector from body center to Sun [km] at the given time. |
| illumination | Compute illumination at a surface point. |
| illumination_at | Compute illumination at a planetarypy Point. |
| north_azimuth_at | Compute north azimuth in a spacecraft image via SPICE. |
| solar_azimuth_at | Compute solar azimuth at a surface point via SPICE. |
| solar_constant | Solar constant at body center distance [W/m²]. |
| solar_longitude | Solar longitude L_s [deg] at the given time (default: now). |
| subsolar_point | Sub-solar point (lon, lat) in degrees at the given time. |
| sun_direction_at | Compute a surface point toward the sun for azimuth calculation. |
| supported_bodies | List all bodies available for Spicer calculations. |
center_to_sun
spice.spicer.Spicer.center_to_sun(time=None)Vector from body center to Sun [km] at the given time.
illumination
spice.spicer.Spicer.illumination(
lon,
lat,
time=None,
observer=None,
tau_atm=0.0,
slope=0.0,
aspect=0.0,
)Compute illumination at a surface point.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lon | float | Planetocentric longitude and latitude [deg]. | required |
| lat | float | Planetocentric longitude and latitude [deg]. | required |
| time | str or datetime | Observation time. Default: now. | None |
| observer | str | NAIF observer name (e.g. “MRO”) for emission/phase angles. If None, only solar incidence is computed. | None |
| tau_atm | float | Atmospheric optical depth for flux attenuation (default 0). | 0.0 |
| slope | float | Surface slope in degrees (0 = flat). The surface normal is tilted toward north by this amount. | 0.0 |
| aspect | float | Aspect angle in degrees, clockwise from north. Rotates the tilted normal around the vertical. Only used when slope > 0. | 0.0 |
Returns
| Name | Type | Description |
|---|---|---|
| IlluminationResult |
illumination_at
spice.spicer.Spicer.illumination_at(
point,
time=None,
observer=None,
tau_atm=0.0,
)Compute illumination at a planetarypy Point.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| point | planetarypy.geo.Point | Must have lon/lat. | required |
| time | See illumination(). |
None |
|
| observer | See illumination(). |
None |
|
| tau_atm | See illumination(). |
None |
north_azimuth_at
spice.spicer.Spicer.north_azimuth_at(lon, lat, time=None)Compute north azimuth in a spacecraft image via SPICE.
This would require the instrument boresight and orientation — not available with generic kernels alone. For now, raises NotImplementedError. Use the PDS index NORTH_AZIMUTH instead.
(Included as a placeholder for future mission kernel support.)
solar_azimuth_at
spice.spicer.Spicer.solar_azimuth_at(lon, lat, time=None)Compute solar azimuth at a surface point via SPICE.
Returns the azimuth of the sun measured clockwise from north in the local tangent plane. This is the standard geographic convention (N=0°, E=90°, S=180°, W=270°).
Independent of any PDS index — computed directly from SPICE ephemeris.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lon | float | Planetocentric longitude and latitude [deg]. | required |
| lat | float | Planetocentric longitude and latitude [deg]. | required |
| time | str or datetime | None |
Returns
| Name | Type | Description |
|---|---|---|
| float | Solar azimuth [deg], clockwise from north. |
solar_constant
spice.spicer.Spicer.solar_constant(time=None)Solar constant at body center distance [W/m²].
solar_longitude
spice.spicer.Spicer.solar_longitude(time=None)Solar longitude L_s [deg] at the given time (default: now).
subsolar_point
spice.spicer.Spicer.subsolar_point(time=None)Sub-solar point (lon, lat) in degrees at the given time.
sun_direction_at
spice.spicer.Spicer.sun_direction_at(lon, lat, time=None, pixel_res=0.5)Compute a surface point toward the sun for azimuth calculation.
Returns lon/lat of a point within one pixel of the origin but in the direction of the subsolar point. Use with Point.azimuth_to() to get solar azimuth.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lon | float | Origin surface point [deg]. | required |
| lat | float | Origin surface point [deg]. | required |
| time | str or datetime | None |
|
| pixel_res | float | Pixel size in km (default 0.5). | 0.5 |
Returns
| Name | Type | Description |
|---|---|---|
| sun_lon, sun_lat : float | Lon/lat [deg] of point toward sun. |
supported_bodies
spice.spicer.Spicer.supported_bodies()List all bodies available for Spicer calculations.
Returns bodies that have radii defined in the currently loaded SPICE kernels (typically the generic PCK kernel pck00011.tpc). Load additional kernels via spiceypy to extend this list.
Returns
| Name | Type | Description |
|---|---|---|
| list of (naif_id, name, equatorial_radius_km) |