[aider] docs: Add comprehensive README files

README.md

@@ -1,23 +1,70 @@
 # filmsim
 
-This is an exploration into a few things:
- - An LLM based project (I do minimal coding)
- - Film simulation
- - Real life film capture
+`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`.
 
-This project seeks to create a fast, "batteries included", film simulation package that walks the user through a film simulation.
+## Features
 
-Currently we have the following pipeline components:
- - `filmcolor` - Takes in a digital color positive (picture from your digital camera) and outputs a simulated film negative based on the film stock chosen
- - `filmscan` - Simulates the film scan and negative reversal process by referencing the "[Negadoctor](https://github.com/darktable-org/darktable/blob/master/src/iop/negadoctor.c)" module from [Darktable](https://www.darktable.org/), but adding in a few auto features for "batteries included"
- - `filmgrain` - Adds grain based on the filmgrain method by [Zhang et al. (2023)](https://dl.acm.org/doi/10.1145/3592127) in either RGB or monochrome
+*   **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.
 
-All scripts are designed to take in TIFF/PNG/JPG, and output TIFF/PNG/JPG. TIFFs are output in uncompressed 16-bit.
+## Scripts
 
-`filmcolor` can additionally take in Sony ARW and various DNG camera RAW files.
+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.
 
-All scripts are self contained and portable.
+*   **[`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.
 
-Details about each script can be found in their respective readmes.
+## Quick Start with `uv`
 
-This project also contains test input images and outputs at various stages of development.
+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.