# Camera Raw ISP Capture Batch Tool

This tool captures raw camera sensor data through the complete ISP (Image Signal Processing) pipeline at multiple brightness levels for camera calibration and validation purposes. It works with Omniverse Kit and provides selective stage saving for optimized performance and storage.

## Overview

The script captures images from a virtual camera sensor in an Omniverse scene, processing them through a complete ISP pipeline that includes:

1. **HDR** - High Dynamic Range raw sensor data
2. **Color Correction** - Color matrix correction and white balance
3. **CFA** - Color Filter Array encoding (Bayer pattern)
4. **Noise** - Sensor noise simulation
5. **Companding** - Tone curve application
6. **ISP** - ISP model processing
7. **RGB** - Final RGB output

## Usage

### Basic Usage

```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_ColorChecker
```

### Command Line Arguments

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `--pose` | str | `Chart_ColorChecker` | Target chart/pose selection |
| `--time_secs` | float | `3.0` | Capture duration per brightness level |
| `--output_dir` | str | `<HOME>/Documents/kit_sensors/capture` | Output directory for captured files |
| `--save_stages` | list | `all stages` | Which ISP pipeline stages to save |

### Available Poses

| Pose Name | Description | Brightness Levels (nits) |
|-----------|-------------|---------------------------|
| `Chart_Calibration` | Calibration chart | [10, 10, 100, 1000] |
| `Chart_HDR` | HDR test chart | [0.001, 0.01, 0.1, 1, 10, 100] |
| `Chart_ColorChecker` | Color checker chart | [0.001, 0.1, 1, 100, 10000] |
| `Chart_Sphere` | Sphere target | [0.01, 0.1, 1, 10, 100, 1000] |
| `Chart_Motion` | Motion blur test | [100, 10000] |
| `Chart_Flicker` | Flicker test | [1000] |
| `Chart_TrafficLight` | Traffic light simulation | [1000] |
| `Chart_Depth` | Depth test chart | [1000] |

### Available ISP Stages

| Stage Name | Description | Output File Pattern |
|------------|-------------|---------------------|
| `hdr` | Raw HDR sensor data | `1-hdr_[pose]_[nits]nits.bin` |
| `colcorrect` | Color corrected data | `2-colcorrect_[pose]_[nits]nits.bin` |
| `cfa` | CFA encoded data | `3-cfa_[pose]_[nits]nits.bin` |
| `noise` | Noise processed data | `4-noise_[pose]_[nits]nits.bin` |
| `companding` | Tone curve applied | `5-companding_[pose]_[nits]nits.bin` |
| `isp` | ISP model output | `6-isp_[pose]_[nits]nits.bin` |
| `rgb` | Final RGB output | `7-rgb_[pose]_[nits]nits.bin` |

## Usage Examples

### 1. Basic Color Checker Capture (All Stages)
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_ColorChecker
```
- Captures 5 brightness levels: 0.001, 0.1, 1, 100, 10000 nits
- Saves all 7 ISP pipeline stages
- Output: 35 files total (5 levels × 7 stages)

### 2. HDR Chart with Only RGB Output
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_HDR --save_stages rgb
```
- Captures 6 brightness levels: 0.001, 0.01, 0.1, 1, 10, 100 nits
- Saves only final RGB output
- Output: 6 files total (6 levels × 1 stage)
- **Performance**: Fastest execution, minimal storage

### 3. Raw Sensor Data Only
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_Sphere --save_stages hdr cfa
```
- Captures 6 brightness levels
- Saves only raw HDR and CFA encoded data
- Output: 12 files total (6 levels × 2 stages)
- **Use case**: Raw sensor analysis

### 4. ISP Input/Output Comparison
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_Calibration --save_stages companding rgb
```
- Captures 4 brightness levels
- Saves ISP input (companding) and output (RGB)
- Output: 8 files total (4 levels × 2 stages)
- **Use case**: ISP algorithm validation

### 5. Custom Output Directory and Timing
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_Motion --output_dir /data/captures --time_secs 5.0 --save_stages hdr rgb
```
- Longer capture time for motion analysis
- Custom output directory
- Raw and processed data only

### 6. Complete Pipeline Analysis
```bash
./kit/_build/linux-x86_64/release/omni.app.sensors.sh --exec ./kit/source/python/sensors/tools/cam/calibration/camera_raw_isp_capture.py --/rtx/materialDb/rtSensorMaterialLogs=false --/app/quiet=true --/app/useFabricSceneDelegate=true -- --pose Chart_ColorChecker --save_stages hdr colcorrect cfa noise companding isp rgb
```
- Explicitly specify all stages (same as default)
- Full pipeline analysis
- Maximum file output

## Output Files

### File Naming Convention
```
[stage_number]-[stage_name]_[pose]_[brightness]nits.bin
```

### Example Output
For `--pose Chart_HDR --save_stages hdr rgb`:
```
1-hdr_Chart-HDR_0_001nits.bin
7-rgb_Chart-HDR_0_001nits.bin
1-hdr_Chart-HDR_0_01nits.bin
7-rgb_Chart-HDR_0_01nits.bin
1-hdr_Chart-HDR_0_1nits.bin
7-rgb_Chart-HDR_0_1nits.bin
1-hdr_Chart-HDR_1nits.bin
7-rgb_Chart-HDR_1nits.bin
1-hdr_Chart-HDR_10nits.bin
7-rgb_Chart-HDR_10nits.bin
1-hdr_Chart-HDR_100nits.bin
7-rgb_Chart-HDR_100nits.bin
```

### Recommended Configurations

| Use Case | Recommended Stages | Benefits |
|----------|-------------------|----------|
| Camera calibration | `rgb` | Fast, minimal storage |
| Sensor analysis | `hdr`, `cfa` | Raw data focus |
| ISP validation | `companding`, `rgb` | Input/output comparison |
| Algorithm development | `hdr`, `noise`, `rgb` | Key processing steps |
| Complete analysis | `all` | Full pipeline visibility |

## Technical Details

### Camera Configuration
- **Sensor**: IMX728 fisheye camera
- **Resolution**: 1920×1536
- **Projection**: fisheyeOpenCV
- **Focal Length**: fx=489.56, fy=489.29
- **Principal Point**: cx=965.84, cy=763.0
- **Distortion**: k1=0.075, k2=-0.025, k3=0.009, k4=0.001

### ISP Pipeline
- **Color Matrix**: Custom 3×3 matrix for IMX728
- **White Balance**: [0.71, 0.45, 0.37]
- **CFA Pattern**: RGGB Bayer
- **Noise Model**: Shot noise + dark current
- **Companding**: 18-point tone curve
- **ISP Program**: `isp_program_1749-0_00000002.ispprg`

### File Cleanup
- Temporary files (e.g., `1-hdr0.bin`) are automatically removed after Kit shutdown
- Only properly named output files remain
- 2-second delay ensures Kit fully releases file handles

## Integration

This tool integrates with other calibration scripts:
- **calibration_run.py**: Process captured images for intrinsic calibration
- **calibration_sim_validation.py**: Validate calibration results