Nuke-Templates/Scripts/README_CONVERTER.md

# 3DE to Nuke Track Converter v2.0

A professional, feature-rich tool for converting 3DEqualizer 2D tracks to Nuke Tracker4 nodes with a beautiful terminal interface.

## Features

### ✨ Core Improvements (from v1.0)

1. **CLI Arguments & Configurable I/O** - No more hard-coded filenames
2. **Robust Error Handling** - Clear error messages with line numbers
3. **Gap Filling & Interpolation** - Handle missing frames intelligently
4. **Coordinate System Support** - Pixels or normalized coordinates with transforms
5. **Track Name Preservation** - Custom naming with prefixes
6. **Nuke Version Compatibility** - Configurable version and format settings
7. **Multiple Output Modes** - Interactive TUI, CLI, dry-run, and verbose modes
8. **Performance Optimized** - Progress bars and efficient processing
9. **Beautiful TUI** - Rich terminal interface with tables, panels, and colors
10. **Comprehensive Validation** - Input validation at every step

## Installation

```bash
# Install dependencies
pip install -r requirements.txt

# Or install Rich directly
pip install rich
```

## Usage

### Interactive Mode (Recommended for First-Time Users)

Simply run the script without arguments to enter interactive mode:

```bash
python 3de-to-nuke-converter.py
```

You'll be guided through a beautiful TUI with prompts for:
- Input file path
- Output file path
- Resolution settings
- Coordinate space
- Gap filling options
- Track enable settings

### CLI Mode (For Automation & Scripting)

```bash
# Basic usage
python 3de-to-nuke-converter.py -i input.txt -o output.nk

# Full example with all options
python 3de-to-nuke-converter.py \
  -i tracks.txt \
  -o shot_001_tracks.nk \
  -w 3840 \
  --height 2160 \
  --input-space normalized \
  --fill-gaps \
  --fill-strategy linear \
  --flip-y \
  --enable-all \
  --name-prefix "shot001_" \
  --nuke-version "15.2 v3" \
  --format "UHD_3840x2160" \
  --verbose
```

## Command-Line Options

### Required (CLI Mode)
- `-i, --input` - Input 3DE track file path
- `-o, --output` - Output Nuke .nk file path

### Resolution & Format
- `-w, --width` - Input resolution width (default: 2048)
- `--height` - Input resolution height (default: 1556)
- `--format` - Nuke format name (default: 2K_Super_35(full-ap))
- `--nuke-version` - Nuke version string (default: 15.2 v3)

### Coordinate Handling
- `--input-space {pixels,normalized}` - Input coordinate space (default: pixels)
- `--flip-y` - Flip Y coordinates (useful for different coordinate origins)

### Track Processing
- `--fill-gaps` - Fill missing frames in tracks
- `--fill-strategy {last,linear}` - Gap filling method:
  - `last` - Use last known value
  - `linear` - Linear interpolation between points
- `--enable-all` - Enable all tracks (default: only first track enabled)
- `--name-prefix` - Prefix for track names (e.g., "shot001_")

### Output Control
- `-v, --verbose` - Show detailed progress and statistics
- `-q, --quiet` - Minimal output (errors only)
- `--dry-run` - Parse and validate without writing output file

## Examples

### Example 1: Basic Conversion
```bash
python 3de-to-nuke-converter.py -i my_tracks.txt -o my_tracks.nk
```

### Example 2: 4K Resolution with Normalized Coordinates
```bash
python 3de-to-nuke-converter.py \
  -i tracks_4k.txt \
  -o output_4k.nk \
  -w 3840 \
  --height 2160 \
  --input-space normalized
```

### Example 3: Fill Gaps with Linear Interpolation
```bash
python 3de-to-nuke-converter.py \
  -i sparse_tracks.txt \
  -o filled_tracks.nk \
  --fill-gaps \
  --fill-strategy linear \
  --verbose
```

### Example 4: Batch Processing Script
```bash
#!/bin/bash
for file in tracks/*.txt; do
    output="nuke/$(basename "$file" .txt).nk"
    python 3de-to-nuke-converter.py \
      -i "$file" \
      -o "$output" \
      --fill-gaps \
      --enable-all \
      -q
done
```

### Example 5: Validation Only (Dry Run)
```bash
python 3de-to-nuke-converter.py \
  -i tracks.txt \
  -o /dev/null \
  --dry-run \
  --verbose
```

## Input File Format

The script expects 3DEqualizer 2D track export format:

```
<track_count>
<track_number>
<frame_start>
<num_points>
<frame> <x> <y>
<frame> <x> <y>
...
```

Example:
```
2
1
1001
3
1001 1024.5 778.2
1002 1025.1 779.0
1003 1026.0 780.5
2
1001
2
1001 512.0 389.0
1002 513.5 390.2
```

## Output

The script generates a Nuke .nk file containing a Tracker4 node with all tracks properly formatted.

### Features of Generated Output:
- Proper Nuke version headers
- Configurable format and resolution
- Correct center point calculation
- All track data as animation curves
- Customizable track enable states
- Compatible with Nuke 13.0+

## Error Handling

The script provides detailed error messages for common issues:

- **File not found** - Clear path indication
- **Invalid format** - Line number and content shown
- **Missing data** - Specific track and point identified
- **Parse errors** - Context and suggestions provided

## Performance

- **Progress bars** for long operations
- **Efficient parsing** with minimal memory overhead
- **Streaming output** for large track sets
- **Optimized** for files with 1000+ tracks

## Tips & Best Practices

1. **Use Interactive Mode** for one-off conversions
2. **Use CLI Mode** for batch processing and automation
3. **Enable --verbose** when troubleshooting
4. **Use --dry-run** to validate files before conversion
5. **Fill gaps** when tracks have dropped frames
6. **Use linear interpolation** for smoother motion
7. **Flip Y** if coordinate systems don't match
8. **Name prefix** helps organize tracks by shot

## Troubleshooting

### "File not found" error
- Check the file path is correct
- Use absolute paths if relative paths fail
- Ensure file has .txt extension

### "Invalid track count" error
- Verify the first line contains a number
- Check file isn't corrupted
- Ensure proper 3DE export format

### Coordinates seem wrong
- Try `--flip-y` flag
- Check `--input-space` setting
- Verify resolution matches source

### Tracks have gaps
- Use `--fill-gaps` flag
- Choose appropriate `--fill-strategy`
- Consider if gaps are intentional

## Version History

### v2.0 (Current)
- Complete rewrite with Rich TUI
- Interactive and CLI modes
- Robust error handling
- Gap filling and interpolation
- Coordinate transformations
- Configurable everything
- Beautiful progress bars and tables

### v1.0 (Original)
- Basic conversion functionality
- Hard-coded settings
- Minimal error handling

## License

Part of the Biohazard VFX Nuke Template Suite

## Support

For issues or questions, contact the VFX pipeline team.