# resolved

Renders what a spacecraft camera sees: Earth, Moon, Sun and a target
spacecraft loaded from a mesh. The inputs are an epoch, the observer and target
states and attitudes, and a camera model. Images are radiometric: the renderer
works in radiance and converts to electrons and then DN through the camera's
optics and detector, so an image should match what a real camera with the same
parameters records.

It is built for closed-loop simulation, where each step renders one frame and
latency is the number that matters. The target is 1–2 MP RGB in under 100 ms
end to end on a mid-range GPU (the reference is an RTX 3060). Lighting fidelity
and camera fidelity are selected separately, and each tier is benchmarked, so
a run can trade fidelity for speed knowing what each step costs.

Rendering goes through wgpu. On a machine without a GPU, the same shaders run
on the CPU through Mesa's lavapipe (`vulkan-swrast` on Arch,
`mesa-vulkan-drivers` on Debian and Ubuntu).

## Status

Early development. Nothing renders yet. The work is tracked as Gitea
milestones, each split into one issue per change:

| Milestone | Scope |
|---|---|
| M1 | Scene API, headless wgpu, analytic Earth/Moon/Sun, glTF and STL targets, Lambert shading with eclipse, pinhole camera, radiance to DN, CLI, benchmark baseline |
| M2 | Self-shadowing, Earthshine and Moonshine, Earth and Moon albedo maps, Sun limb darkening |
| M3 | Lens distortion, PSF, detector noise, saturation and blooming, stars |
| M4 | BRDF and spectral materials, atmospheric scattering, clouds, lunar terrain |
| M5 | Portable ray tracing, path tracing, label outputs for ML |
| M6 | Validation against lunar, Earth and Mitsuba references; motion blur, rolling shutter, stray light; multi-band and 4k |

## Conventions

- SI units throughout: meters, seconds, radians, watts.
- Scene state is f64 in an inertial frame (GCRF). The GPU only sees f32
  coordinates relative to the camera.

## Layout

- `crates/resolved`: the library.
- `crates/resolved-cli`: the `resolved` command, for rendering without writing
  a host program.
- `docs/optics.md`: the optics and radiometry the renderer models, explained
  for readers without an optics background.

## Development

Point git at the committed hooks once per clone:

```sh
git config core.hooksPath hooks
```

`pre-commit` runs formatting, clippy and the library unit tests; `pre-push`
runs the full test suite, including doctests, and the documentation build.

The integration tests render on both a hardware GPU and lavapipe, so running
them needs a Vulkan driver for the GPU and lavapipe installed. Set
`WGPU_BACKEND`, `WGPU_ADAPTER_NAME` and the other standard wgpu environment
variables to steer adapter discovery.

To see what the GPU tests render, set `RESOLVED_TEST_IMAGES=1`. Each test then
writes a PNG per device to `target/tmp/test-images/`, scaled so a white
surface facing the Sun is full white:

```sh
RESOLVED_TEST_IMAGES=1 cargo test --test bodies --test mesh
```

## License

MIT