Open source planetary image processing and terrain reconstruction environment, built on NASA JPL's VICAR.
TIG works with the instrument-specific formats planetary missions produce, converting between them and into interchange formats while retaining the acquisition metadata that travels in the image label. It processes raw instrument image products into the visual and geometric products that surface mission operations run on: disparity maps, XYZ point clouds, textured terrain meshes, slope, roughness and reachability rasters, and map-projected mosaics that can cover a full 360 degrees in azimuth. Camera-model and coordinate-frame tools bring products from different instruments into a common frame, so views from several cameras can be combined; radiometric calibration and image co-registration are available where the mission's calibration data and tiepoint workflows are supplied. Every tool is an ordinary command, so terrain generation can be automated as ordinary scripts or workflow tasks.
It packages VICAR — NASA JPL's general-purpose image processing system, used on
planetary missions since the 1960s — as a container image with ~546 commands
(74 of them the mission-specific mars* terrain programs), plus
tig, a CLI that runs any of them from your own shell as
if they were installed locally. Products come out in interchange formats
(Wavefront OBJ, glTF/GLB, PNG/JPEG/TIFF, map-projected VICAR) that downstream
AMMOS visualization tools such as MMGIS, ASTTRO and Astria consume; TIG itself
does not talk to those services and ships no adapter for them.
Scope note: processing starts at instrument image products (EDR/FDR-level VICAR images). There is no telemetry ingest or depacketization in this repository — "raw" here means uncalibrated image products, not raw downlink.
Terrain meshes, point clouds and slope/roughness maps from in-situ imagery:
| Stage | Tools |
|---|---|
| Stereo correlation | marscorr, marscor3, marsecorr, marsjplstereo |
| Point clouds | marsxyz, marsxyzmerge, marsxyzsurf, marsrfilt |
| Meshes | marsmesh, marsrefmesh (Wavefront OBJ + OpenInventor), obj2gltf (glTF/GLB) |
| Surface characteristics | marsslope, marsrough, marsirough, marsuvw (surface normals), marsgreach (goodness/reachability) |
| Range and depth | marsrange, marsdepth, marsinvrange |
The mesh generation demo runs the stereo →
disparity → XYZ → mesh path end to end on Mars 2020 NavCam pairs, and the
Airflow example runs the same path as
scheduled tasks. The surface characteristics demo
takes that XYZ and derives slope, roughness, surface normals and placement
goodness. marsgreach, which collapses arm reachability into the goodness
raster used for traversability assessment, is in the image but its 6-band
reachability input is produced by a mission program that is not, so it stays
an available program rather than a demonstrated workflow.
Map-projected, large-area products are built by mosaicking overlapping frames.
marsmap assembles a mosaic in a cylindrical, polar, vertical or (experimental)
sinusoidal projection and handles azimuth wrap-around, which is how a panorama
covering up to 360 degrees is produced; marsmos assembles frames under a
synthetic wide-field camera model; marsortho produces orthographic mosaics and
DEMs from XYZ data; marsremos and marsunmosaic rebuild and invert mosaics.
map3, maptran and mapcoord from the general VICAR toolset perform
cartographic map projection and reprojection.
Co-registration is a tiepoint-and-pointing workflow rather than a single
command: marsautotie / marsautotie2 / marstie generate tiepoints,
marsnav, marsnav2 (bundle adjustment) and marsautoloco solve for corrected
pointing, and marsfidfinder locates fiducials. Once images are registered,
change comparison over time is composed from the general image-processing tools
— there is no change-detection program in the image.
Both workflows are demonstrated: see the panorama mosaic
and co-registration demos. Note also
that the mars* mosaicking programs are built around in-situ camera geometry
(spherical coordinates about a landing site); orbital imagery is handled by the
general cartographic programs above.
Camera models in CAHV/CAHVOR/CAHVORE (marscahv, marsmake_cm, marsget_cm,
marscheckcm) and frame transforms (marscoordtrans, marsproj,
marsrelabel) bring products from different instruments and coordinate frames
into a common frame, which is what allows high-resolution surface views and
broader context imagery to be combined into one product. Radiometric
calibration (marsrad) plus brightness matching and colour handling
(marsbrt, marsrcorr, marsbias, marscolor, marsdebayer) normalize
inputs beforehand; marsrad reads flat fields from MARS_CONFIG_PATH, so it
needs mission calibration data that the base image does not bundle — see
Calibration Data for mounting VISOR data
or using the :visor-<mission> image variants. marsrad is exercised as the
rad_left / rad_right tasks of the Airflow
example.
VICAR's label system carries acquisition metadata through processing, so
intermediate and final products keep their provenance (label, clabel and
marsrelabel inspect and update it). vicario converts VICAR images to
PNG/JPEG/TIFF (see the reference); vtiff handles
TIFF, visis2 / visisx / isislab handle ISIS, and obj2gltf / obj2plane
/ marstile convert mesh and tiled products. There is no PDS4 reader or writer
in the image; metadata retention here means VICAR-label retention.
~546 commands for enhancement (stretch, filter), geometry (geom, rotate,
size), analysis (hist, list, label) and arithmetic (f2).
Every tool is an ordinary command, so pipelines are ordinary scripts — the
demo script is one, and the
Airflow + Kubernetes example runs
radiometric correction, correlation, XYZ and meshing as event-driven DAG tasks.
tig keeps a container warm between invocations, so per-command overhead is
tens of milliseconds rather than a container start.
So the scope is unambiguous:
- No telemetry ingest or depacketization; inputs are instrument image products.
- No MMGIS, ASTTRO or Astria adapter, exporter or tiling recipe. TIG writes interchange formats those tools can consume; connecting them is up to you.
- No PDS4 reader or writer.
- No change-detection program; change monitoring is a composed workflow.
- No calibration data in the base image (the
:visor-<mission>variants bundle it per mission). - No worked example for
marsgreachreachability, whose input-producing program is not in the image — the program is present, the demo is not. Automated checks cover the CLI, format conversion, and the presence of the MARS commands; the end-to-end product paths that are demonstrated are the mesh, panorama mosaic, surface characteristics and co-registration demos, and the Airflow example.
pip install tig-cli
# Any VICAR tool, running in the container against your local files
tig gen test.vic 512 512
tig vicario test.vic test.pngPrefer the tools unqualified? Generate a shim directory once:
tig --shim
export PATH="$HOME/.local/share/tig/shims:$PATH"
marsmesh inp=pointcloud.xyz out=terrain.obj in_skin=texture.img -adaptiveGenerate a mesh from a Mars 2020 NavCam stereo pair:
export MARS_CONFIG_PATH=/path/to/mars_calibration_m20
./demo-mesh-generation-with-xyz.sh \
--stereo-left /path/to/NLM_*_FDR_*.VIC \
--stereo-right /path/to/NRM_*_FDR_*.VIC
ls workspace/ # terrain.obj, terrain.mtl, texture.png, pointcloud.xyz
meshlab workspace/terrain.objSee QUICKSTART.md for the fuller tour.
The command-line client. Runs any VICAR tool in the container, translating host
paths, reusing one warm container, mounting calibration data, and forwarding X11
so GUI tools such as xvd display on your desktop.
📁 tig-cli/ · 📦 pip install tig-cli · 📖 README
The container image: VICAR built from the
NASA-AMMOS/VICAR open-source releases,
plus the Java vicario converter. Published as
ghcr.io/nasa-ammos/tig/terrain-intelligence-generator:opensource.
📁 terrain-intelligence-generator/ · 📖 README
VICAR Institutional Stereo Observation Repository — camera calibration files for
M20, MSL, MER and other missions. Not bundled in the base image; mount it at
runtime, or use a :visor-<mission> image variant that bundles it.
📖 Downloading VISOR Data · Calibration Data
📁 demo-mesh-generation-with-xyz.sh · 📖 Mesh Generation · Command Reference
📁 demo-surface-characteristics.sh · 📖 Surface Characteristics
- Getting Started - Installation and setup
- Quick Start - Common workflows end to end
- Mesh Generation Demo - Step-by-step mesh creation
- Panorama Mosaic Demo - 360-degree in-situ NavCam panorama
- Surface Characteristics Demo - Slope, roughness, normals and goodness from an XYZ cloud
- Co-registration Demo - Tiepoints, pointing correction, and composing change monitoring
- Command Reference - Tour of the VICAR toolset
- Vicario Reference - Image format conversion
- Calibration Data - Mounting MARS/VISOR files
- Architecture - How the pieces fit together
- Airflow + Kubernetes Pipeline - Event-driven terrain mesh generation example
| Tool | Purpose | Input | Output |
|---|---|---|---|
marscorr |
Initial stereo correlation | Stereo pair | Disparity map |
marscor3 |
Disparity refinement | Disparity + images | Refined disparity |
marsxyz |
3D point generation | Disparity + images | XYZ point cloud |
marsrfilt |
Rover hardware filtering | XYZ | Filtered XYZ |
marsmesh |
Surface triangulation | XYZ + texture | 3D mesh (OBJ) |
marsslope, marsrough |
Surface characteristics | XYZ | Slope / roughness maps |
marsmap |
Projected mosaicking (cylindrical / polar / vertical) | Images + geometry | Map-projected mosaic |
marsmos |
Camera-model mosaicking | Images + geometry | Wide-field mosaic |
marsortho |
Orthographic mosaic / DEM | XYZ + skin | Ortho image, DEM |
| Tool | Purpose | Category |
|---|---|---|
vicario |
VICAR ↔ PNG/JPEG/TIFF | Format conversion |
gen |
Generate test images | Development |
stretch |
Contrast adjustment | Enhancement |
filter |
Spatial filtering | Enhancement |
geom |
Geometric transformation | Geometric |
hist |
Histogram analysis | Analysis |
label |
VICAR metadata viewer | Metadata |
f2 |
Image arithmetic | Mathematical |
Representative examples out of ~546 commands; tig bash -c 'ls /usr/local/bin'
lists them all.
VICAR programs return 1 on a successful run, and 1 again when TAE rejects the
invocation, so the raw code cannot tell the two apart. TIG's command wrappers
translate them, which means set -e and && chains work as written:
| Code | Meaning |
|---|---|
| 0 | The program ran |
| 1 | TAE rejected the invocation (missing parameter, unknown keyword) |
| 255 | The program called abend() — e.g. a missing or unreadable input |
| >128 | Killed by a signal |
The translation happens in the wrappers under /usr/local/bin, so it applies
to commands run through tig-cli or docker exec. Calling a program by its
full path ($V2TOP/p2/lib/x86-64-linx/gen) bypasses it and returns VICAR's
raw code.
- Docker or Podman
- Python 3.9+
- 8GB RAM minimum (16GB recommended for high-res meshes)
- Linux, macOS (including Apple Silicon, via emulation), or Windows with WSL2
tig/
├── demo-mesh-generation-with-xyz.sh # Mesh demo (stereo pair or pre-computed XYZ)
├── demo-surface-characteristics.sh # Slope, roughness, normals and goodness from XYZ
├── find-calibration.sh # Calibration helper
├── tig-cli/ # The tig command-line client (PyPI: tig-cli)
├── terrain-intelligence-generator/ # Container image: Dockerfile, vicario, build/test
├── QUICKSTART.md # Common workflows end to end
├── examples/
│ └── airflow-k8s-pipeline/ # Airflow + Kubernetes terrain pipeline example
└── docs/
├── demos/ # Demo guides
├── architecture/ # System design
└── reference/ # Tool references
Contributions welcome! This project builds on:
- VICAR: JPL MIPL's general-purpose image processing system
- Docker: Containerized VICAR execution environment
- VISOR: Open source calibration repository for multiple missions
Apache License 2.0 (see LICENSE file)
VICAR (Video Image Communication and Retrieval) is a general-purpose image processing system developed by NASA JPL's Multimission Image Processing Laboratory (MIPL). Used for processing images from Mars rovers, lunar missions, and deep space probes since the 1960s, it covers enhancement, filtering, geometric transformation, radiometric calibration, stereo reconstruction, and format conversion. TIG makes it accessible through modern containerization.
- NASA JPL Multimission Image Processing Laboratory (MIPL)
- VICAR development team
- Open source planetary science community