STMap Exporter

Overview

STMap Exporter is a Blender extension that exports camera lens distortion data from the Movie Clip Editor as STMap images.

It accurately calculates Blender's internal distortion models (Polynomial, Division, Nuke, and Brown-Conrady) and generates 32-bit Float STMaps. By loading these EXR files into an STMap node in external compositors like Nuke, Fusion, or Natron, you can easily apply or remove lens distortion matching Blender's tracking environment with pixel accuracy.

Features

• Pixel-Perfect Math: Faithfully replicates Blender's internal normalization scales, principal point shifts, and asymmetric aspect ratios, completely eliminating the visual mismatch commonly found between Blender and compositors.
• Advanced Overscan Control: Choose between Auto BBox expansion based on the distortion curve, or set a Custom resolution to align exactly with your CG overscan pipelines.
• Scene Integration: One-click operators to apply the calculated overscan resolution to your Scene render settings and automatically scale the active Camera's sensor width to maintain the exact field of view.
• Preset System: Save and load your favorite configurations directly from the standard Blender panel header.

Extensions version does not support GPU Acceleration, so exporting high-resolution footage takes tens of seconds to several minutes.

How to Use

1. Open the Movie Clip Editor in Blender.
2. Track your footage and solve the camera/lens distortion as usual in the Lens panel.
3. Open the Sidebar (N key) and navigate to the Track tab.
4. Scroll down to the STMap Exporter panel.
5. Set your Overscan preferences and Output path.
6. (Optional) Click Apply to Scene to update your render resolution and camera sensor for CG rendering.
7. Click the large Export Maps button.
8. In your Compositor: Read the exported .exr file and plug it directly into the UV channel of an STMap node.
   • Nuke / Natron Workflow Example: Load the exported Undistort_STMap and connect a Reformat node to crop it back to your original footage resolution while preserving the bounding box (check preserve bounding box and set resize type to none). This step ensures the map functions exactly like an STMap natively generated by Nuke's LensDistortion node.

Parameters

Panel Header

• Presets (☰ Icon): Save and load your tool configurations. (Note: Output paths and custom names are project-specific and are excluded from presets).

Output Settings

• Export Path: Directory to export maps. Leave this empty to automatically save the files in the same directory as your current .blend file.
• Use Custom Name: When enabled, allows you to use a custom prefix string for the exported files instead of the default movie clip name.

Export Contents

• Undistort Map: Exports the STMap used to flatten (undistort) the original live-action plate. (Forward mapping from Distorted to Undistorted).
• Redistort Map: Exports the STMap used to apply lens curvature (redistort) to your straight CG renders so they match the original plate. (Inverse mapping from Undistorted to Distorted).
• Checkerboard Guides: Exports grayscale checkerboard images alongside the STMaps to easily visualize the distortion effect.
• Override Base Res: Allows you to generate STMaps at a custom base resolution instead of the original clip's dimensions. Useful when the footage resolution differs from the rendering and compositing working resolution.

Overscan / BBox

• Mode:

• Auto Expansion: Automatically calculates the bounding box needed to prevent curved image edges from being cropped.

• Custom Resolution: Manually set the overscan size using percentage scale or explicit pixel dimensions (Width/Height) with an aspect ratio lock.

• Reference Values & Copy to Clipboard: Displays the calculated output resolution, the modified camera sensor width, and the target scene camera. Use the Copy (📋) icon to quickly grab these values for use in external software like Nuke.

• Apply to Scene: Applies the expanded overscan resolution to the Scene Render settings and scales the active Camera's Sensor Width proportionally to retain the correct angle of view.

• Restore: Reverts the Scene Render resolution and Camera Sensor Width back to the original values.

Options

Format Settings

• Format: Image format for the exported files. OpenEXR is highly recommended.
• Color Depth (EXR): Choose between 16-bit (Half) or 32-bit (Full) Float. 32-bit Float is strongly recommended to prevent sub-pixel stepping and banding.
• Codec: Compression method for OpenEXR files. ZIP (lossless) is the standard default.
• Remap to [0-1] (BBox): When exporting the Redistort Map, checking this will strictly squeeze the UV values into a 0.0–1.0 range relative to the expanded bounding box. This is necessary if you must use non-floating-point formats (like PNG or TIFF) which clip negative values. For standard EXR workflows in Nuke, leave this OFF to keep the negative UV coordinates intact.

Auto BBox Limits

• Overscan Limit (%): A safety limiter for the Auto mode to prevent out-of-memory errors on extreme distortion curves. Default is 50% of the base resolution.
• Extra Padding (px): Adds an additional, uniform pixel padding margin around the Auto-calculated bounding box.

Future Roadmap: OpenEXR Data and Display Window Support

Currently, to prevent heavily distorted image corners from being cropped, this add-on handles overscan by physically expanding the output resolution (adding padding) of the generated STMaps.

Blender developers are currently working to "Support display window in EXR Writer". Once this feature is officially implemented and accessible via the Python API, this add-on will be updated to utilize OpenEXR's native dataWindow and displayWindow metadata.