star_trail.py - A high-performance Python utility for stacking long-exposure sequences (Sony ARW or standard images) into stunning star trail images using the 'Lighten' blend mode.
- Ground Stabilization: Anchors the landscape to remove wind jitter. Includes Rotational Stabilization (experimental) to handle tilted horizons.
- Star Localization (experimental): Locks onto a celestial anchor to create perfect circular arcs and remove high-frequency shake.
- Time-Aware Smoothing: Uses EXIF timestamps to intelligently smooth motion curves across varying intervals.
- Real-time Monitoring: Watch your trails grow with the
--save-stepsflag. - Automatic Metadata: Copies camera and lens metadata from the source sequence to the final stack.
pip install -r requirements.txt- ExifTool: Required for metadata copy. It should be located in
../lib/exif-tools/exiftool.exe.
Launch the interactive dark-themed desktop app with full drag-and-drop support, real-time live previewing, and visual settings controls:
python gui.py
# or
python star_trail.py --gui- Drag & Drop: Drag image folders directly into the app window.
- Live Preview: Watch the star trail stack build in real time.
- Full Control: Interactively adjust Ground/Star Stabilization, Brightness Boost, Rotation limits, and Video export settings.
python star_trail.py "path/to/frames"python star_trail.py "path/to/frames" --ground-stabilize --save-steps --overwrite| Standard Stacking | Ground Stabilized (Locked) |
|---|---|
 |
 |
python star_trail.py "path/to/frames" --star-stabilize --limit 100Note
This mode is currently experimental and requires clear visibility of the celestial pivot point.
-o,--output <path>: Specific output JPG filename or directory. If omitted or set to a directory, defaults to a file named after the source folder with appropriate suffixes.--limit <int>: Limit the number of frames processed from the input sequence.--overwrite: Automatically overwrite existing output files without prompting.--skip: Automatically skip processing if the output file already exists.--threads <int>: Number of concurrent RAW processing threads (defaults to CPU count).--bright <float>: Apply a brightness boost factor to the frames during processing (default: 1.0).--save-steps: Continuously update and save the output JPG file after processing every frame, allowing real-time progress monitoring.--save-jpg: Save converted JPEG frames from RAW ARW inputs into a separate folder (suffix_jpg).
--ground-stabilize: Remove high-frequency wind jitter by anchoring the landscape using bottom-masked phase correlation and motion smoothing.--star-stabilize: Align frames dynamically by tracking the brightest celestial anchor to ensure perfect circular star trails.--smooth <int>: Set a specific radius (in frames) for Gaussian motion curve smoothing (defaults to 100% of the sequence length).--brightness-limit <value>: Exclude overexposed frames (e.g. headlights, clouds) using a threshold (0.0 to 1.0) orauto(uses standard deviation), ornone/1.0to disable.--max-rotation <float>: Maximum allowed per-frame rotation in degrees for ECC stabilization (default: 5.0). Use0to disable rotation tracking.--motion-width <int>: Downscaled image width used during the motion detection phase to speed up analysis (default: 1500).
--video [trail|no-trail]: Generate an MP4 video of the sequence.trail(default if flag is set) renders the progressive stack growing, whileno-trailoutputs the individual stabilized frames.--fps <int>: Frame rate for the output video (default: 30).--video-width <int>: Maximum width of the output video in pixels (default: 3840 for 4K). Set to0to preserve the original sequence resolution.
The data/ folder typically contains sample sequences or output files when following default naming conventions.