71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 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.
|