filmsim

Beware, this repo is currently a total mess. Versions of scripts everywhere, image names that make no sense, the lot.

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:

1. Clone the repository (optional):

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

2. Ensure uv is installed. (Installation Guide)
3. 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.