diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..007d089e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,83 @@ +# Documentation build and deployment workflow +# Builds documentation using Doxygen + Sphinx + Breathe +# Deploys to GitHub Pages on pushes to main branch + +name: Documentation + +on: + push: + branches: [ "main" ] + paths: + - 'docs/**' + - 'include/**' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/**' + - 'include/**' + - '.github/workflows/docs.yml' + # Allow manual trigger + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build-docs: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install -y doxygen + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + + - name: Build Doxygen XML + working-directory: docs + run: doxygen Doxyfile + + - name: Build Sphinx HTML + working-directory: docs + run: | + sphinx-build -b html -D breathe_projects.rawtoaces=doxygen/xml . _build/html + + - name: Upload artifact for GitHub Pages + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy-docs: + # Only deploy on push to main + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build-docs + runs-on: ubuntu-latest + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index d7a1b6d6..97643137 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,9 @@ build/ build-coverage/ tests/materials/*.exr -__pycache__/ \ No newline at end of file +__pycache__/ + +# Documentation build artifacts +docs/_build/ +docs/doxygen/ +docs/html/ \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..a8b4601b --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# Read the Docs configuration file for RAWtoACES +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +# Set the OS, Python version, and other tools +build: + os: ubuntu-22.04 + tools: + python: "3.11" + apt_packages: + - doxygen + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + fail_on_warning: false + +# Python requirements for documentation +python: + install: + - requirements: docs/requirements.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index 9e2c50fc..ead5d937 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -105,6 +105,12 @@ endif ( RTA_BUILD_PYTHON_BINDINGS ) enable_testing() add_subdirectory(tests) +# Documentation (optional) +option( BUILD_DOCS "Build documentation" OFF ) +if( BUILD_DOCS ) + add_subdirectory(docs) +endif() + ################################################# ## ## Install RAWTOACES.pc diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 00000000..6633e644 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,63 @@ +# Documentation build configuration for RAWtoACES +# +# This file provides CMake targets for building documentation locally. +# For Read the Docs builds, the documentation is built directly using +# Sphinx and Doxygen without CMake. + +find_package(Doxygen) +find_program(SPHINX_EXECUTABLE sphinx-build) + +if(DOXYGEN_FOUND AND SPHINX_EXECUTABLE) + message(STATUS "Documentation tools found - enabling 'docs' target") + + # Configure Doxyfile with project paths + configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + @ONLY + ) + + # Doxygen target - generates XML for Breathe + add_custom_target(doxygen + COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + COMMENT "Generating API documentation with Doxygen" + VERBATIM + ) + + # Sphinx target - generates HTML documentation + add_custom_target(sphinx + COMMAND ${SPHINX_EXECUTABLE} + -b html + -c ${CMAKE_CURRENT_SOURCE_DIR} + -D breathe_projects.rawtoaces=${CMAKE_BINARY_DIR}/docs/doxygen/xml + ${CMAKE_CURRENT_SOURCE_DIR} + ${CMAKE_CURRENT_BINARY_DIR}/html + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + COMMENT "Generating HTML documentation with Sphinx" + DEPENDS doxygen + VERBATIM + ) + + # Main docs target + add_custom_target(docs + DEPENDS sphinx + COMMENT "Building documentation" + ) + + # Install documentation + install( + DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ + DESTINATION share/doc/rawtoaces + OPTIONAL + COMPONENT documentation + ) + +else() + if(NOT DOXYGEN_FOUND) + message(STATUS "Doxygen not found - documentation target disabled") + endif() + if(NOT SPHINX_EXECUTABLE) + message(STATUS "Sphinx not found - documentation target disabled") + endif() +endif() diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..1c33e613 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,65 @@ +# Doxyfile for RAWtoACES - standalone version for ReadTheDocs +# This file is used when building documentation without CMake + +# Project information +PROJECT_NAME = "RAWtoACES" +PROJECT_NUMBER = "2.0.0" +PROJECT_BRIEF = "RAW to ACES Utility" +PROJECT_LOGO = + +# Input/Output +INPUT = ../include/rawtoaces +OUTPUT_DIRECTORY = doxygen +RECURSIVE = YES +FILE_PATTERNS = *.h *.hpp + +# What to extract +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES + +# XML output for Breathe +GENERATE_XML = YES +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES + +# Disable other outputs (Sphinx/Breathe will handle HTML) +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO + +# Preprocessing +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +PREDEFINED = + +# Source browsing +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES + +# Warnings +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES + +# Graphs (disabled for faster builds) +HAVE_DOT = NO +CLASS_DIAGRAMS = NO + +# Sorting +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = YES +SORT_MEMBERS_CTORS_1ST = YES + +# Namespaces +HIDE_UNDOC_RELATIONS = NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in new file mode 100644 index 00000000..4ba4c5f2 --- /dev/null +++ b/docs/Doxyfile.in @@ -0,0 +1,65 @@ +# Doxyfile for RAWtoACES +# This file is configured by CMake to set project-specific paths + +# Project information +PROJECT_NAME = "RAWtoACES" +PROJECT_NUMBER = @RAWTOACES_VERSION@ +PROJECT_BRIEF = "RAW to ACES Utility" +PROJECT_LOGO = + +# Input/Output +INPUT = @CMAKE_SOURCE_DIR@/include/rawtoaces +OUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/docs/doxygen +RECURSIVE = YES +FILE_PATTERNS = *.h *.hpp + +# What to extract +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES + +# XML output for Breathe +GENERATE_XML = YES +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES + +# Disable other outputs (Sphinx/Breathe will handle HTML) +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO + +# Preprocessing +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +PREDEFINED = + +# Source browsing +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES + +# Warnings +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES + +# Graphs (disabled for faster builds, enable if needed) +HAVE_DOT = NO +CLASS_DIAGRAMS = NO + +# Sorting +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = YES +SORT_MEMBERS_CTORS_1ST = YES + +# Namespaces +HIDE_UNDOC_RELATIONS = NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..d0f9e073 --- /dev/null +++ b/docs/_static/.gitkeep @@ -0,0 +1 @@ +# This file ensures the _static directory is tracked by git diff --git a/docs/api/image_converter.rst b/docs/api/image_converter.rst new file mode 100644 index 00000000..4bdb5b0b --- /dev/null +++ b/docs/api/image_converter.rst @@ -0,0 +1,69 @@ +ImageConverter +============== + +The ``ImageConverter`` class is the main interface for converting RAW images to ACES format. +It provides a high-level API that handles the entire conversion pipeline. + +.. contents:: Contents + :local: + :depth: 2 + +Overview +-------- + +The ``ImageConverter`` class encapsulates the complete RAW-to-ACES conversion workflow: + +1. Configure white balance and color matrix methods +2. Load the RAW image +3. Apply color transformations +4. Apply scaling and cropping +5. Save the ACES EXR output + +Basic Usage +----------- + +.. code-block:: cpp + + #include + + rta::util::ImageConverter converter; + + // Configure settings + converter.settings.WB_method = rta::util::ImageConverter::Settings::WBMethod::Metadata; + converter.settings.matrix_method = rta::util::ImageConverter::Settings::MatrixMethod::Auto; + converter.settings.overwrite = true; + + // Process an image + bool success = converter.process_image("input.dng"); + +Class Reference +--------------- + +ImageConverter Class +^^^^^^^^^^^^^^^^^^^^ + +.. doxygenclass:: rta::util::ImageConverter + :members: + :protected-members: + :undoc-members: + +Settings Structure +^^^^^^^^^^^^^^^^^^ + +.. doxygenstruct:: rta::util::ImageConverter::Settings + :members: + :undoc-members: + +Enumerations +^^^^^^^^^^^^ + +.. doxygenenum:: rta::util::ImageConverter::Settings::WBMethod + +.. doxygenenum:: rta::util::ImageConverter::Settings::MatrixMethod + +.. doxygenenum:: rta::util::ImageConverter::Settings::CropMode + +Utility Functions +----------------- + +.. doxygenfunction:: rta::util::collect_image_files diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..f09f83fd --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,25 @@ +API Reference +============= + +This section contains the API documentation for the RAWtoACES C++ libraries, +automatically generated from the source code using Doxygen and Breathe. + +.. toctree:: + :maxdepth: 2 + + image_converter + rawtoaces_core + spectral_data + +Namespaces +---------- + +RAWtoACES organizes its code into the following namespaces: + +``rta::util`` + The utility library containing the high-level :cpp:class:`ImageConverter` class + for easy RAW-to-ACES conversion. + +``rta::core`` + The core library containing lower-level functionality for spectral calculations, + color science, and data management. diff --git a/docs/api/rawtoaces_core.rst b/docs/api/rawtoaces_core.rst new file mode 100644 index 00000000..1d3b5f70 --- /dev/null +++ b/docs/api/rawtoaces_core.rst @@ -0,0 +1,48 @@ +RAWtoACES Core +============== + +The core library provides low-level functionality for spectral calculations, +color science operations, and data management. + +.. contents:: Contents + :local: + :depth: 2 + +Overview +-------- + +The core library (``rawtoaces_core``) contains: + +- Spectral solver for calculating IDT matrices from camera spectral sensitivities +- Database management for camera data, illuminants, and training spectra +- Color science utilities + +SpectralSolver Class +-------------------- + +.. doxygenclass:: rta::core::SpectralSolver + :members: + :protected-members: + :undoc-members: + +Database Classes +---------------- + +CameraDatabase +^^^^^^^^^^^^^^ + +.. doxygenclass:: rta::core::CameraDatabase + :members: + :undoc-members: + +IlluminantDatabase +^^^^^^^^^^^^^^^^^^ + +.. doxygenclass:: rta::core::IlluminantDatabase + :members: + :undoc-members: + +Utility Functions +----------------- + +.. doxygenfunction:: rta::core::database_paths diff --git a/docs/api/spectral_data.rst b/docs/api/spectral_data.rst new file mode 100644 index 00000000..3a025e7a --- /dev/null +++ b/docs/api/spectral_data.rst @@ -0,0 +1,24 @@ +Spectral Data +============= + +Data structures for handling spectral information used in color transformations. + +.. contents:: Contents + :local: + :depth: 2 + +Overview +-------- + +The spectral data module provides structures for representing: + +- Camera spectral sensitivity curves +- Illuminant spectral power distributions +- Color matching functions (CMFs) +- Training spectral data + +Data Structures +--------------- + +.. doxygenfile:: spectral_data.h + :sections: briefdescription detaileddescription innerclass innernamespace typedef enum func var define diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..a9db00bd --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,95 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import subprocess +import os + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'RAWtoACES' +copyright = '2024, Contributors to the rawtoaces Project' +author = 'Contributors to the rawtoaces Project' + +# The version info for the project +version = '2.0' +release = '2.0.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'breathe', + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', + 'sphinx_rtd_theme', + 'myst_parser', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The suffix(es) of source filenames. +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +# The master toctree document. +master_doc = 'index' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] + +html_theme_options = { + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False, +} + +# -- Breathe configuration --------------------------------------------------- +# https://breathe.readthedocs.io/en/latest/ + +# Check if we're building on Read the Docs +read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' + +# Path to Doxygen XML output +# When building locally with CMake, this will be in the build directory +# When building on RTD, we run Doxygen from conf.py +if read_the_docs_build: + # Run Doxygen when building on Read the Docs + subprocess.call('cd .. && doxygen docs/Doxyfile', shell=True) + breathe_projects = {'rawtoaces': '../doxygen/xml'} +else: + # Local build - assume CMake has run Doxygen + breathe_projects = {'rawtoaces': '_build/doxygen/xml'} + +breathe_default_project = 'rawtoaces' +breathe_default_members = ('members', 'undoc-members') + +# -- Intersphinx configuration ----------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), +} + +# -- MyST Parser configuration ----------------------------------------------- +# https://myst-parser.readthedocs.io/en/latest/ + +myst_enable_extensions = [ + 'colon_fence', + 'deflist', +] diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..02eec1ac --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,12 @@ +Contributing +============ + +We welcome contributions to RAWtoACES! This page provides guidelines for contributing +to the project. + +For detailed contribution guidelines, please see the +`CONTRIBUTING.md `_ +file in the repository. + +.. include:: CONTRIBUTING.md + :parser: myst_parser.sphinx_ diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 00000000..f8d79c65 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,68 @@ +Getting Started +=============== + +Installation +------------ + +From Source +^^^^^^^^^^^ + +RAWtoACES requires the following dependencies: + +- CMake 3.12 or later +- C++17 compatible compiler +- OpenImageIO +- LibRaw +- Ceres Solver +- Eigen3 + +Build steps: + +.. code-block:: bash + + git clone https://github.com/AcademySoftwareFoundation/rawtoaces.git + cd rawtoaces + mkdir build && cd build + cmake .. + make + make install + +Python Bindings +^^^^^^^^^^^^^^^ + +If you want to use the Python bindings, ensure Python development headers are installed +and enable the bindings during configuration: + +.. code-block:: bash + + cmake -DRTA_BUILD_PYTHON_BINDINGS=ON .. + +Environment Setup +----------------- + +RAWtoACES needs access to camera spectral sensitivity data and other reference data. +The data is automatically fetched during the build process and installed to +``share/rawtoaces/data``. + +You can override the data location using environment variables: + +- ``RAWTOACES_DATA_PATH``: Primary path to search for data files +- ``AMPAS_DATA_PATH``: Alternative path (for compatibility) + +Basic Usage +----------- + +The simplest way to convert a RAW file: + +.. code-block:: bash + + rawtoaces input.dng + +This will: + +1. Read the RAW file +2. Apply white balance using metadata from the file +3. Calculate the color transformation matrix (using spectral data if available) +4. Write an ACES-compliant EXR file + +For more options, see the :doc:`user_guide`. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..ac245044 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,73 @@ +RAWtoACES Documentation +======================= + +RAWtoACES is a tool for converting RAW camera images to ACES (Academy Color Encoding System) format. +It provides both a command-line utility and C++/Python libraries for integration into other applications. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + getting_started + user_guide + api/index + contributing + +Features +-------- + +- Convert RAW images from various camera manufacturers to ACES EXR files +- Multiple white balance methods: metadata, illuminant, box averaging, or custom +- Multiple matrix methods: spectral (using camera sensitivity data), metadata, Adobe, or custom +- Flexible cropping options +- Python bindings for scripting and integration +- Batch processing support + +Quick Start +----------- + +Command Line +^^^^^^^^^^^^ + +.. code-block:: bash + + # Basic conversion using camera metadata + rawtoaces input.dng + + # Convert with specific illuminant + rawtoaces --wb-method illuminant --illuminant D55 input.cr2 + + # Batch convert all files in a directory + rawtoaces /path/to/raw/files/ + +Library Usage (C++) +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cpp + + #include + + rta::util::ImageConverter converter; + converter.settings.WB_method = rta::util::ImageConverter::Settings::WBMethod::Metadata; + converter.settings.matrix_method = rta::util::ImageConverter::Settings::MatrixMethod::Auto; + + bool success = converter.process_image("input.dng"); + +Library Usage (Python) +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + import rawtoaces + + converter = rawtoaces.ImageConverter() + converter.settings.WB_method = rawtoaces.WBMethod.Metadata + converter.settings.matrix_method = rawtoaces.MatrixMethod.Auto + + success = converter.process_image("input.dng") + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..2d07aa6d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +# Documentation build requirements for RAWtoACES +# Used by Read the Docs and local documentation builds + +sphinx>=7.0 +sphinx-rtd-theme>=2.0 +breathe>=4.35 +myst-parser>=2.0 diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 00000000..529b2131 --- /dev/null +++ b/docs/user_guide.rst @@ -0,0 +1,126 @@ +User Guide +========== + +Command Line Interface +---------------------- + +The ``rawtoaces`` command-line tool provides a comprehensive interface for converting +RAW images to ACES format. + +Basic Syntax +^^^^^^^^^^^^ + +.. code-block:: bash + + rawtoaces [options] + +White Balance Options +^^^^^^^^^^^^^^^^^^^^^ + +``--wb-method `` + Specify the white balance method: + + - ``metadata`` (default): Use white balance from file metadata + - ``illuminant``: White balance to a specific illuminant + - ``box``: Calculate white balance from a region of the image + - ``custom``: Use custom white balance multipliers + +``--illuminant `` + Specify the illuminant for white balancing. Can be: + + - A color temperature (e.g., ``3200K``, ``5600K``) + - A D-series illuminant (e.g., ``D50``, ``D55``, ``D65``) + - Any illuminant name present in the data folder + +``--wb-box `` + Define a region for box white balance calculation. + +``--custom-wb `` + Provide custom white balance multipliers. + +Matrix Options +^^^^^^^^^^^^^^ + +``--mat-method `` + Specify the color matrix method: + + - ``auto`` (default): Use spectral if available, otherwise metadata + - ``spectral``: Use camera spectral sensitivity curves + - ``metadata``: Use matrix from file metadata (DNG) + - ``adobe``: Use Adobe color matrix from LibRaw + - ``custom``: Use a custom 3x3 matrix + +``--custom-matrix `` + Provide a custom 3x3 color transformation matrix. + +Output Options +^^^^^^^^^^^^^^ + +``--output-dir `` + Specify output directory for converted files. + +``--overwrite`` + Allow overwriting existing output files. + +``--create-dirs`` + Create output directories if they don't exist. + +``--headroom `` + Set the highlight headroom (default: 6.0 stops). + +Cropping Options +^^^^^^^^^^^^^^^^ + +``--crop `` + Specify cropping mode: + + - ``off``: Write full sensor area + - ``soft``: Full sensor area with crop marked as display window + - ``hard`` (default): Write only the crop area + +Camera Override Options +^^^^^^^^^^^^^^^^^^^^^^^ + +``--custom-camera-make `` + Override camera manufacturer name. + +``--custom-camera-model `` + Override camera model name. + +These options are useful when metadata is missing or incorrect. + +Verbosity Options +^^^^^^^^^^^^^^^^^ + +``--verbose`` or ``-v`` + Enable verbose output. + +``--timing`` + Show timing information for each processing step. + +Examples +-------- + +Convert a single file with default settings: + +.. code-block:: bash + + rawtoaces photo.dng + +Convert using a specific illuminant: + +.. code-block:: bash + + rawtoaces --wb-method illuminant --illuminant D55 photo.cr2 + +Batch convert a directory: + +.. code-block:: bash + + rawtoaces --output-dir ./converted --overwrite /path/to/raw/files/ + +Use custom white balance: + +.. code-block:: bash + + rawtoaces --wb-method custom --custom-wb 2.1,1.0,1.5,1.0 photo.nef