I/O

Satellite loading and trajectory persistence.

Trajectory I/O

save_trajectories

save_trajectories(
    trajectories: TrajectorySet,
    path: str | Path,
    *,
    format: TrajectoryFormat | None = None,
    observer_name: str | None = None,
    observer_lat: float | None = None,
    observer_lon: float | None = None,
) -> Path

Save multiple trajectories to a single file.

Parameters:

Name	Type	Description	Default
trajectories	TrajectorySet	List of trajectories to save.	required
path	str | Path	Output file path.	required
format	TrajectoryFormat | None	File format handler. Defaults to ArrowFormat.	None
observer_name	str | None	Optional name of the observing facility.	None
observer_lat	float | None	Optional latitude of the observer.	None
observer_lon	float | None	Optional longitude of the observer.	None

Returns:

Type	Description
Path	Path to the saved file.

Source code in src/sopp/io/trajectory.py

def save_trajectories(
    trajectories: TrajectorySet,
    path: str | Path,
    *,
    format: TrajectoryFormat | None = None,
    observer_name: str | None = None,
    observer_lat: float | None = None,
    observer_lon: float | None = None,
) -> Path:
    """Save multiple trajectories to a single file.

    Args:
        trajectories: List of trajectories to save.
        path: Output file path.
        format: File format handler. Defaults to ArrowFormat.
        observer_name: Optional name of the observing facility.
        observer_lat: Optional latitude of the observer.
        observer_lon: Optional longitude of the observer.

    Returns:
        Path to the saved file.
    """
    if format is None:
        from sopp.io.formats.arrow import ArrowFormat

        format = ArrowFormat()

    return format.save(
        trajectories,
        Path(path),
        observer_name=observer_name,
        observer_lat=observer_lat,
        observer_lon=observer_lon,
    )

TLE Loading

load_satellites

load_satellites(
    tle_file: Path | str,
    frequency_file: Path | str | None = None,
    file_format: str = "auto",
) -> list[Satellite]

Loads satellites from a TLE or OMM file and optionally attaches frequency data.

file_format may be "tle", "csv", "json", or "xml". The default "auto" picks the format by file extension; anything without a .csv/.json/.xml extension is treated as TLE.

Source code in src/sopp/io/tle.py

def load_satellites(
    tle_file: Path | str,
    frequency_file: Path | str | None = None,
    file_format: str = "auto",
) -> list[Satellite]:
    """
    Loads satellites from a TLE or OMM file and optionally attaches
    frequency data.

    file_format may be "tle", "csv", "json", or "xml". The default
    "auto" picks the format by file extension; anything without a
    .csv/.json/.xml extension is treated as TLE.
    """
    tle_path = Path(tle_file)

    if file_format == "auto":
        suffix = tle_path.suffix.lower().lstrip(".")
        file_format = suffix if suffix in OMM_FILE_FORMATS else "tle"

    if file_format == "tle":
        satellites = _parse_tle_file(tle_path)
    else:
        satellites = parse_omm_file(tle_path, file_format)

    if frequency_file:
        satellites = _attach_frequency_data(satellites, Path(frequency_file))

    return satellites

fetch_tles

fetch_tles(
    output_path: Path, source: str = "celestrak"
) -> Path

Downloads TLEs from a remote source and saves them to output_path.

Source code in src/sopp/io/tle.py

def fetch_tles(output_path: Path, source: str = "celestrak") -> Path:
    """
    Downloads TLEs from a remote source and saves them to output_path.
    """
    if source == "celestrak":
        content = _fetch_celestrak()
    elif source == "spacetrack":
        content = _fetch_spacetrack()
    else:
        raise ValueError(f"Unknown TLE source: {source}")

    output_path.parent.mkdir(parents=True, exist_ok=True)

    with open(output_path, "wb") as f:
        f.write(content)

    return output_path

OMM Loading

parse_omm_file

parse_omm_file(
    omm_file: Path | str, file_format: str
) -> list[Satellite]

Loads satellites from an OMM file in csv, json, or xml format.

Source code in src/sopp/io/omm.py

def parse_omm_file(omm_file: Path | str, file_format: str) -> list[Satellite]:
    """
    Loads satellites from an OMM file in csv, json, or xml format.
    """
    path = Path(omm_file)

    if file_format == "csv":
        with open(path, newline="") as f:
            return [_to_satellite(fields) for fields in sgp4_omm.parse_csv(f)]
    if file_format == "json":
        with open(path) as f:
            records = json.load(f)
        return [_to_satellite(fields) for fields in records]
    if file_format == "xml":
        with open(path) as f:
            return [_to_satellite(fields) for fields in sgp4_omm.parse_xml(f)]

    raise ValueError(f"Unknown OMM file format: {file_format}")

Frequency Data

GetFrequencyDataFromCsv

GetFrequencyDataFromCsv(filepath: Path)

Reads satellite frequency data from a CSV file.

Returns a dict mapping NORAD catalog IDs to lists of FrequencyRange. The CSV must have columns: ID, Name, Frequency [MHz], Bandwidth [kHz]/Baud, Status, Description, Source.

Source code in src/sopp/io/frequency.py

def __init__(self, filepath: Path):
    self._filepath = filepath