dubey/filmsim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[aider] docs: Add comprehensive README files

Browse Source
This commit is contained in:
Tanishq Dubey
2025-06-05 21:19:09 -04:00
committed by Tanishq Dubey
parent 0a93e9c664
commit d59bd215d8
5 changed files with 390 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
README-filmscan.md Normal file
View File

@ -0,0 +1,111 @@
# `filmscan` - Film Scan and Negative Reversal Simulation
`filmscan` is a Python script that simulates the process of scanning a film negative and converting it into a positive image. It is heavily inspired by the "Negadoctor" module found in the popular open-source raw image processor, Darktable. This script aims to provide a "batteries included" experience by auto-detecting several key parameters required for the conversion.
## Features
* Implements a negative-to-positive conversion process similar to Darktable's Negadoctor.
* **Automatic Parameter Detection:**
* `Dmin` (film base color / brightest part of the negative)
* `Dmax` (determines the dynamic range, from darkest part of the negative)
* `Offset` (scan exposure bias)
* `Paper Black` (density correction for print black point)
* `Print Exposure` (overall print exposure adjustment)
* Color management: Converts input sRGB (assumed) to ACEScg for processing, then back to a chosen output colorspace (sRGB or Display P3).
* Supports TIFF, PNG, and JPG inputs.
* Outputs TIFF (16-bit uncompressed), PNG (8-bit), or JPG (8-bit).
## Usage
The script is designed to be run with `uv`, which handles dependency management.
### Direct Execution with `uv` (Recommended)
You can run `filmscan` directly from its Git repository URL:
```bash
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/filmscan -- <input_file> <output_file> [options]
```
**Example:**
```bash
# Ensure input_negative.tiff is in your current directory or provide a full path
# Output will be output_positive.jpg
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/filmscan -- input_negative.tiff output_positive.jpg --output_colorspace sRGB
```
### Local Execution
If you have cloned the repository or downloaded the script:
1. Navigate to the script's directory or ensure it's in your PATH.
2. Run the script:
```bash
uv run ./filmscan -- <input_file> <output_file> [options]
```
Or, if `filmscan` is in the current directory and executable:
```bash
./filmscan <input_file> <output_file> [options]
```
## Arguments
### Positional Arguments:
* `input_file`: Path to the input negative image.
* Supported formats: TIFF, PNG, JPG.
* The image is assumed to be an sRGB encoded film negative scan.
* `output_file`: Path to save the processed positive image.
* Output format is determined by the file extension:
* `.tiff` / `.tif`: 16-bit uncompressed TIFF.
* `.png`: 8-bit PNG.
* `.jpg` / `.jpeg`: 8-bit JPG.
### Options:
* `--patch_size_ratio FLOAT`: Ratio of image minimum dimension for patch size in auto-detection. (Default: `1/128`)
* Smaller values use smaller patches, which can be faster but potentially more susceptible to noise.
* `--min_patch_size INT`: Minimum patch size in pixels for auto-detection. (Default: `8`)
* `--max_patch_size INT`: Maximum patch size in pixels for auto-detection. (Default: `32`)
* `--aces_transform TEXT`: ACES working space. Currently, ACEScg is used internally and this option is noted for future flexibility but does not change behavior. (Default: `ACEScg`)
* `--output_colorspace TEXT`: Colorspace for the output image.
* Supported: `sRGB` (default), `Display P3`.
* The output image will be gamma-corrected for the chosen colorspace.
## Workflow
1. **Load Image:** Reads the input negative image. It's normalized to a 0-1 float range.
2. **Color Conversion (Input):**
* The input image (assumed sRGB) is decoded from its gamma (e.g., sRGB EOTF inverse).
* The linear sRGB data is then converted to the ACEScg color space for internal processing.
3. **Auto-Parameter Detection:**
* The script analyzes the ACEScg image to automatically determine optimal values for:
* `Dmin`: The color of the unexposed film base, found by looking for the brightest representative patch in the negative.
* `Dmax`: A measure of the film's maximum density range, calculated using `Dmin` and the darkest representative patch in the negative (scene highlight).
* `Offset`: A scan exposure bias, determined from `Dmin`, `Dmax`, and the brightest image content patch.
* `Paper Black`: Adjusts the black point of the final print, derived from `Dmin`, `Dmax`, `Offset`, and characteristics of the brightest image patch under default white balance.
* `Print Exposure`: Overall brightness adjustment for the final print, calculated using all previously determined parameters and the darkest image patch.
* Default white balance (`WB_HIGH`, `WB_LOW`), gamma (`DEFAULT_GAMMA`), and soft clip (`DEFAULT_SOFT_CLIP`) values are used alongside these auto-detected parameters.
4. **Negadoctor Process:**
* The core conversion logic, adapted from Darktable's `negadoctor.c`.
* **Density Conversion:** Input pixel values are converted to log densities relative to `Dmin`.
* **Density Correction:** Densities are adjusted using `Dmax`, `Offset`, and white balance parameters.
* **Print Simulation:** Corrected densities are transformed to simulate printing on paper, incorporating `Print Exposure` and `Paper Black`.
* **Paper Grade (Gamma):** A gamma curve (contrast adjustment) is applied.
* **Highlight Compression (Soft Clip):** Highlights are compressed to simulate the behavior of photographic paper gloss.
5. **Color Conversion (Output):**
* The processed image (now a positive in ACEScg) is converted to the chosen `output_colorspace` (e.g., sRGB, Display P3).
* The image is clipped to the 0-1 range.
* The appropriate gamma correction (e.g., sRGB OETF) is applied for the output colorspace.
6. **Save Output:** The final positive image is saved, converting to 16-bit for TIFF or 8-bit for PNG/JPG.
## Notes on Auto-Detection
The auto-detection routines (`auto_calculate_dmin`, `auto_calculate_dmax`, etc.) work by finding representative "brightest" or "darkest" patches in the negative image.
* "Brightest" on a negative typically corresponds to the film base (for `Dmin`) or unexposed areas that will become deep shadows in the positive.
* "Darkest" on a negative typically corresponds to scene highlights that will become bright areas in the positive.
The `patch_size_ratio`, `min_patch_size`, and `max_patch_size` arguments control how these patches are sampled.