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: Transforms digital color positives into simulated film negatives based on chosen film stock data.
filmscan: Simulates the film scanning process and reverses negatives to positives, inspired by Darktable's "Negadoctor" module with added auto-adjustment capabilities.
filmgrain: 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.

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

Example (adding grain to an image):

# 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:

Clone the repository (optional):

git clone https://git.dws.rip/dubey/filmsim.git
cd filmsim

Ensure uv is installed. (Installation Guide)

Run the script: Navigate to the directory containing the script (if cloned) or use the path to the script.

uv run ./{SCRIPT_NAME} -- {ARGUMENTS}

Or, if not cloned, you can download the script and run it:

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.

3.4 KiB Raw Blame History