Core modules

angle_utils

Angle parsing and formatting (ported from viewer3_utils.f ParseAngle and DMS_string).

Ported from FORTRAN viewer3_utils.f.

dms_string(value: float, separator: str, ndecimal: int = 3) → str[source]

Format angle as degrees/hours, minutes, seconds (port of DMS_string).

Parameters:

value – Angle in degrees (or hours for RA).
separator – 3-character string for separators (e.g. ‘hms’ or ‘dms’).
ndecimal – 3 or 4 decimal places for seconds.

Returns:

Formatted string (e.g. “ 12 30 45.123”).

parse_angle(string: str) → float | None[source]

Parse an angle as hours/degrees, minutes, and seconds (port of ParseAngle).

Accepts three numbers (deg/h, m, s), two (deg/h, m), or one (deg/h). Minutes and seconds must be non-negative. Leading minus makes result negative. Returned value is in the same units as the first number (hours or degrees).

Parameters:: string – Whitespace-separated numbers (e.g. “12 30 45” or “-5 30”).
Returns:: Angle in hours or degrees, or None on parse failure.

config

Configuration: SPICE paths and temp/starlist paths from environment.

get_leapsecs_path() → str[source]

Return path to a NAIF LSK leap seconds file for rms-julian.

rms-julian expects a NAIF LSK (e.g. naif0012.tls); plain leapsecs.txt may require fallback to bundled LSK. Prefers JULIAN_LEAPSECS, then .tls under SPICE_PATH, then leapsecs.txt.

Returns:: Path string to LSK or leapsecs file.

get_spice_path() → str[source]

Return SPICE kernel root directory (SPICE_PATH env var or default).

Returns:: Path string (from tools.inc / rspk_common.inc convention).

get_starlist_candidate_paths(starlist_filename: str) → list[Path][source]

Return candidate paths for a starlist file for both checkout and installed use.

Tries STARLIST_PATH first, then the bundled ephemeris_tools._web_tools package resource so starlists are found when the package is installed.

Parameters:: starlist_filename – Basename of the starlist file (e.g. starlist_sat.txt).
Returns:: List of Path candidates in order of preference; callers should use the first path that exists.

get_starlist_path() → str[source]

Return star catalog directory (STARLIST_PATH env var or default).

Returns:: Path string.

get_temp_path() → str[source]

Return temporary/output directory (TEMP_PATH env var or default).

Returns:: Path string.

constants

Fixed constants used across ephemeris, viewer, and tracker.

From FORTRAN tools.inc. Categories include: body IDs (NAIF), spacecraft names/codes and planet number mapping; time constants (seconds per minute/hour/ day, noon offset); angle/unit constants (degrees per circle, DMS/arcmin/arcsec, RA degrees per hour); and configuration constants (default interval, min interval, max FOV, alignment, string lengths).

spacecraft_code_to_id(sc_code: int) → str | None[source]

Return spacecraft abbreviation for NAIF code (port of RSPK_GetSCID inverse).

Parameters:: sc_code – NAIF spacecraft ID (e.g. -82 for Cassini).
Returns:: Abbreviation (e.g. ‘CAS’) or None if unknown.

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

Return NAIF ID for spacecraft by name or abbreviation (port of RSPK_GetSCID).

Parameters:: name – Full name or ID (e.g. ‘VG1’, ‘Voyager 1’, ‘CASSINI’).
Returns:: NAIF integer ID or None if not found.

params

Unified parameter parsing for ephemeris, tracker, and viewer (env, CLI, API).

class EphemerisParams(planet_num: int, start_time: str, stop_time: str, interval: float = 1.0, time_unit: str = 'hour', ephem_version: int = 0, viewpoint: str = 'Earth', observatory: str = "Earth's center", latitude_deg: float | None = None, longitude_deg: float | None = None, lon_dir: str = 'east', altitude_m: float | None = None, sc_trajectory: int = 0, columns: list[int] = <factory>, mooncols: list[int] = <factory>, moon_ids: list[int] = <factory>, output: TextIO | None = None, ephem_display: str | None = None, columns_display: list[str] | None = None, mooncols_display: list[str] | None = None, moons_display: list[str] | None = None)[source]

Bases: object

Parameters for ephemeris table generation (ephem3_xxx.f request summary).

altitude_m: float | None = None

columns: list[int]

columns_display: list[str] | None = None

ephem_display: str | None = None

ephem_version: int = 0

interval: float = 1.0

latitude_deg: float | None = None

lon_dir: str = 'east'

longitude_deg: float | None = None

moon_ids: list[int]

mooncols: list[int]

mooncols_display: list[str] | None = None

moons_display: list[str] | None = None

observatory: str = "Earth's center"

output: TextIO | None = None

planet_num: int

sc_trajectory: int = 0

start_time: str

stop_time: str

time_unit: str = 'hour'

viewpoint: str = 'Earth'

class ExtraStar(name: str = '', ra_deg: float = 0.0, dec_deg: float = 0.0)[source]

Bases: object

Optional extra star marker for viewer plots.

Parameters:

name – Display name.
ra_deg – Right ascension in degrees.
dec_deg – Declination in degrees.

dec_deg: float = 0.0

name: str = ''

ra_deg: float = 0.0

class Observer(name: str | None = None, latitude_deg: float | None = None, longitude_deg: float | None = None, lon_dir: str = 'east', altitude_m: float | None = None, sc_trajectory: int = 0)[source]

Bases: object

Observer location and trajectory selection shared by all tools.

Parameters:

name – Named observer, observatory, or spacecraft identifier.
latitude_deg – Observer latitude in degrees.
longitude_deg – Observer longitude in degrees; east-positive.
lon_dir – Original longitude direction token from CGI/CLI (east/west).
altitude_m – Observer altitude in meters.
sc_trajectory – Optional spacecraft trajectory selector.

altitude_m: float | None = None

latitude_deg: float | None = None

lon_dir: str = 'east'

longitude_deg: float | None = None

name: str | None = None

sc_trajectory: int = 0

class TrackerParams(planet_num: int, start_time: str, stop_time: str, interval: float = 1.0, time_unit: str = 'hour', observer: Observer = <factory>, ephem_version: int = 0, moon_ids: list[int] = <factory>, ring_names: list[str] | None = None, sc_trajectory: int = 0, xrange: float | None = None, xunit: str = 'arcsec', title: str = '', output_ps: TextIO | None = None, output_txt: TextIO | None = None, ephem_display: str | None = None, moons_display: list[str] | None = None, rings_display: list[str] | None = None, viewpoint_display: str | None = None)[source]

Bases: object

Structured inputs for tracker backend execution.

ephem_display: str | None = None

ephem_version: int = 0

interval: float = 1.0

moon_ids: list[int]

moons_display: list[str] | None = None

observer: Observer

output_ps: TextIO | None = None

output_txt: TextIO | None = None

planet_num: int

ring_names: list[str] | None = None

rings_display: list[str] | None = None

sc_trajectory: int = 0

start_time: str

stop_time: str

time_unit: str = 'hour'

title: str = ''

viewpoint_display: str | None = None

xrange: float | None = None

xunit: str = 'arcsec'

Bases: object

Viewer center specification.

Parameters:

mode – One of body, ansa, J2000, or star.
body_name – Center body name when mode is body.
ansa_name – Ring ansa name when mode is ansa.
ansa_ew – Ring ansa side (east or west) when mode is ansa.
ra_deg – Right ascension in degrees when mode is J2000.
dec_deg – Declination in degrees when mode is J2000.
star_name – Star name when mode is star.

ansa_ew: str | None = None

ansa_name: str | None = None

body_name: str | None = None

dec_deg: float | None = None

mode: str = 'body'

ra_deg: float | None = None

star_name: str | None = None

Bases: object

Display-only strings preserved from CGI inputs.

Parameters:

ephem_display – Ephemeris display string.
moons_display – Moon selection display string.
rings_display – Ring selection display string.
viewpoint_display – Raw lat/lon/alt caption string from CGI, if present.
center_ra_display – Raw center RA text from CGI (for J2000 summary line).
center_ra_type_display – Raw center RA units text from CGI.
center_dec_display – Raw center Dec text from CGI (for J2000 summary line).
moonpts_display – Raw moon point-size text from CGI.
blank_display – Raw blank-disk toggle text from CGI.
meridians_display – Raw prime-meridians toggle text from CGI.
additional_display – Raw additional-star toggle text from CGI.
extra_name_display – Raw extra star name from CGI.
extra_ra_display – Raw extra star RA from CGI.
extra_ra_type_display – Raw extra star RA units from CGI.
extra_dec_display – Raw extra star Dec from CGI.

additional_display: str | None = None

blank_display: str | None = None

center_dec_display: str | None = None

center_ra_display: str | None = None

center_ra_type_display: str | None = None

ephem_display: str | None = None

extra_dec_display: str | None = None

extra_name_display: str | None = None

extra_ra_display: str | None = None

extra_ra_type_display: str | None = None

meridians_display: str | None = None

moonpts_display: str | None = None

moons_display: str | None = None

rings_display: str | None = None

viewpoint_display: str | None = None

class ViewerParams(planet_num: int, time_str: str, fov_value: float = 1.0, fov_unit: str = 'degrees', center: ViewerCenter = <factory>, observer: Observer = <factory>, ephem_version: int = 0, moon_ids: list[int] | None = None, ring_names: list[str] | None = None, blank_disks: bool = False, opacity: str = 'Transparent', labels: str = 'Small (6 points)', moonpts: float = 0.0, peris: str = 'None', peripts: float = 4.0, meridians: bool = False, arcmodel: str | None = None, arcpts: float = 4.0, show_standard_stars: bool = False, extra_star: ExtraStar | None = None, other_bodies: list[str] | None = None, torus: bool = False, torus_inc: float = 6.8, torus_rad: float = 422000.0, moremoons: bool = False, title: str = '', display: ViewerDisplayInfo | None = None, output_ps: TextIO | None = None, output_txt: TextIO | None = None)[source]

Bases: object

Structured inputs for viewer backend execution.

arcmodel: str | None = None

arcpts: float = 4.0

blank_disks: bool = False

center: ViewerCenter

display: ViewerDisplayInfo | None = None

ephem_version: int = 0

extra_star: ExtraStar | None = None

fov_unit: str = 'degrees'

fov_value: float = 1.0

labels: str = 'Small (6 points)'

meridians: bool = False

moon_ids: list[int] | None = None

moonpts: float = 0.0

moremoons: bool = False

observer: Observer

opacity: str = 'Transparent'

other_bodies: list[str] | None = None

output_ps: TextIO | None = None

output_txt: TextIO | None = None

peripts: float = 4.0

peris: str = 'None'

planet_num: int

ring_names: list[str] | None = None

show_standard_stars: bool = False

time_str: str

title: str = ''

torus: bool = False

torus_inc: float = 6.8

torus_rad: float = 422000.0

ephemeris_params_from_env() → EphemerisParams | None[source]

Build EphemerisParams from CGI-style environment variables.

Reads NPLANET, start, stop, interval, viewpoint, columns, etc. from env.

Returns:: EphemerisParams or None if required keys are missing/invalid.

parse_center(planet_num: int, tokens: list[str]) → ViewerCenter[source]

Parse CLI --center tokens into a structured viewer center definition.

Parameters:

planet_num – Planet number (4-9) for body/ring lookups.
tokens – Tokenized center specification from CLI.

Returns:

Parsed center as a ViewerCenter object.

parse_column_spec(tokens: list[str]) → list[int][source]

Convert column tokens to column IDs (ephem3_xxx.f COL_*).

Parameters:: tokens – List of decimal IDs or case-insensitive names (e.g. ymdhms, radec).
Returns:: List of column IDs; invalid tokens are skipped (logged).

parse_fov(tokens: list[str]) → tuple[float, str][source]

Parse CLI --fov tokens into numeric value and canonical unit string.

Parameters:: tokens – Tokenized FOV value from CLI, where the first token is numeric and remaining tokens form the unit string.
Returns:: Tuple (value, unit) where value is the parsed float and unit is the canonical unit string.
Raises:: ValueError – If no tokens are provided, numeric value cannot be parsed, or the unit is unknown.

parse_mooncol_spec(tokens: list[str]) → list[int][source]

Convert moon column tokens to moon column IDs (MCOL_*).

Parameters:: tokens – List of decimal IDs or case-insensitive names (e.g. radec, offset).
Returns:: List of moon column IDs; invalid tokens are skipped (logged).

parse_observer(tokens: list[str]) → Observer[source]

Parse CLI observer tokens into a structured observer definition.

Parameters:: tokens – Observer tokens from CLI. Either a named observer/observatory or a numeric latitude longitude altitude triplet.
Returns:: Parsed observer object.
Raises:: ValueError – If the input looks numeric but is not a valid triplet.

parse_planet(value: str) → int[source]

Parse planet specifier: integer 4-9 or name (mars..pluto).

Parameters:: value – Planet number string or name (case-insensitive).
Returns:: Planet number (4-9).
Raises:: ValueError – If value is not a valid planet.

parse_ring_spec(planet_num: int, tokens: list[str]) → list[int][source]

Convert ring tokens (int strings or names) to ring option codes.

Each token may be a decimal ring option code (e.g. 61) or a case-insensitive ring name (e.g. main, gossamer). The set of valid names depends on the planet. Unknown tokens are skipped with a log message.

Parameters:

planet_num – Planet number (4-9).
tokens – List of string tokens from the CLI.

Returns:

List of integer ring option codes.

parse_viewer_rings(planet_num: int, tokens: list[str]) → list[str][source]

Parse viewer ring tokens into canonical ring names.

Parameters:

planet_num – Planet number (4-9).
tokens – Ring name tokens from CLI.

Returns:

Canonical ring names in first-seen order. Supports all and none.

tracker_params_from_env() → TrackerParams | None[source]: Build TrackerParams from CGI-style environment variables.

viewer_params_from_env() → ViewerParams | None[source]: Build ViewerParams from CGI-style environment variables.

params_env

Build EphemerisParams, ViewerParams, TrackerParams from CGI-style env vars.

ephemeris_params_from_env() → EphemerisParams | None[source]

Build EphemerisParams from CGI-style environment variables.

Reads NPLANET, start, stop, interval, viewpoint, columns, etc. from env.

Returns:: EphemerisParams or None if required keys are missing/invalid.

tracker_params_from_env() → TrackerParams | None[source]: Build TrackerParams from CGI-style environment variables.

viewer_params_from_env() → ViewerParams | None[source]: Build ViewerParams from CGI-style environment variables.

record

Tabular output record formatting.

Ported from ephem3_xxx.f Rec_Init, Rec_Append, Rec_Write.

class Record(max_length: int = 4096)[source]

Bases: object

Fixed-width record buffer: append fields with single blank separator, write line.

append(string: str) → None[source]

Append a field with one blank separator before it (port of Rec_Append).

Parameters:: string – Text to append (truncated if would exceed max_length).

get_line() → str[source]: Return the current record as a string (no write or re-init).

init() → None[source]: Clear the record and reset length (port of Rec_Init).

write(stream: TextIO) → None[source]

Write the current record to stream and re-initialize (port of Rec_Write).

Parameters:: stream – Output text stream.

input_params

Input Parameters section (port of FORTRAN Summarize request).

write_input_parameters_ephemeris(stream: TextIO, params: EphemerisParams) → None[source]

Write Input Parameters section for ephemeris (port of ephem3_xxx Summarize).

Parameters:

stream – Output text stream.
params – Ephemeris parameters to summarize.

write_input_parameters_tracker(stream: TextIO, params: TrackerParams) → None[source]

Write Input Parameters section for tracker (port of tracker3_xxx Summarize).

Parameters:

stream – Output text stream.
params – Tracker parameters (from CLI or CGI).

write_input_parameters_viewer(stream: TextIO, params: ViewerParams) → None[source]

Write Input Parameters section for viewer (port of viewer3_* Summarize).

Parameters:

stream – Output text stream.
params – Viewer parameters (from CLI or CGI).

ephemeris

Ephemeris table generator (ported from ephem3_xxx.f).

generate_ephemeris(params: EphemerisParams, output: TextIO | None = None) → None[source]

Generate ephemeris table and write to output (port of ephem3_xxx.f).

Loads SPICE, sets observer from params, steps over time range, and writes requested columns (and moon columns) to the given stream.

Parameters:

params – Time range, planet, columns, viewpoint, etc.
output – Output text stream; if None, uses params.output.

Raises:

ValueError – Invalid start/stop time or time range.
RuntimeError – SPICE load failure.

time_utils

Time conversion wrappers around rms-julian (replaces FORTRAN Julian library).

day_from_ymd(year: int, month: int, day: int) → int[source]

Convert calendar date to days since J2000 (replaces FJUL_DUTCofYMD).

Parameters:

year – Calendar date.
month – Calendar date.
day – Calendar date.

Returns:

Days since J2000.

day_sec_from_tai(tai: float) → tuple[int, float][source]

Convert TAI to UTC (day, sec) (replaces FJUL_DUTCofTAI).

Parameters:: tai – TAI in seconds.
Returns:: (day, sec) where day is days since J2000.

format_utc(tai: float, fmt: str | None = None) → str[source]

Format TAI as UTC string (replaces FJUL_FormatPDS / FJUL_FormatDate).

Parameters:

tai – TAI in seconds.
fmt – Optional format string for rms-julian; None = default.

Returns:

Formatted UTC string.

hms_from_sec(sec: float) → tuple[int, int, float][source]

Convert seconds within day to (hour, minute, second) (replaces FJUL_HMSofSec).

Parameters:: sec – Seconds within day (0..86400).
Returns:: (hour, minute, second).

interval_seconds(interval: float, time_unit: str, *, min_seconds: float = 1.0, round_to_minutes: bool = False) → float[source]

Convert interval and time_unit to seconds.

Parameters:

interval – Numeric interval value.
time_unit – One of ‘sec’, ‘min’, ‘hour’, ‘day’ (case-insensitive, first 4 chars).
min_seconds – Minimum returned value (e.g. 60.0 for tracker).
round_to_minutes – If True, round result to nearest minute (60 * n).

Returns:

Interval in seconds, at least min_seconds, optionally rounded to minutes.

mjd_from_tai(tai: float) → float[source]

Convert TAI to Modified Julian Date (replaces FJUL_MJDofTAI).

Parameters:: tai – TAI in seconds.
Returns:: MJD (float).

parse_datetime(string: str) → tuple[int, float] | None[source]

Parse date/time string to UTC (day, sec) (replaces FJUL_ParseDT).

Parameters:: string – Date/time string (format accepted by rms-julian).
Returns:: (day, sec) where day is days since J2000, sec is seconds within that day; None on parse failure.

tai_from_day_sec(day: int, sec: float) → float[source]

Convert UTC (day, sec) to TAI seconds (replaces FJUL_TAIofDUTC + secs).

Parameters:

day – Days since J2000.
sec – Seconds within that day.

Returns:

TAI in seconds.

tai_from_jd(jd: float) → float[source]

Convert Julian Date to TAI seconds (replaces FJUL_TAIofJD).

Parameters:: jd – Julian Date.
Returns:: TAI in seconds.

tai_from_tdb(tdb: float) → float[source]

Convert TDB seconds to TAI (inverse of FJUL_ETofTAI).

Parameters:: tdb – TDB (ephemeris time) in seconds.
Returns:: TAI in seconds.

tdb_from_tai(tai: float) → float[source]

Convert TAI to TDB seconds (replaces FJUL_ETofTAI). Used as ET for SPICE.

Uses cspyce.unitim when SPICE kernels are loaded so ET matches FORTRAN (which uses the same CSPICE library). Falls back to rms-julian otherwise.

Parameters:: tai – TAI in seconds.
Returns:: TDB (ephemeris time) in seconds.

utc_to_et(day: int, sec: float) → float[source]

Convert UTC (day, sec) to ET (TDB) seconds for SPICE.

Parameters:

day – Days since J2000.
sec – Seconds within day.

Returns:

ET (TDB) in seconds.

yd_from_day(day: int) → tuple[int, int][source]

Convert day since J2000 to year and day-of-year (replaces FJUL_YDofDUTC).

Parameters:: day – Days since J2000.
Returns:: (year, day_of_year).

ymd_from_day(day: int) → tuple[int, int, int][source]

Convert day since J2000 to calendar date (replaces FJUL_YMDofDUTC).

Parameters:: day – Days since J2000.
Returns:: (year, month, day).

stars

Star catalog reader (ported from viewer3_utils.f ReadStars).

class Star(name: str, ra: float, dec: float)[source]

Bases: object

A single star entry: name and J2000 RA/Dec in radians.

dec: float

name: str

ra: float

read_stars(filepath: str | Path, max_stars: int = 100) → list[Star][source]

Read star list from file (port of ReadStars).

Format: for each star, a line with name, then RA (hours or h m s), then Dec (deg or d m s). Lines starting with ‘!’ are skipped.

Parameters:

filepath – Path to star catalog file.
max_stars – Maximum number of stars to read.

Returns:

List of Star with name, ra (radians), dec (radians).

tracker

Moon tracker tool: PostScript plot and text table (port of tracker3_xxx.f).

run_tracker(params: TrackerParams) → None[source]

Generate moon tracker PostScript plot and optional text table (tracker3_xxx.f).

Loads SPICE, computes moon offsets over the time range, draws plot and table.

Parameters:

params – Structured tracker inputs (planet, time range, interval, observer, moons, rings, output streams).

Raises:

ValueError – Invalid time range or planet.
RuntimeError – SPICE load failure.

tracker_params_from_legacy_kwargs(**kwargs: object) → TrackerParams[source]

Build TrackerParams from flat legacy keyword arguments (e.g. for tests).

Accepts the same keyword names as the legacy run_tracker signature.

viewer

Planet viewer tool: PostScript diagram and tables (port of viewer3_*.f).

get_planet_config(planet_num: int) → PlanetConfig | None[source]

Return PlanetConfig for planet number (port of viewer3_* planet config).

Parameters:: planet_num – Planet index 4 (Mars) through 9 (Pluto).
Returns:: PlanetConfig or None if planet_num not supported.

run_viewer(params: ViewerParams) → None[source]

Generate planet viewer PostScript diagram and FOV table (port of viewer3_*.f).

Loads SPICE, sets observer, computes geometry, and draws planet/rings/moons. Writes PostScript to params.output_ps (if set) and FOV table to params.output_txt or stdout.

Parameters:

params – Structured viewer inputs (planet, time, FOV, center, observer, rings, moons, display options, output streams).

Raises:

ValueError – Unknown planet or invalid time.
RuntimeError – SPICE load failure.

viewer_helpers

Planet viewer tool: PostScript diagram and tables (port of viewer3_*.f).

get_planet_config(planet_num: int) → PlanetConfig | None[source]

Return PlanetConfig for planet number (port of viewer3_* planet config).

Parameters:: planet_num – Planet index 4 (Mars) through 9 (Pluto).
Returns:: PlanetConfig or None if planet_num not supported.

viewer_params_from_legacy_kwargs(**kwargs: object) → ViewerParams[source]

Build ViewerParams from flat legacy keyword arguments (e.g. for tests).

Accepts the same keyword names as the legacy run_viewer signature (and _RunViewerKwargs). Used by tests that call run_viewer with keyword arguments.

install_web_tools

Install bundled web/tools files to a target directory.

Provides the install_ephemeris_tools_files entry point used when the package is installed via pip. Copies all files from the bundled web/tools tree into the given directory, preserving subdirectories (e.g. samples/).

install_web_tools(dest_dir: str | Path) → int[source]

Copy all files from the bundled web/tools into dest_dir.

Preserves directory structure (e.g. samples/). Skips __init__.py. Creates dest_dir and any subdirectories as needed.

Parameters:: dest_dir – Target directory to copy files into. Accepts a string, Path, or any os.PathLike.
Returns:: 0 on success, 1 on error.
Raises:: TypeError – If dest_dir is not a string or path-like object.

main() → int[source]: Entry point for the install_ephemeris_tools_files console script.