diff --git a/QUICKSTART.md b/QUICKSTART.md index 6e13241..606a2a9 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,4 +1,6 @@ -# Quick Start - Running Demos with Your Data +# Quick Start - TIG Image Processing & Terrain Reconstruction + +TIG provides ~550 VICAR image processing commands. This guide focuses on the flagship terrain reconstruction workflow, but you can use TIG for general image processing, format conversion, enhancement, and analysis. ## Option 1: Original Demo (Temporary Container) @@ -40,7 +42,7 @@ docker stop tig-mesh-demo && docker rm tig-mesh-demo ## Option 2: Native Toolkit Demo (Persistent Container) -Native-looking commands for interactive development. Container stays running. +Native-looking commands for interactive development and full VICAR access. Container stays running, providing access to all ~550 VICAR commands beyond just mesh generation. ### One-time Setup @@ -229,13 +231,28 @@ cd /path/to/tig cd vicar-native-toolkit direnv allow -# 2. Work interactively +# 2. Work interactively with VICAR commands cd workspace + +# Generate test images gen out=test.img nl=100 ns=100 + +# View image metadata label test.img + +# Image processing examples +stretch inp=test.img out=stretched.img +filter inp=test.img out=filtered.img +geom inp=test.img out=rotated.img rotate=45 + +# Terrain processing marsmesh inp=pointcloud.xyz out=custom.obj +# Convert VICAR to standard formats +vicario inp=test.img out=test.png + # 3. Container stays running for next session +# Access all ~550 VICAR commands the same way ``` --- @@ -266,7 +283,14 @@ ls -lh terrain.obj ## Next Steps +### Terrain Reconstruction - Read full documentation: `docs/demos/mesh-generation.md` -- Explore VICAR commands: `toolkit-shell` then `ls /usr/local/bin` - Customize processing: Edit marsmesh/marsxyz parameters in demo scripts - Integrate into pipelines: Use as reference for your own scripts + +### General Image Processing +- Explore VICAR commands: `toolkit-shell` then `ls /usr/local/bin` (see ~550 commands) +- Image enhancement: Try `stretch`, `filter`, `hist` commands +- Format conversion: Use `vicario` for VICAR ↔ PNG/JPEG/TIFF +- Geometric operations: Experiment with `geom`, `rotate`, `size` +- Learn VICAR: See vicar-native-toolkit documentation for command usage diff --git a/README.md b/README.md index c45fa84..f191b90 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,35 @@ # Terrain Intelligence Generator (TIG) -Open source stereo terrain reconstruction pipeline using NASA's VICAR image processing system. +Open source VICAR image processing environment for planetary science and stereo terrain reconstruction. ## Overview -TIG provides a Docker-based execution environment for generating 3D terrain meshes from stereo camera images. Built on VICAR (Video Image Communication and Retrieval), NASA JPL's image processing system used across planetary missions. The vicar-native-toolkit provides a helper/wrapper script to interact with the TIG container. +TIG provides a containerized VICAR execution environment with ~550 image processing commands spanning enhancement, filtering, geometric transformation, format conversion, and multi-mission calibration. Built on VICAR (Video Image Communication and Retrieval), NASA JPL's general-purpose image processing system used across planetary missions since the 1960s. While TIG's flagship capability is stereo terrain reconstruction, it provides comprehensive image processing tools for planetary science workflows. The vicar-native-toolkit provides native-like CLI access to all VICAR commands. ## Features +### Terrain Reconstruction (Flagship Capability) - **Stereo Correlation**: Generate disparity maps from stereo image pairs (marscorr, marscor3) - **3D Point Clouds**: Convert disparity to XYZ coordinates (marsxyz) - **Mesh Generation**: Create textured 3D surface meshes in OBJ / OpenInventor formats (marsmesh) -- **Image Conversion**: Convert VICAR images to PNG / JPEG / TIFF (vicario) -- **VISOR Calibration**: Integrates with VISOR (VICAR Institutional Stereo Observation Repository) containing M20 and many other open source mission calibrations -- **Open Source**: Community-accessible VICAR-based terrain processing +- **Terrain Analysis**: Orthoprojection, mosaicking, localization (marsmap, marsmos, marsautoloco) + +### Image Processing (~550 Commands) +- **Enhancement**: Contrast stretching, filtering, dynamic range adjustment (stretch, filter) +- **Geometric Operations**: Transformations, rotation, resizing, registration (geom, rotate, size) +- **Format Conversion**: VICAR to/from PNG, JPEG, TIFF (vicario) +- **Analysis**: Histograms, statistics, pixel inspection (hist, list, label) +- **Mathematical Operations**: Image arithmetic, band math (f2) + +### Multi-Mission Support +- **VISOR Integration**: 1,461 calibration files for M20, MSL, MER, Phoenix missions +- **Camera Models**: CAHVORE format support with automatic calibration lookup +- **Sample Data**: 249 sample files including stereo pairs and pre-computed XYZ + +### Development Tools +- **Native Toolkit**: ~550 command wrappers for native-like CLI usage +- **Fast Execution**: Long-running container with minimal latency (~50-100ms) +- **Cross-Platform**: Linux, macOS (including Apple Silicon via emulation) ## Quick Start @@ -68,21 +84,27 @@ meshlab workspace/terrain.obj ### VICAR Native Toolkit -A helper/wrapper script that provides native-like CLI usage for VICAR commands inside the TIG Docker execution environment. Features: +A wrapper system that provides native-like CLI usage for all ~550 VICAR commands inside the TIG Docker execution environment. Features: - ✨ **One-command setup** via `make bootstrap` - πŸš€ **Fast activation** (~1 second, symlink-based wrappers) -- πŸ”§ **Auto-discovers** ~550 VICAR commands +- πŸ”§ **Auto-discovers** all ~550 VICAR commands - 🐳 **Custom image support** via `IMAGE=` variable - πŸ“Š **VISOR calibration mounting** for terrain processing +- 🌐 **Full VICAR access** - not just terrain tools, but all image processing commands πŸ“ `vicar-native-toolkit/` πŸ“– [Toolkit README](vicar-native-toolkit/README.md) | [Quick Reference](vicar-native-toolkit/docs/QUICKREF.md) ### Terrain Intelligence Generator -An optimized VICAR execution environment, packaged as a Docker image with the VICAR toolset and VISOR calibration integration for stereo processing and mesh generation. +A containerized VICAR execution environment, packaged as a Docker image with the complete VICAR toolset (~550 commands), VISOR calibration integration, and optimized runtime for both interactive and batch processing workflows. - πŸ“ `terrain-intelligence-generator/docker/` - πŸ“– [Getting Started](docs/getting-started.md) +**Image Variants:** +- **`tig:opensource`** (~2GB) - Complete VICAR system with 976 commands +- **`tig:geocal`** (~3-4GB) - VICAR + GeoCal geometric calibration & bundle adjustment +- πŸ“– [GeoCal Integration Guide](docs/geocal-integration.md) + ### VISOR (VICAR Institutional Stereo Observation Repository) Open source repository containing camera calibration files for multiple missions including M20 (Mars 2020), MER, MSL, and others. TIG integrates with VISOR for accurate stereo processing. @@ -101,13 +123,29 @@ Example workflows for stereo mesh generation. ## Key Tools +### Terrain Reconstruction Pipeline | 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 | | `marsmesh` | Surface triangulation | XYZ + texture | 3D mesh (OBJ) | -| `vicario` | Format conversion | VICAR image | PNG/JPEG/TIFF | +| `marsmap` | Orthoprojection | Images + geometry | Map-projected images | + +### Image Processing Commands (~550 Available) +| 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 | +| `list` | Pixel value display | Analysis | +| `f2` | Image arithmetic | Mathematical | + +*TIG provides ~550 total VICAR commands. Above shows representative examples.* ## Requirements @@ -136,10 +174,10 @@ tig/ ## Contributing Contributions welcome! This project uses: -- **VICAR**: JPL's MIPL image processing system +- **VICAR**: JPL's MIPL general-purpose image processing system (~550 commands) - **Docker**: Containerized VICAR execution environment - **VISOR**: Open source calibration repository for multiple missions -- **Open Source**: Community-driven terrain processing tools +- **Open Source**: Community-driven planetary image processing and terrain reconstruction tools ## License @@ -147,7 +185,7 @@ Apache License 2.0 (see LICENSE file) ## About VICAR -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. +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. VICAR provides comprehensive image processing capabilities including enhancement, filtering, geometric transformation, radiometric calibration, stereo reconstruction, and format conversion. TIG makes this powerful system accessible through modern containerization. ## Acknowledgments diff --git a/docs/README.md b/docs/README.md index 1c14c28..2372271 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,22 +1,21 @@ # TIG Documentation -Documentation for the **Terrain Intelligence Generator (TIG)** β€” Mars 2020 stereo -terrain reconstruction using VICAR MARS tools. +Documentation for the **Terrain Intelligence Generator (TIG)** β€” a containerized VICAR image processing environment with ~550 commands for planetary image analysis, enhancement, transformation, and stereo terrain reconstruction. New here? Start with **[Getting Started](getting-started.md)**. ## Contents ### Getting Started -- **[Getting Started](getting-started.md)** β€” Prerequisites, installation, and your first mesh-generation demo. +- **[Getting Started](getting-started.md)** β€” Prerequisites, installation, and your first demo. ### Demos -- **[Mesh Generation](demos/mesh-generation.md)** β€” Mars 2020 NavCam stereo terrain reconstruction walkthrough. +- **[Mesh Generation](demos/mesh-generation.md)** β€” Mars 2020 NavCam stereo terrain reconstruction walkthrough (flagship capability). - **[Demo Commands](demos/commands.md)** β€” Complete VICAR pipeline using direct Docker commands. - **[Downloading VISOR Data](demos/downloading-visor-data.md)** β€” Obtaining calibration and sample data from VICAR releases. ### Architecture -- **[Components](architecture/components.md)** β€” Overview of the TIG system components. +- **[Components](architecture/components.md)** β€” Overview of the TIG system components and VICAR capabilities. ### Reference - **[Vicario](reference/vicario.md)** β€” Java VicarIO library for VICAR image-format conversion. @@ -24,5 +23,5 @@ New here? Start with **[Getting Started](getting-started.md)**. ## Related - **[Project README](../README.md)** β€” Top-level project overview. -- **[vicar-native-toolkit](../vicar-native-toolkit/README.md)** β€” Native-like command execution for VICAR tools. +- **[vicar-native-toolkit](../vicar-native-toolkit/README.md)** β€” Native-like command execution for all ~550 VICAR tools. - **[Quick Reference](../vicar-native-toolkit/docs/QUICKREF.md)** β€” Toolkit command cheat sheet. diff --git a/docs/architecture/components.md b/docs/architecture/components.md index 6e617ac..373e74f 100644 --- a/docs/architecture/components.md +++ b/docs/architecture/components.md @@ -1,6 +1,6 @@ # TIG Architecture -Overview of the Terrain Intelligence Generator system components. +Overview of the Terrain Intelligence Generator system components and VICAR image processing environment. ## System Components @@ -10,30 +10,37 @@ Overview of the Terrain Intelligence Generator system components. β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ VICAR β”‚ β”‚ MARS Tools β”‚ β”‚ Vicario β”‚ β”‚ -β”‚ β”‚ Programs β”‚ β”‚ β”‚ β”‚ (Java JAR) β”‚ β”‚ -β”‚ β”‚ (~540) β”‚ β”‚ marscorr β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ β”‚ β”‚ marscor3 β”‚ β”‚ Image β”‚ β”‚ -β”‚ β”‚ gen β”‚ β”‚ marsxyz β”‚ β”‚ Converter β”‚ β”‚ -β”‚ β”‚ label β”‚ β”‚ marsmesh β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ list β”‚ β”‚ marsmap β”‚ β”‚ VICARβ†’PNG β”‚ β”‚ +β”‚ β”‚ Commands β”‚ β”‚ (~74) β”‚ β”‚ (Java JAR) β”‚ β”‚ +β”‚ β”‚ (~550) β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ marscorr β”‚ β”‚ Image β”‚ β”‚ +β”‚ β”‚ gen β”‚ β”‚ marscor3 β”‚ β”‚ Converter β”‚ β”‚ +β”‚ β”‚ label β”‚ β”‚ marsxyz β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ stretch β”‚ β”‚ marsmesh β”‚ β”‚ VICARβ†’PNG β”‚ β”‚ +β”‚ β”‚ filter β”‚ β”‚ marsmap β”‚ β”‚ PNGβ†’VICAR β”‚ β”‚ +β”‚ β”‚ geom β”‚ β”‚ marsmos β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ hist β”‚ β”‚ + 68 more β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ + ~540 β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ M2020 Calibration Data β”‚ β”‚ -β”‚ β”‚ - Camera models (NavCam, Mastcam-Z) β”‚ β”‚ +β”‚ β”‚ Multi-Mission Calibration Data (VISOR) β”‚ β”‚ +β”‚ β”‚ - M20, MSL, MER, Phoenix camera models β”‚ β”‚ β”‚ β”‚ - Flat field corrections β”‚ β”‚ β”‚ β”‚ - Geometric distortion models β”‚ β”‚ +β”‚ β”‚ - 1,461 calibration files β”‚ β”‚ +β”‚ β”‚ - 249 sample data files β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό - Input Images Processing Output Meshes - (VICAR .VIC) (Workspace) (OBJ, PNG, XYZ) + Input Images Processing Output Files + (VICAR .VIC) (Workspace) (OBJ, PNG, VICAR, etc.) +``` ``` ## Processing Pipeline -### Full Correlation Pipeline +### Full Stereo Terrain Reconstruction Pipeline (Flagship Capability) ``` Stereo Pair (L/R .VIC) @@ -68,13 +75,20 @@ XYZ Point Cloud (.IMG) ## Core Tools -### VICAR Programs -- **Base**: Full VICAR image processing suite (~540 CLI wrappers on `PATH`) +### VICAR Commands (~550 Available) +- **Base**: Full VICAR image processing suite for planetary science +- **Categories**: + - **Image Generation**: gen, copy + - **Enhancement**: stretch, filter, histogram equalization + - **Geometric**: geom, rotate, size, registration + - **Analysis**: hist, list, label, statistics + - **Mathematical**: f2 (image arithmetic), band operations + - **Multispectral**: band manipulation, transformations - **Location**: `/usr/local/bin/` (wrappers) β†’ `/usr/local/vicar/dev/` - **Runtime**: TAE (Terminal Application Executive) -### MARS Tools -Specialized Mars terrain processing: +### MARS Terrain Tools (~74 Commands) +Specialized Mars terrain processing suite: | Tool | Function | Input | Output | |------|----------|-------|--------| @@ -83,14 +97,18 @@ Specialized Mars terrain processing: | marsxyz | 3D triangulation | Disparity + images | XYZ point cloud | | marsmesh | Surface meshing | XYZ + texture | OBJ mesh | | marsmap | Orthoprojection | XYZ | Map projection | +| marsmos | Mosaicking | Multiple images | Panorama | +| marsautotie | Tie point detection | Image pair | Tie points | +| marsrfilt | Rover filtering | XYZ | Filtered XYZ | ### Vicario (Java) -- **Purpose**: VICAR format conversion +- **Purpose**: VICAR format conversion (VICAR ↔ standard formats) - **Technology**: Java 11 + Java Advanced Imaging - **Features**: - Dynamic range rescaling (16-bit β†’ 8-bit) - - Format support: PNG, JPEG, TIFF + - Format support: PNG, JPEG, TIFF (read and write) - Proper VICAR label parsing + - Bidirectional conversion ## Data Flow @@ -127,7 +145,7 @@ Specialized Mars terrain processing: ## Calibration Data -### M2020 Calibration Structure +### Multi-Mission Calibration Structure (VISOR Integration) ``` mars_calibration_m20/ @@ -136,11 +154,20 @@ mars_calibration_m20/ β”‚ β”œβ”€β”€ M20_SN_0102.cahvore # NavCam Right β”‚ β”œβ”€β”€ ZL*.cahvore # Mastcam-Z Left β”‚ └── ZR*.cahvore # Mastcam-Z Right + +mars_calibration_msl/ +mars_calibration_mer/ +mars_calibration_phoenix/ +β”œβ”€β”€ camera_models/ β”œβ”€β”€ flat_fields/ β”‚ └── *.parms # Flat field corrections └── param_files/ β”œβ”€β”€ M20_camera_mapping.xml - └── MSL_camera_mapping.xml + β”œβ”€β”€ MSL_camera_mapping.xml + └── MER_camera_mapping.xml + +Total: 1,461 calibration files across all missions + 249 sample data files ``` ### Camera Models @@ -157,18 +184,18 @@ Base Layer: Oracle Linux 8 ↓ Builder Stage: downloads pre-built VICAR + external library releases ↓ -Runtime Layer: VICAR binaries + MARS tools + Java + vicario.jar + calibration +Runtime Layer: VICAR binaries (~550 commands) + MARS tools (~74) + Java + vicario.jar + multi-mission calibration ↓ -Command Wrappers: ~540 CLI wrappers generated under /usr/local/bin +Command Wrappers: ~550 CLI wrappers generated under /usr/local/bin ↓ Entry Point: Shell with VICAR environment ``` ### Volume Mounts -- `/workspace` - Input/output files -- `/usr/local/vicar/mars_calib` - M2020 calibration (read-only) -- `/usr/local/vicar/visor_data` - Sample data (optional) +- `/workspace` - Input/output files (VICAR images, meshes, point clouds, processed data) +- `/usr/local/vicar/mars_calib` - Multi-mission calibration data (M20, MSL, MER, Phoenix) (read-only) +- `/usr/local/vicar/visor_data` - Sample data files (optional) ### Environment Variables diff --git a/docs/getting-started.md b/docs/getting-started.md index 90b4176..5736a19 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting Started with TIG -Quick setup guide for running Mars 2020 stereo mesh generation. +Quick setup guide for TIG - a VICAR image processing environment with ~550 commands. This guide demonstrates the flagship stereo terrain reconstruction workflow. ## Prerequisites @@ -115,9 +115,13 @@ ERROR: MARS calibration not found ## Next Steps +### Terrain Reconstruction - **[Mesh Generation Demo](demos/mesh-generation.md)** - Detailed walkthrough - **[Command Reference](demos/commands.md)** - Available VICAR tools + +### General Image Processing - **[Vicario Reference](reference/vicario.md)** - Image format conversion +- **VICAR Commands** - Access ~550 commands for enhancement, filtering, geometric operations via vicar-native-toolkit ## Configuration diff --git a/terrain-intelligence-generator/docker/Dockerfile b/terrain-intelligence-generator/docker/Dockerfile index d762c4c..9972c14 100644 --- a/terrain-intelligence-generator/docker/Dockerfile +++ b/terrain-intelligence-generator/docker/Dockerfile @@ -294,6 +294,9 @@ RUN ARCH_DIR="x86-64-linx" && \ echo "export VICSYS=DEVELOPMENT" >> /usr/local/bin/$cmdname; \ echo "export LD_LIBRARY_PATH=$VICAR_LIB_PATH:\$LD_LIBRARY_PATH" >> /usr/local/bin/$cmdname; \ echo "export PATH=${V2TOP}/gui/lib/$ARCH_DIR:${V2TOP}/mars/lib/$ARCH_DIR:${V2TOP}/p2/lib/$ARCH_DIR:\$PATH" >> /usr/local/bin/$cmdname; \ + echo "# X11 app-defaults (.xres) so Motif widget labels resolve instead of showing placeholder resource names" >> /usr/local/bin/$cmdname; \ + echo "export XFILESEARCHPATH=\"${V2TOP}/gui/lib/$ARCH_DIR/%N%S.xres:${V2TOP}/p2/lib/$ARCH_DIR/%N%S.xres:${V2TOP}/mars/lib/$ARCH_DIR/%N%S.xres:/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S\${XFILESEARCHPATH:+:\$XFILESEARCHPATH}\"" >> /usr/local/bin/$cmdname; \ + echo "export XBMLANGPATH=\"%D:${V2TOP}/p2/lib/$ARCH_DIR/%B\"" >> /usr/local/bin/$cmdname; \ echo "$cmd \"\$@\"" >> /usr/local/bin/$cmdname; \ echo "exit_code=\$?" >> /usr/local/bin/$cmdname; \ echo "# VICAR commands often return non-zero on success, treat 0-2 as success" >> /usr/local/bin/$cmdname; \ @@ -319,6 +322,9 @@ RUN ARCH_DIR="x86-64-linx" && \ echo "export VICSYS=DEVELOPMENT" >> /etc/profile.d/vicar.sh && \ echo "export LD_LIBRARY_PATH=$VICAR_LIB_PATH:\$LD_LIBRARY_PATH" >> /etc/profile.d/vicar.sh && \ echo "export PATH=${V2TOP}/tae53/bin:${V2TOP}/bin:\$PATH" >> /etc/profile.d/vicar.sh && \ + echo "# X11 app-defaults (.xres) so Motif GUI (xvd) widget labels resolve instead of showing placeholder resource names" >> /etc/profile.d/vicar.sh && \ + echo "export XFILESEARCHPATH=\"${V2TOP}/gui/lib/$ARCH_DIR/%N%S.xres:${V2TOP}/p2/lib/$ARCH_DIR/%N%S.xres:${V2TOP}/mars/lib/$ARCH_DIR/%N%S.xres:/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S\${XFILESEARCHPATH:+:\$XFILESEARCHPATH}\"" >> /etc/profile.d/vicar.sh && \ + echo "export XBMLANGPATH=\"%D:${V2TOP}/p2/lib/$ARCH_DIR/%B\"" >> /etc/profile.d/vicar.sh && \ chmod +x /etc/profile.d/vicar.sh # Verify VICAR installation diff --git a/vicar-native-toolkit/.envrc b/vicar-native-toolkit/.envrc index 688a6aa..2d1be80 100644 --- a/vicar-native-toolkit/.envrc +++ b/vicar-native-toolkit/.envrc @@ -18,8 +18,15 @@ fi # Disable SELinux label enforcement on the container (Linux only). # May be required for images that load certain 32-bit legacy shared # libraries, which can trigger "cannot change memory protections" under -# SELinux. Opt-in; default keeps standard labeling. Set -# DISABLE_SELINUX_LABEL=true in .envrc.local when needed. +# SELinux, and is required for the container to access the host X11 socket +# (/tmp/.X11-unix) when SELinux is Enforcing. Opt-in; default keeps standard +# labeling. Set DISABLE_SELINUX_LABEL=true in .envrc.local to force it. +# When left unset, the toolkit auto-enables it on SELinux-Enforcing Linux hosts. +if [[ -z "${DISABLE_SELINUX_LABEL+x}" ]]; then + DISABLE_SELINUX_LABEL_EXPLICIT=false +else + DISABLE_SELINUX_LABEL_EXPLICIT=true +fi : ${DISABLE_SELINUX_LABEL:=false} # VICAR paths inside container (for terrain-intelligence-generator:opensource) @@ -40,6 +47,73 @@ log_error() { echo "[vicar-toolkit] ERROR: $1" >&2 } +# ===== X11 / Display Readiness ===== +# Ensures the host X server will accept connections from the container, so GUI +# tools (xvd) don't fail with "Authorization required, but no authorization +# protocol specified" / "Can't open display". Runs on every activation because +# xhost ACLs and XQuartz state do not persist across restarts/reboots. +ensure_x11_ready() { + if [[ "${HOST_OS}" == "Darwin" ]]; then + # macOS: container reaches XQuartz over TCP via host.docker.internal:0. + # Requires XQuartz running, TCP listening (nolisten_tcp=false), and the + # host to authorize localhost (xhost +localhost). + if ! command -v xhost >/dev/null 2>&1; then + log_info "XQuartz/xhost not found. Install with: brew install --cask xquartz (GUI tools will not work until then)" + return 0 + fi + + # Ensure XQuartz allows TCP connections (persisted preference). + if command -v defaults >/dev/null 2>&1; then + if [[ "$(defaults read org.xquartz.X11 nolisten_tcp 2>/dev/null)" != "0" ]]; then + defaults write org.xquartz.X11 nolisten_tcp -bool false 2>/dev/null || true + log_info "Set XQuartz to allow TCP connections (restart XQuartz if GUI still fails)" + fi + fi + + # Start XQuartz if not running. + if ! pgrep -q -x Xquartz && ! pgrep -q -x X11.bin 2>/dev/null; then + log_info "Starting XQuartz..." + open -a XQuartz 2>/dev/null || log_info "Could not auto-start XQuartz; run: open -a XQuartz" + # Give XQuartz a moment to bind the TCP socket before xhost. + local _tries=0 + while ! pgrep -q -x Xquartz && [[ ${_tries} -lt 10 ]]; do + sleep 0.5 + ((_tries++)) + done + fi + + # Authorize localhost so the container's TCP connection is accepted. + if DISPLAY=:0 xhost +localhost >/dev/null 2>&1; then + log_info "X11 authorized (xhost +localhost)" + else + log_info "Could not run 'xhost +localhost' yet. If GUI fails, ensure XQuartz is running then run: xhost +localhost && toolkit-restart" + fi + else + # Linux: container shares the X11 unix socket via --network host. + # Authorize local (non-network) connections to the display. Use the + # broad "+local:" form: SELinux label=disable makes the container + # connect as the "LOCAL:" family, which "+local:docker" does NOT cover. + if command -v xhost >/dev/null 2>&1 && [[ -n "${DISPLAY}" ]]; then + xhost +local: >/dev/null 2>&1 || true + fi + + # SELinux Enforcing blocks the container (container_t) from the host + # X11 socket (/tmp/.X11-unix), so xvd fails with a misleading + # "Can't open display". Auto-enable label=disable unless the user has + # explicitly configured DISABLE_SELINUX_LABEL themselves. + if command -v getenforce >/dev/null 2>&1 && [[ "$(getenforce 2>/dev/null)" == "Enforcing" ]]; then + if [[ "${DISABLE_SELINUX_LABEL_EXPLICIT}" != "true" ]]; then + if [[ "${DISABLE_SELINUX_LABEL}" != "true" ]]; then + DISABLE_SELINUX_LABEL=true + log_info "SELinux is Enforcing: enabling container '--security-opt label=disable' so GUI tools can reach the X11 socket (set DISABLE_SELINUX_LABEL=false in .envrc.local to override)" + fi + elif [[ "${DISABLE_SELINUX_LABEL}" != "true" ]]; then + log_info "SELinux is Enforcing and DISABLE_SELINUX_LABEL=false: GUI tools (xvd) may fail with 'Can't open display'. Set DISABLE_SELINUX_LABEL=true in .envrc.local if so." + fi + fi + fi +} + # ===== Container Management ===== ensure_container_running() { if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then @@ -156,8 +230,23 @@ else REL_PATH="." fi +# X11 app-defaults so Motif GUI (xvd) widget labels resolve to real text +# instead of placeholder resource names. Passed at exec time so this works +# even on images built before the in-image fix. %N=class (e.g. XVd), +# %S=suffix -> resolves \${GUILIB}/XVd.xres. Runtime value is a fallback: +# if the container already sets XFILESEARCHPATH, that is preserved (appended). +VICAR_GUI_LIB="${VICAR_INSTALL_PREFIX}/gui/lib/x86-64-linx" +VICAR_P2_LIB="${VICAR_INSTALL_PREFIX}/p2/lib/x86-64-linx" +VICAR_MARS_LIB="${VICAR_INSTALL_PREFIX}/mars/lib/x86-64-linx" +X11_DEFAULTS="/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S" +XFSP="\${VICAR_GUI_LIB}/%N%S.xres:\${VICAR_P2_LIB}/%N%S.xres:\${VICAR_MARS_LIB}/%N%S.xres:\${X11_DEFAULTS}" +XBMLP="%D:\${VICAR_P2_LIB}/%B" + # Execute command in container at correct working directory -exec docker exec -w "/workspace/\${REL_PATH}" "\${CONTAINER_NAME}" "\${TOOL_NAME}" "\$@" +exec docker exec \\ + -e "XFILESEARCHPATH=\${XFSP}" \\ + -e "XBMLANGPATH=\${XBMLP}" \\ + -w "/workspace/\${REL_PATH}" "\${CONTAINER_NAME}" "\${TOOL_NAME}" "\$@" VICAR_EXEC_EOF chmod +x "${exec_script}" @@ -232,10 +321,11 @@ create_utility_commands() { cat > "${utils_script}" << UTILS_HEADER_EOF #!/bin/bash # Toolkit utility commands handler -# Handles: toolkit-shell, toolkit-stop, toolkit-restart, toolkit-status +# Handles: toolkit-shell, toolkit-stop, toolkit-restart, toolkit-update, toolkit-status UTIL_NAME="\$(basename "\$0")" CONTAINER_NAME="${CONTAINER_NAME}" +CONTAINER_IMAGE="${CONTAINER_IMAGE}" UTILS_HEADER_EOF cat >> "${utils_script}" << 'TOOLKIT_UTILS_EOF' @@ -253,6 +343,28 @@ case "$UTIL_NAME" in echo "Container stopped. Re-enter directory to restart." ;; + toolkit-update) + echo "Pulling latest image: ${CONTAINER_IMAGE}" + old_id="$(docker image inspect "${CONTAINER_IMAGE}" --format '{{.Id}}' 2>/dev/null || true)" + if ! docker pull --platform linux/amd64 "${CONTAINER_IMAGE}"; then + echo "Error: docker pull failed for ${CONTAINER_IMAGE}" >&2 + exit 1 + fi + new_id="$(docker image inspect "${CONTAINER_IMAGE}" --format '{{.Id}}' 2>/dev/null || true)" + if [[ "${old_id}" == "${new_id}" ]]; then + echo "Image already up to date (${new_id#sha256:})." + else + echo "Image updated: ${old_id#sha256:} -> ${new_id#sha256:}" + fi + if docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then + docker stop "${CONTAINER_NAME}" >/dev/null 2>&1 || true + docker rm "${CONTAINER_NAME}" >/dev/null 2>&1 || true + echo "Old container removed. Re-enter directory to recreate from the new image." + else + echo "No running container. Re-enter directory to create one from the new image." + fi + ;; + toolkit-status) SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" echo "VICAR Native Toolkit Status:" @@ -271,7 +383,7 @@ case "$UTIL_NAME" in # Direct invocation handler if [[ $# -eq 0 ]]; then echo "Usage: toolkit-utils " - echo "Commands: shell, stop, restart, status" + echo "Commands: shell, stop, restart, update, status" echo "Or create symlinks: ln -s toolkit-utils toolkit-" exit 1 fi @@ -291,9 +403,10 @@ TOOLKIT_UTILS_EOF ln -sf "../toolkit-utils" "${WRAPPER_DIR}/toolkit-shell" ln -sf "../toolkit-utils" "${WRAPPER_DIR}/toolkit-stop" ln -sf "../toolkit-utils" "${WRAPPER_DIR}/toolkit-restart" + ln -sf "../toolkit-utils" "${WRAPPER_DIR}/toolkit-update" ln -sf "../toolkit-utils" "${WRAPPER_DIR}/toolkit-status" - log_info "Created 4 utility command symlinks" + log_info "Created 5 utility command symlinks" } # ===== Main Activation ===== @@ -304,6 +417,9 @@ main() { # Ensure workspace exists mkdir -p "${WORKSPACE_ROOT}" + # Ensure host X server will accept GUI connections from the container + ensure_x11_ready + # Ensure container is running if ! ensure_container_running; then log_error "Failed to start container" diff --git a/vicar-native-toolkit/README.md b/vicar-native-toolkit/README.md index ab29a68..95e1b6d 100644 --- a/vicar-native-toolkit/README.md +++ b/vicar-native-toolkit/README.md @@ -1,6 +1,8 @@ # VICAR Native Toolkit -Make 540+ VICAR CLI programs living inside a Docker container feel like native commands on your host machine. When you activate the environment, the container starts, directories mount, X11 routing is established, and every command "just works" as if installed locally. +Make ~550 VICAR image processing commands living inside a Docker container feel like native commands on your host machine. When you activate the environment, the container starts, directories mount, X11 routing is established, and every command "just works" as if installed locally. + +This provides full access to VICAR's comprehensive image processing capabilities (~550 commands) including enhancement, filtering, geometric transformation, analysis, terrain reconstruction, and format conversion. **Works on both Linux (bash) and macOS (zsh), including Apple Silicon (M1/M2).** @@ -25,10 +27,10 @@ This project implements the docker-native-wrapper pattern using: ### Wrapper Architecture -Instead of generating 540+ individual wrapper scripts, the toolkit uses a symlink-based approach: +Instead of generating ~550 individual wrapper scripts, the toolkit uses a symlink-based approach: 1. **Single wrapper script** (`vicar-exec`) - Handles all VICAR commands -2. **Command detection** - Auto-discovers available commands from container +2. **Command detection** - Auto-discovers available commands from container (~550 total) 3. **Symlink generation** - Creates symlinks pointing to `vicar-exec` for each command 4. **Dynamic routing** - `vicar-exec` determines which command to run based on symlink name @@ -37,6 +39,7 @@ Instead of generating 540+ individual wrapper scripts, the toolkit uses a symlin - Reduced disk usage (~2MB vs 3.5MB) - Single point of maintenance - Identical functionality +- Access to all ~550 VICAR commands plus ~74 MARS terrain tools ### Performance @@ -161,6 +164,7 @@ toolkit-shell # Open interactive shell in container toolkit-status # Show container status and wrapper count toolkit-stop # Stop and remove container toolkit-restart # Restart container (useful after config changes) +toolkit-update # Pull the latest CONTAINER_IMAGE and recreate the container toolkit-verify-calib # Verify MARS calibration mounting (if configured) ``` @@ -206,10 +210,10 @@ vicar-native-toolkit/ - Starts the container (or uses existing one) - Configures X11 forwarding for your platform - Generates `vicar-exec` and `toolkit-utils` scripts - - Auto-discovers available VICAR commands + - Auto-discovers available VICAR commands (~550 total) - Creates symlinks for each command in `.direnv/wrappers/` - Adds `.direnv/wrappers/` to your PATH -4. All VICAR commands are now available +4. All VICAR commands are now available (~550 image processing commands) ### Command Execution Flow @@ -447,3 +451,16 @@ For issues: --- **Happy VICAR processing!** + +## Summary + +The VICAR Native Toolkit provides seamless access to ~550 VICAR image processing commands through Docker containerization. Use it for: + +- **Image Enhancement**: stretch, filter, histogram operations +- **Geometric Operations**: rotate, resize, registration, transformation +- **Terrain Reconstruction**: Full stereo-to-mesh pipeline (marscorr, marsxyz, marsmesh) +- **Format Conversion**: VICAR ↔ PNG/JPEG/TIFF (vicario) +- **Analysis**: Histograms, statistics, pixel inspection +- **Multi-Mission Support**: M20, MSL, MER, Phoenix calibrations + +All commands available as native-like CLI tools with minimal latency (~50-100ms). diff --git a/vicar-native-toolkit/docs/CONFIGURATION.md b/vicar-native-toolkit/docs/CONFIGURATION.md index b06aea0..ce0d3f1 100644 --- a/vicar-native-toolkit/docs/CONFIGURATION.md +++ b/vicar-native-toolkit/docs/CONFIGURATION.md @@ -118,6 +118,28 @@ make bootstrap MARS_CALIB=/path/to/mars_calibration toolkit-verify-calib ``` +### SELinux (Linux) + +On Linux hosts with SELinux in **Enforcing** mode, the container (`container_t`) +is denied access to the host X11 socket (`/tmp/.X11-unix`), so GUI tools such as +`xvd` fail with a misleading `Can't open display`. The toolkit handles this +automatically: + +```bash +# Auto-enabled on SELinux-Enforcing hosts when left unset. +# Adds "--security-opt label=disable" at container creation. +DISABLE_SELINUX_LABEL=true +``` + +- **Unset (default):** auto-enabled only when `getenforce` reports `Enforcing`. +- **`DISABLE_SELINUX_LABEL=true`:** always disable labeling. +- **`DISABLE_SELINUX_LABEL=false`:** never disable it (the toolkit logs a hint + if it detects Enforcing mode and GUI tools may fail). + +Changing this only affects a newly created container. After changing it, run +`toolkit-update` (or `toolkit-restart` then re-enter the directory) to recreate +the container with the new setting. + ### Command Auto-Discovery By default, commands are auto-discovered from the container: diff --git a/vicar-native-toolkit/docs/QUICKREF.md b/vicar-native-toolkit/docs/QUICKREF.md index 4addb9c..62b6346 100644 --- a/vicar-native-toolkit/docs/QUICKREF.md +++ b/vicar-native-toolkit/docs/QUICKREF.md @@ -50,6 +50,7 @@ toolkit-status # Show container status toolkit-shell # Interactive shell in container toolkit-stop # Stop and remove container toolkit-restart # Restart container +toolkit-update # Pull latest image and recreate container toolkit-verify-calib # Verify MARS calibration (if configured) # VICAR commands work natively @@ -170,7 +171,7 @@ readlink .direnv/wrappers/gen # Should point to ../vicar-exec # Image issues docker images | grep terrain-intelligence-generator -docker pull ghcr.io/nasa-ammos/tig/terrain-intelligence-generator:opensource +toolkit-update # pull latest CONTAINER_IMAGE and recreate container # Container logs docker logs vicar-sidecar diff --git a/vicar-native-toolkit/docs/VICAR_NATIVE_TOOLKIT_WALKTHROUGH.md b/vicar-native-toolkit/docs/VICAR_NATIVE_TOOLKIT_WALKTHROUGH.md index c8758f0..21c9ef9 100644 --- a/vicar-native-toolkit/docs/VICAR_NATIVE_TOOLKIT_WALKTHROUGH.md +++ b/vicar-native-toolkit/docs/VICAR_NATIVE_TOOLKIT_WALKTHROUGH.md @@ -140,6 +140,7 @@ Available commands: toolkit-shell - Open interactive shell in container toolkit-stop - Stop and remove container toolkit-restart - Restart container with new configuration + toolkit-update - Pull latest image and recreate container VICAR tools: 543 commands available Working directory: /vicar-native-toolkit/workspace