# filmsim

`filmsim` is a collection of Python scripts designed for film simulation, offering a "batteries included" approach to transform digital images through various stages of a film-like pipeline. The project emphasizes ease of use, portability, and direct execution via `uv`.

## Features

*   **Modular Pipeline:** Consists of distinct scripts for different stages of film simulation:
    *   `filmcolor`: Simulates the color response of film stocks.
    *   `filmscan`: Emulates the film scanning and negative reversal process.
    *   `filmgrain`: Adds realistic film grain to images.
*   **"Batteries Included":** Scripts aim to provide sensible defaults and auto-detection features where possible.
*   **Portable & Self-Contained:** Each script includes its dependencies and can be run directly.
*   **Direct Execution with `uv`:** Run any script remotely without cloning the repository using `uv run`.
*   **Flexible I/O:** Supports common image formats like TIFF, PNG, and JPG. `filmcolor` also handles Sony ARW and DNG RAW files. TIFFs are output in uncompressed 16-bit by default.

## Scripts

Each script in the `filmsim` suite is designed to be a self-contained tool. Click the links below for detailed information on each script, including its specific parameters and usage examples.

*   **[`filmcolor`](README-filmcolor.md):** Transforms digital color positives into simulated film negatives based on chosen film stock data.
*   **[`filmscan`](README-filmscan.md):** Simulates the film scanning process and reverses negatives to positives, inspired by Darktable's "Negadoctor" module with added auto-adjustment capabilities.
*   **[`filmgrain`](README-filmgrain.md):** Applies film grain to images using the method described by Zhang et al. (2023), with options for RGB or monochrome grain.

## Quick Start with `uv`

You can run any of these scripts directly from the web using `uv`. This is the recommended way to use `filmsim` if you don't need to modify the code.

Replace `{SCRIPT_NAME}` with `filmcolor`, `filmscan`, or `filmgrain`, and `{ARGUMENTS}` with the script-specific arguments.

```bash
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/{SCRIPT_NAME} -- {ARGUMENTS}
```

**Example (adding grain to an image):**

```bash
# Ensure you have an input.jpg in your current directory
# Output will be output_grained.jpg
uv run https://git.dws.rip/dubey/filmsim/raw/branch/main/filmgrain -- input.jpg output_grained.jpg --mu_r 0.15 --sigma 1.0
```

## Local Usage

If you prefer to run the scripts locally:

1.  **Clone the repository (optional):**
    ```bash
    git clone https://git.dws.rip/dubey/filmsim.git
    cd filmsim
    ```
2.  **Ensure `uv` is installed.** ([Installation Guide](https://github.com/astral-sh/uv))
3.  **Run the script:**
    Navigate to the directory containing the script (if cloned) or use the path to the script.
    ```bash
    uv run ./{SCRIPT_NAME} -- {ARGUMENTS}
    ```
    Or, if not cloned, you can download the script and run it:
    ```bash
    curl -O https://git.dws.rip/dubey/filmsim/raw/branch/main/{SCRIPT_NAME}
    chmod +x {SCRIPT_NAME}
    uv run ./{SCRIPT_NAME} -- {ARGUMENTS}
    ```

## Contributing

This project is an exploration and contributions or suggestions are welcome. Please feel free to open an issue or a pull request.

## Test Images

The repository includes test input images and sample outputs at various stages of development in the `test_images/` directory.