Metadata-Version: 2.1
Name: satsim
Version: 0.25.0
Summary: Satellite observation and scene simulator.
Home-page: https://github.com/ssc-ai/satsim
Author: Alex Cabello
Author-email: alexander.cabello@algoritics.com
License: UNKNOWN
Keywords: satsim
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/markdown
License-File: AUTHORS.md
Requires-Dist: Click (>=8.1)
Requires-Dist: Cython (>=0.29.0)
Requires-Dist: scikit-image (>=0.19.3)
Requires-Dist: Pillow (>=9.0)
Requires-Dist: numpy (>=1.21.0)
Requires-Dist: opensimplex (>=0.4.0)
Requires-Dist: PyYAML (>=6.0)
Requires-Dist: matplotlib (>=3.7.0)
Requires-Dist: astropy (<6,>=5.2.1)
Requires-Dist: apng (>=0.3.4)
Requires-Dist: scipy (>=1.10)
Requires-Dist: tensorflow (>=2.4)
Requires-Dist: skyfield (>=1.45)
Requires-Dist: sgp4 (>=2.21)
Requires-Dist: poppy (>=1.0.3)
Requires-Dist: diskcache (>=5.0.3)
Requires-Dist: pydash (>=4.9.0)
Requires-Dist: asdf (<3,>=2.14.3)
Requires-Dist: pygc (>=1.3.0)
Requires-Dist: numba (>=0.56.0)
Requires-Dist: pooch (>=1.6.0)
Requires-Dist: czmlpy (>=0.9.0)
Requires-Dist: tifffile (>=2023.4.12)
Requires-Dist: imagecodecs (>=2023.3.16)

# SatSim

[![Unit Tests](https://github.com/ssc-ai/satsim/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/ssc-ai/satsim/actions/workflows/unit-tests.yml)

**SatSim source code was developed under contract with AFRL/RDSM, and is approved for public release under Public Affairs release approval #AFRL-2022-1116.**

SatSim is a GPU-accelerated synthetic data generation engine for space domain awareness scenes. It renders electro-optical imagery of resident space objects (RSOs), produces labels and metadata for detection workflows, and includes an analytical radar path for measurement simulation. Configurations are plain JSON or YAML, so a single scenario can be fixed, procedurally sampled, or generated from Python functions.

![Real and SatSim-generated rate-track imagery](docs/images/satsim-real-vs-synthetic.jpg)
_Real Raven rate-track imagery and a SatSim-rendered counterpart, adapted from the public SatSim SPIE Defense + Commercial Sensing paper._


![PANDORA wide-field synthetic imagery](docs/images/satsim-pandora-wide-field.jpg)
_Synthetic PANDORA wide-field imagery generated for sensor modeling, adapted from the same paper._


## What SatSim Does

- Renders stars, RSOs, point-spread functions, sky background, dark current, shot noise, read noise, pixel response, bias, and analog-to-digital conversion.
- Supports fast 2D image-plane targets and 3D astrometric geometry using TLE/SGP4, two-body state vectors, ephemerides, great-circle tracks, and angles-only observations.
- Models Gaussian and POPPY physical-optics PSFs, optional turbulence, tiled rendering for large images, FITS compression, segmentation masks, and ground-truth planes.
- Adds environmental effects including skyglow, moonlight, twilight, daytime sky brightness, and procedural cloud attenuation and glow.
- Generates nominal, RPO, breakup, collision, Monte Carlo, and sensor-variation scenarios through `$sample`, `$generator`, `$function`, `$pipeline`, `$compound`, `$ref`, and `$import`.
- Writes SatNet-style annotations, FITS image frames, annotated JPEGs, APNG movies, CZML visualizations, analytical EO observations, and radar observations.
- Can augment TensorFlow datasets by injecting synthetic targets into real imagery during training.

## Quick Start

Install the released package:

```bash
pip3 install satsim
```

Run an EO image simulation from a JSON or `.yml` configuration:

```bash
satsim --debug INFO run --device 0 --mode eager --output_dir output/ input/config.json
```

Use SatSim from Python:

```python
from satsim import gen_multi, load_json

ssp = load_json("input/config.json")
ssp["sim"]["samples"] = 50
ssp["geometry"]["obs"]["list"][0]["mv"] = 17.5

gen_multi(ssp, eager=True, output_dir="output/")
```

The CLI writes each run to a timestamped output directory. Typical EO products include `ImageFiles/*.fits`, `Annotations/*.json`, `AnnotatedImages/*.jpg`, optional segmentation TIFFs, optional ground-truth TIFF stacks, `movie.png`, `satsim.czml`, and transformed `config_pass_*.json` files.

## Documentation

- [Installation](docs/installation.md)
- [Usage](docs/usage.md)
- [JSON schema](schema/v1/README.md)
- [Developer setup](CONTRIBUTING.md#getting-started-for-developers)
- [Release history](HISTORY.md)


History
=======

0.25.0
---------------------

* **BEHAVIORAL CHANGE:** Add sub-pixel bilinear point rendering for stars and targets, enabled by default. Rendered images differ slightly from v0.24.0; set `sim.point_rendering` to `floor` for legacy rendering.
* Add detector-space ePSF lookup-table renderer. Set `sim.mode` to `epsf` and configure `sim.epsf.*`.
* Add native ePSF trailed star rendering for `star_render_mode: streak` to speed dense rate-track star fields.
* Add tiered ePSF crop rendering for dim stars, defaulting to auto thresholds.
* Add ePSF transform renderer performance options: budget-scaled scatter batches, `point_rendering: phase_nearest`, and detector-pixel auto temporal sampling with bin-centered exposure samples.
* Add block-sum downsampling and normalization options for radial image models and PSF generation.


0.24.0
---------------------

* Add sky background models for artificial skyglow, moonlight, twilight, and daytime. Configure `background.*`.
* Add modular cloud layers with presets, optical depth, glow, source brightening, and wind motion. Configure `clouds`.
* Add deformable radial image models. Use `deformable_radial_poly2d` and `deformable_radial_falloff2d`.
* Add apparent RA/Dec FITS WCS metadata with GAPPT headers.


0.23.1
---------------------

* Change radar range rate to instantaneous measurement. See `radar.monostatic.range_rate`.


0.23.0
---------------------

* Add FITS compression support. Set `sim.fits_compression`.
* Add seed support for deterministic sampling in random functions. Use `seed` on `$sample`.
* Add simplex gradient noise and lognormal_mu_sigma random. Use `$sample: random.simplex` or `random.lognormal_mu_sigma`, with optional `center`.
* Add GCVS5 star variability catalog support. Configure `geometry.stars.gcvs5.*`.
* Add RA/Dec tracking support. Set `geometry.site.track.mode` to `radec`.
* Add compound operator normalization/evaluation and schema updates. Use `$compound` with `$operator`.
* Enhance radial_cos2d with falloff parameters. Set `falloff_height`, `falloff_width`, or `falloff_xy`.
* Implement PSF `none` mode to bypass convolution. Set `fpa.psf.mode: none`.
* Refactor FITS header generation to incorporate focal plane roll and fix CD/CRPIX.
* Add support for additional noise term in FPA and evaluation tests. Configure `fpa.noise.misc`.


0.22.2
---------------------

* Rename tracking pointing toggle from `light_transit_correction` to `track_apparent` in config and APIs.
* Add graceful fallback to geometric LOS when apparent LOS computation fails.


0.22.1
---------------------

* Add light transit correction toggle for pointing. Set `light_transit_correction` in `track`. Default is `true`.


0.22.0
---------------------

* Add analytical RADAR observations.
* Batched SGP4 propagation with FOV pre-filtering to speed large catalogs.
* Add profiling for image generation pipeline and object timing logs. Controlled by `enable_profiler`.


0.21.2
---------------------

* Fix stellar aberration being applied to target incorrectly.


0.21.1
---------------------

* Add field of view pre-filter to cull objects for performance. Controlled by `enable_fov_filter` and optional `fov_filter_radius` (degrees).


0.21.0
---------------------

* Add space-based observer.


0.20.4
---------------------

* Update analytical observation for specified observation frames. `analytical_obs_frame` can be `barycentric`, `geocentric`, or `observer`.


0.20.3
---------------------

* Fix star stellar aberration.
* Add simulation configuration options for deflection, light transit, and stellar aberration.


0.20.2
---------------------

* Refactor keras_tensor import logic to support multiple TensorFlow/Keras versions.
* Refactor great circle into separate module.
* Reorganize CLI tests to run first to prevent TensorFlow configuration errors.


0.20.1
---------------------

* Refactor two-body propagation to remove `poliastro` dependency.
* Add object identification fields to analytical observations.


0.20.0
---------------------

* Add analytical observations with noise modeling capability.
* Fix electronic noise casting issue in add_read_noise function.


0.19.4
---------------------

* Fix observer altitude units.
* Fix apparent position of stars to include stellar aberration.


0.19.3
---------------------

* Add object ID to FITS and annotations.


0.19.2
---------------------

* Add `rate-sidereal` track mode. This mode takes n - 1 rate track frames and the last frame in sidereal tracking mode.


0.19.1
---------------------

* Add `TRKMODE` to fits header.


0.19.0
---------------------

* Add lambertian sphere brightness model for objects. Set object key `model` `mode` to `lambertian_sphere` and set `albedo` and `size` (meters) parameters. For 2D simulations, `distance` (km) and `phase_angle` (degrees) parameters must also be specified.


0.18.0
---------------------

* Add turbulent atmosphere to POPPY PSF generation. Set with psf option `turbulent_atmosphere` and sim option `psf_sample_frequency`.
* Add star and object segmentation annotation. Set sim option `save_segmentation` to `true` and `star_annotation_threshold` to limit stars annotated.


0.17.1
---------------------

* Copy useful TensorFlow Addon (TFA) functions into `tfa` as the TFA project is no longer maintained.
* Copy tests.


0.17.0
---------------------

* Add JSON schema definitions. See `schema/v1/Document.json` for root schema file.
* Add observation object type.
* Add support for cropped sensors.
* Add altitude to site object. Set site `alt` parameter in km. Default is 0.


0.16.0
---------------------

* Add option to annotate stars. Set sim option `star_annotation_threshold` to the minimum star brightness magnitude or `false` to disable. Disabled by default.
* Add option to show annotated stars in annotated images. Set sim option `show_star_boxes` to `true` to enable.


0.15.1
---------------------

* Remove clipping of negative values in ground truth files by default.
* Fix missing dependencies for ground truth file generation.


0.15.0
---------------------

* Add support to save ground truth image data to the Annotations directory. Set sim option `save_ground_truth` to `true`.
* Add support for running on CPU with no GPU acceleration.
* Add CZML options for sensor visualization and object billboard image.


0.14.0
---------------------

* Add vector math library.
* Add CZML output for sensor visualization.
* Fix objects not updating properly when image renderer is off.


0.13.1
---------------------

* Add argument to set folder name in `gen_multi`.
* Add environment variable, `SATSIM_SKYFIELD_LOAD_DIR`, to specify location of Skyfield ephemeris files.
* Fix incorrect CZML output when image renderer is off.


0.13.0
---------------------

* Add ephemeris objects that are propagated with the Lagrange interpolator.
* Add Cesium CZML output. Set sim option `save_czml` to `false` to disable.
* Add CSV text file star catalog loader. This feature is useful for small catalogs such as Hipparcos and simulating wide FOV sensors.
* Add multiplier and clipping for radial cosine.
* Add option to skip image rendering. Set sim option `mode` to `none` to bypass image rendering.
* Update interfaces for newest version of Skyfield, Poliastro, POPPY, and AstroPy.
* Fix star renderer issue removing stars in field of view for non-square arrays.


0.12.0
---------------------

* Add augmentation of SatNet `tf.data.Dataset`. This feature allows injecting synthetic targets into real data during training.
* Add FFT convolution to `add_patch` sprite render and `scatter_shift` image augmenter for speed improvement.
* Add cache last PSF FFT to `fftconv2p` for speed improvement for static PSFs.
* Add two-body state vector as a trackable target.
* Add moon and sun model and misc methods to calculate phase angle and target brightness.


0.11.0
---------------------

* Add support to render star motion with FFT. Set sim option `star_render_mode` to `fft`.
* Add option to sample photon noise multiple times. Set sim option `num_shot_noise_samples` to integer number.
* Add support to render a satellite as a sprite. Set `model` option in obs.
* Add support to load and augment sprite model with `$pipeline` operator.
* Add cropped POPPY PSF generation.
* Fix GreatCircle propagator tracking offset.
* Fix runtime exception when site and track_mode are not defined.
* Add TensorFlow 2.6 and update TensorFlow 2.2 and 2.4 Docker build file.


0.10.0
---------------------

* Add support for piecewise rendering. Set sim option `render_size` to enable. For example, [256, 256].
* Add `fixed` tracking mode with mount azimuth and elevation.
* Add great circle propagator for targets.
* Add in-memory image generation. See generator function `image_generator`.
* Fix missing stars when FOV crosses zero degree RA.
* Add curved targets using bezier curve raster. Enabled by default. Set sim option `num_target_samples` to 2 to enable linear raster.
* Add LRU cache to star catalog reader.
* Add option to turn off SNR calculation. Set sim option `calculate_snr` to false will render targets and stars together.
* Handle unstable SGP4 TLEs.
* Add TensorFlow 2.4 Docker build file.
* Add debug output for pristine images of targets and stars.


0.9.1
---------------------

* Calculate POPPY input wavefront resolution to avoid PSF aliasing.
* Add support for additional FITS image data types (`int16`, `uint16`, `int32`, `uint32`, `float32`).
* Add batch processing to `transform_and_add_counts` to support batch processing of stars.
* Add `auto` option to calculate temporal oversample factor based on star velocities.
* Add option to turn off serializing config data to pickle file (`save_pickle`).
* Add option to turn off png movie output (`save_movie`).
* Add `crop_and_resize` and `flip` image augmentation.
* Set pixels with values beyond the pixel data type's capacity to the maximum value for that data type.
* Add `lognormal` function to generate a distribution with a true target mean.
* Fix issue with sidereal track.
* Fix issue with fragment velocity not being randomly sampled.


0.9.0
---------------------

* Add Physical Optics Propagation in Python (POPPY) PSF generation.
* Add PSF augmentation with `$pipeline` replacement key.
* Add `$function` and `$compound` replacement key.
* Add ability to generate stray light from a `$function` replacement key.
* Add built-in 2D polynomial image generator for stray light, `polygrid2d`.
* Add built-in cosine fourth image generator for irradiance falloff, `radial_cos2d`.
* Add built-in sine wave image generator for fix pattern noise, `sin2d`.
* Add built-in image generator from AstroPy model, `astropy_model2d`.
* Add built-in image augmentation, `scatter_shift` and `scatter_shift_polar`.
* Add `$cache` replacement key (caching works for PSF and `$function`).


0.8.3
---------------------

* Fix new Skyfield incompatibility.


0.8.2
---------------------

* Prefix replacement keys with `$` in SatSim configuration file.
* Add option to scale collision fragments by cosine of the exit angle.


0.8.1
---------------------

* Add astrometric metadata into FITS header
* Refactor WCS library
* Add option to flip images about x or y axis
* Add option to refresh stars for each frame
* Add RPO from TLE generator


0.8.0
---------------------

* Add two body propagator
* Add object `create`, `delete`, and `update` events
* Add collision generator
* Add breakup generator
* Add `ref` keyword to configuration
* Add `key` keyword to `import` configuration
* Refactor astrometric library


0.7.2
---------------------

* Add option to specify star and obs velocity in polar coordinates


0.7.1
---------------------

* Add option to turn off shot noise: `sim.enable_shot_noise: true`
* Add option to turn off annotation boxes in image: `sim.show_obs_boxes: true`
* Add option to specify velocity in arcseconds: `sim.velocity_units: arcsec`
* Fix PNG output threading issue


0.7.0
---------------------

* Add function pipelines to support variable target brightness


0.6.1
---------------------

* Fix built-in generators not included in distribution
* Add dockerfile


0.6.0
---------------------

* Add configuration import.
* Add configuration generator functions.
* Add built-in generator for breakups.
* Add built-in generator for CSOs.
* Add built-in generator for loading TLE files.


0.5.0
---------------------

* Runtime optimization.
* Add parallel processing and multi-gpu utilization.
* Add option to limit gpu memory usage.


0.4.0
---------------------

* Add signal to noise calculation for target pixels.


0.3.0
---------------------

* Add support for two line element set SGP4 satellite propagator.
* Add support for rate and sidereal track from topocentric site.


0.2.0
---------------------

* Add support for SSTR7 star catalog.


0.1.1
---------------------

* Add target position to annotation file.
* Updates to run GitLab CI.


0.1.0
---------------------

* First release.


