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

# 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:

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)

# 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

python 3de-to-nuke-converter.py -i my_tracks.txt -o my_tracks.nk

Example 2: 4K Resolution with Normalized Coordinates

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

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

#!/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)

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.