Metadata-Version: 2.4
Name: sony-a1-hdrmerge
Version: 0.2.0
Summary: Automated Sony A1 3/5-frame HDR batch pipeline with calibrated deghosting and optional ML denoising
License-Expression: MIT
Project-URL: Homepage, https://github.com/Philipp9D/sony-a1-hdrmerge
Project-URL: Repository, https://github.com/Philipp9D/sony-a1-hdrmerge
Project-URL: Issues, https://github.com/Philipp9D/sony-a1-hdrmerge/issues
Project-URL: Changelog, https://github.com/Philipp9D/sony-a1-hdrmerge/blob/main/CHANGELOG.md
Keywords: hdr,sony,photography,raw,photomatix,heif,denoising
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: PyYAML>=5.4
Requires-Dist: numpy<2.1,>=1.26
Requires-Dist: opencv-python-headless<4.11,>=4.10
Requires-Dist: Pillow<12,>=11
Provides-Extra: ml
Requires-Dist: onnxruntime<2,>=1.19; extra == "ml"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

# Sony A1 HDRMerge

Sony A1 HDRMerge is a conservative Linux command-line pipeline for automatic
3- and 5-frame Sony A1 ARW exposure brackets. One command can detect every
valid stack in a folder, analyze motion, select calibrated deghosting, render a
Balanced HDR through PhotomatixCL, optionally denoise according to ISO, encode
a validated 10-bit HEIC, preserve metadata, and prepare the result for review.

The photographer remains the final quality authority by default. Original ARW
files are never deleted.

## Runtime requirements

The Python package intentionally does not redistribute native or proprietary
software. Install these separately:

- Linux on x86-64 or ARM supported by your PhotomatixCL build
- Python 3.9 or newer and `pipx`
- [PhotomatixCL](https://www.hdrsoft.com/download/photomatixcl.html), installed
  and registered with the user's own license
- ExifTool
- `heif-enc` from libheif, built with an x265 encoder capable of 10-bit HEVC
- Lensfun data for automatic RAW lens correction
- optionally, the reviewed NAFNet ONNX model and ONNX Runtime

PhotomatixCL's free and paid plans are usage-based. The tested free plan also
contacts the license server while rendering. HDRMerge fails instead of silently
falling back to a watermarked output.

## Installation

CPU-capable ML installation from PyPI:

```bash
pipx install 'sony-a1-hdrmerge[ml]'
```

For NVIDIA, install the base application and inject the GPU runtime instead of
the CPU-only ONNX Runtime package:

```bash
pipx install sony-a1-hdrmerge
pipx inject sony-a1-hdrmerge onnxruntime-gpu
```

For development from a checkout:

```bash
pipx install --editable '.[ml]'
```

## One-time setup

Create the per-user configuration with explicit native tool paths. Denoising
can be disabled initially:

```bash
hdrmerge setup \
  --photomatix /opt/PhotomatixCL/PhotomatixCL-static \
  --heif-enc /usr/bin/heif-enc \
  --exiftool /usr/bin/exiftool \
  --no-denoise
```

Or enable the calibrated ML policy with an existing reviewed ONNX model:

```bash
hdrmerge setup \
  --photomatix /opt/PhotomatixCL/PhotomatixCL-static \
  --heif-enc /usr/bin/heif-enc \
  --exiftool /usr/bin/exiftool \
  --denoise-model /data/models/nafnet-sidd-width64.onnx \
  --denoise
```

Then validate everything, including the Photomatix license/server response,
10-bit x265 availability, ONNX model, and selected accelerator:

```bash
hdrmerge doctor
```

`setup` refuses to overwrite an existing configuration unless `--force` is
given. It never stores a Photomatix license key.

Configuration lookup order is:

1. `--config FILE`
2. `HDRMERGE_CONFIG`
3. `config.yaml` in the current directory
4. `${XDG_CONFIG_HOME:-~/.config}/hdrmerge/config.yaml`

Relative paths are resolved against the configuration file.

## Automatic batch processing

The preferred all-in-one command is:

```bash
hdrmerge /path/to/photos
```

It attempts every detected bracket in the folder. A failure in one stack is
reported but does not prevent later stacks from being attempted. Use
`--recursive` to include subdirectories.

Automatic detection validates metadata, exposure spacing and Sony capture
order:

- 3 frames: neutral, underexposed, overexposed
- 5 frames: neutral, underexposed, overexposed, strongly underexposed, strongly
  overexposed

When both interpretations are plausible, the 5-frame interpretation wins.

The current calibrated preset is Photomatix `Balanced`. Motion analysis selects
`g40` as the conservative floor and raises it to `g60` for sufficiently strong
structural residuals or residual-plus-flow displacement. Low-confidence motion
analysis requires a manual `--deghost-strength` instead of guessing.

## Denoising selection

Denoising is configurable both persistently and per batch:

```bash
hdrmerge /path/to/photos --denoise
hdrmerge /path/to/photos --no-denoise
```

When enabled, the highest ISO value in the entire exposure bracket controls the
strength. The calibrated curve is:

| Maximum bracket ISO | Strength |
|---:|---:|
| 100 | off |
| 200 | 0.116 |
| 400 | 0.231 |
| 800 | 0.347 |
| 1600 | 0.463 |
| 2000–4000 | 0.500 |
| 6400 | 0.670 |
| 8000 and above | 0.750 |

Intermediate values are interpolated in `log2(ISO)`. For example,
`[4000, 1250, 10000]` selects ISO 10000 and clamps to `0.75`.

`device: auto` prefers TensorRT/CUDA, ROCm, DirectML, CoreML, or OpenVINO when
available and retains CPU as the final operator fallback.

## Review and publication

The default batch result is a technically validated review candidate and a
manifest below the input folder's `.hdrmerge/` directory. After inspecting the
candidate at 100%, record the decision:

```bash
hdrmerge review /path/to/manifest.json approve --note "accepted"
hdrmerge review /path/to/manifest.json reject --note "ghosting in foliage"
```

Only approval publishes `<reference>_HDR.heic`. Rejection keeps all source and
diagnostic material. Automatic publication is guarded by two explicit settings:

```yaml
quality_review:
  required: false
  allow_automatic_after_calibration: true
```

## Manual stages and overrides

The same processing core is available in smaller commands:

```bash
hdrmerge scan /path/to/photos
hdrmerge motion /path/to/photos
hdrmerge merge /path/to/photos --output-dir /path/to/tiffs
hdrmerge denoise input.tif output.tif --model model.onnx --strength 0.5
hdrmerge encode output.tif output.heic --reference neutral.ARW
hdrmerge review manifest.json approve
```

Useful all-in-one overrides include:

```bash
hdrmerge /path/to/photos --stack-size 5
hdrmerge /path/to/photos --deghost-strength 60
hdrmerge /path/to/photos --denoise-strength 0.5
hdrmerge /path/to/photos --variant calibration-g60
```

Legacy entry points `hdr`, `hdr3`, `hdr5`, `hdr-review`, and `hdr-denoise` remain
available for compatibility.

## Safety guarantees

- ARW source files have no deletion path.
- Existing output or job state is never silently overwritten.
- Ambiguous and incomplete brackets remain untouched.
- Cleanup occurs only after successful processing and the configured review
  decision.
- Camera JPEG/HEIF companions qualify for cleanup only when stem, camera model,
  and capture time match a source RAW.
- An output that is not 10-bit HEVC with sRGB/BT.709 signaling fails validation.
- Every candidate manifest records source file statistics, settings, motion
  metrics, denoising model hash/provider/runtime, output hash, and status.

## Development

Run the test suite:

```bash
python -m unittest discover -v
```

Build release artifacts:

```bash
python -m build
twine check dist/*
```

The package is MIT licensed. PhotomatixCL, ExifTool, libheif/x265, ONNX Runtime,
OpenCV, NAFNet, and model weights retain their own licenses and are not part of
the Python distribution. See `THIRD_PARTY_NOTICES.md`.

Sony, Alpha, Photomatix, and other product names are trademarks of their
respective owners. This project is not affiliated with Sony or HDRsoft.
