# `filmcolor` - Film Stock Color Emulation

`filmcolor` is a Python script that transforms digital color positive images (like those from a digital camera) into simulated film negatives. It bases its transformations on datasheet parameters for specific film stocks, focusing on color response, H&D curves, spatial effects like halation and diffusion, and saturation.

## Features

*   Applies film stock characteristics based on a JSON datasheet.
*   Converts linear RGB input to log exposure.
*   Applies H&D (Hurter–Driffield) curves for tonal mapping.
*   Simulates dye coupler diffusion and interlayer effects.
*   Applies halation effects.
*   Adjusts saturation based on coupler properties.
*   Supports RAW (Sony ARW, DNG), 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 `filmcolor` directly from its Git repository URL:

```bash
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/filmcolor -- <input_image> <datasheet_json> <output_image>
```

**Example:**

```bash
# Ensure input.jpg and sim_data/portra_400.json are in your current directory or provide full paths
# Output will be output_negative.tiff
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/filmcolor -- input.jpg sim_data/portra_400.json output_negative.tiff
```

### 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 ./filmcolor -- <input_image> <datasheet_json> <output_image>
    ```

    Or, if `filmcolor` is in the current directory and executable:
    ```bash
    ./filmcolor <input_image> <datasheet_json> <output_image>
    ```


## Arguments

### Positional Arguments:

*   `input_image`: Path to the input RGB image.
    *   Supported formats: TIFF, PNG, JPG, Sony ARW, DNG.
    *   Non-RAW images are assumed to be sRGB and will be linearized. RAW files are processed to sRGB.
*   `datasheet_json`: Path to the film datasheet JSON file (e.g., `sim_data/portra_400.json`).
*   `output_image`: Path to save the output emulated film negative.
    *   Output format is determined by the file extension:
        *   `.tiff` / `.tif`: 16-bit uncompressed TIFF.
        *   `.png`: 8-bit PNG.
        *   `.jpg` / `.jpeg`: 8-bit JPG (quality 95).

### Options:

The script currently does not have additional command-line options beyond the positional arguments. Configuration is primarily driven by the content of the `datasheet_json` file.

## Input Image Preparation

*   **Linear RGB:** The script internally works with linear RGB data.
    *   If an 8-bit or 16-bit integer image (PNG, JPG, TIFF) is provided, it's assumed to be sRGB encoded and will be automatically linearized.
    *   If a float32/float64 image is provided, it's assumed to be already in linear RGB.
    *   RAW files (ARW, DNG) are demosaiced, white-balanced (using camera WB), and converted to linear sRGB.
*   **Alpha Channel:** If an alpha channel is present, it will be discarded.

## Datasheet Format

The `datasheet_json` file contains detailed parameters for the film stock being simulated. This includes:
*   Information (name, format, version)
*   Processing parameters (gamma, balance)
*   Physical properties (halation strength and size, coupler diffusion, interlayer diffusion)
*   H&D curves
*   Calibration data (ISO, middle gray log exposure)

An example datasheet (`sim_data/portra_400.json`) is provided in the repository.

## Workflow

1.  **Load Image:** Reads the input image. RAW files are processed using `rawpy`. sRGB images are linearized.
2.  **Load Datasheet:** Parses the specified JSON film datasheet.
3.  **Convert to Log Exposure:** Transforms linear RGB pixel values to log exposure (LogE) space, anchored by the `middle_gray_logE` from the datasheet.
4.  **Apply H&D Curves:** Maps LogE values to densities for each color channel (R, G, B) using the H&D curves from the datasheet. This step also incorporates processing gamma and balance shifts.
5.  **Convert Density to Transmittance:** Converts the resulting densities back to linear transmittance values (0-1 range).
6.  **Apply Spatial Effects:**
    *   **Diffusion Blur:** Simulates dye coupler and interlayer diffusion by applying a Gaussian blur. The blur radius is derived from `diffusion_um` values in the datasheet and the image dimensions/film format.
    *   **Halation:** Simulates light scattering within the film base by applying channel-specific Gaussian blurs, controlled by `halation.strength` and `halation.size_um`.
7.  **Apply Saturation:** Adjusts image saturation based on the `couplers.amount` parameter.
8.  **Save Output:** The processed image (now a simulated film negative) is saved to the specified output file, converting to 16-bit for TIFF or 8-bit for PNG/JPG.