DOCSEARCHbyAlgolia
Submit Docs

lutgen-rs

repository·main·Indexed 20 days ago

https://github.com/ozwaldorf/lutgen-rs

A high-performance utility for generating interpolated 3D Lookup Tables (LUTs) based on arbitrary or popular color palettes. It includes the lutgen-cli for generating, extracting, and applying LUTs to images and text files, as well as Lutgen Studio for visual tooling. The project provides the lutgen Rust library for programmatic access and the lutgen-palettes crate for common desktop colorschemes like Catppuccin, Gruvbox, and Nord.

Tokens
17.8K
Snippets
62
Records
90
Agent score
68%

What's inside lutgen-rs

  1. Overview of lutgen CLI commands

    main

    The lutgen CLI is a utility for generating and applying interpolated Look-Up Tables (LUTs) using various color palettes.

    Available commands:

    • generate (g): Generate and save a Hald CLUT to disk.
    • extract (e): Extract colors from existing image(s) and generate a LUT.
    • apply (a): Apply a generated or provided Hald CLUT to images.
    • patch (p): Generate a patch for colors inside text files.
    • palette (P): Print palette names and colors.

    Supported image formats: avif, bmp, dds, exr, ff, gif, hdr, ico, jpg, jpeg, png, pnm, qoi, tga, tiff, webp.

    lutgen generate ...
lutgen extract ...
lutgen apply ...
lutgen patch ...
lutgen palette ...

  2. What is lutgen used for?

    main

    Lutgen is a tool designed for:

    • Desktop Theming: Color grading wallpapers to match specific color palettes used in desktop and application themes.
    • Generic LUT Generation: Creating lookup tables for graphic design.
    • Image Editing: Generating LUTs compatible with image editors that support Hald Cluts.
    • CSS Patching: A patch mode that works on text files containing CSS-styled colors.

  3. Access Lutgen documentation and resources

    main

    The Lutgen wiki provides several specialized guides for different ways of interacting with the project:

    • CLI Documentation: Detailed information for every subcommand available in the lutgen-cli.
    • Examples: Practical usage scenarios and example commands.
    • Lore: Deep dives into the program's history, underlying algorithms, and technical details.
    • Lutgen Studio: Help and documentation for the official GUI application.
    • Tips: Best practices and tricks for optimizing Lutgen outputs.

  5. How does lutgen work?

    main

    Lutgen operates by creating a Hald-Clut lookup-table and applying it to a given image to perform color grading.

    It supports three primary modes of operation:

    1. Color Grading: Applying a generated LUT to an image.
    2. LUT Generation: Generating standalone lookup tables for use in external software.
    3. Patch Mode: Working on text files containing CSS-styled colors.

  6. Understand the LUT generation algorithms

    main

    Lutgen uses different mathematical approaches to generate LUTs, with Gaussian RBF being the current default due to its balance of speed and visual quality.

    Algorithms

    • Gaussian RBF (Default): The current high-performance algorithm. It uses Radial-Basis-Function interpolation with a Gaussian function. It is extremely fast and produces results visually similar to the original stochastic sampling method.
    • Gaussian Sampling: An optimized version of the original stochastic approach. It uses parallel processing to apply Gaussian noise to pixels, find nearest neighbors in a palette, and average the results. It is slower than Gaussian RBF but produces high-quality results.
    • Shepard's Method (IDW): An implementation of Inverse Distance Weighting. While very fast (hundreds of milliseconds), it produces different visual results compared to Gaussian sampling.

    Color Space

    Lutgen performs color math (such as finding nearest neighbors and averaging colors) in the Oklab color space. This ensures that color matching is perceptually accurate and results in smooth transitions.

  7. Save edited output in Lutgen Studio

    main

    Depending on whether you are using the Native or Web version of Lutgen Studio, the export process differs:

    • Native App: Click Save As in the File menu to save the edited image to a file in any supported format.
    • Web App: Select an image format in the File -> Export menu to export your edited output.

  9. Manage custom palettes in lutgen

    main

    Custom palettes can be used with the -p or --palette flag. To make a custom palette available, place the file in one of the following directories:

    • Linux: /home/alice/.config/lutgen (or your specific $HOME/.config/lutgen)
    • macOS: /Users/Alice/Library/Application Support/lutgen
    • Windows: C:\Users\Alice\AppData\Roaming\lutgen

    Naming Convention: Palette names are case-insensitive and are derived from the file stem (the filename without the extension). For example, a file named ~/.config/lutgen/My-palette.txt is referenced in the CLI as my-palette.

  10. Generate a Hald CLUT with `lutgen generate`

    main

    Use the generate command to create a Hald CLUT from a palette or custom colors. You can specify different interpolation algorithms to control how colors are blended.

    Usage: lutgen generate [-o PATH] [-p PALETTE] [ALGORITHM ...] -- [COLORS]...

    Key Options:

    • -o, --output PATH: Path to write the output file.
    • -p, --palette PALETTE: Use a built-in or custom palette. Custom palettes can be added to $LUTGEN_DIR or the local config directory (e.g., ~/.config/lutgen). Names are case-insensitive and based on the filename stem.
    • --: Separator used to pass custom COLORS to the generator.

    Interpolation Algorithms:

    • Gaussian RBF (-R): Uses Gaussian Radial Basis Function. Use -s (--shape) to control blending (higher = less blending) and -n (--nearest) to set the number of nearest colors to consider.
    • Gaussian Sampling (-G): A slower method using noise. Use -m (--mean), -s (--std-dev), and -i (--iterations) to control the noise application.
    • Shepard's Method (-S): Inverse Distance RBF. Use -p (--power) to adjust the power parameter.
    • Nearest Neighbor (-N): Disables interpolation entirely.
    • Gaussian Blur (Default): Uses a Gaussian blur. Use -r (--radius) to adjust the sigma (larger = more blending).
    # Example: Generate a LUT using a custom palette and Gaussian RBF
lutgen generate -o my_lut.png -p my-palette -R --

# Example: Generate a LUT using specific custom colors
lutgen generate -o custom.png -R -- #ff0000 #00ff00 #0000ff

  11. Generate raw Hald-CLUTs from palettes or colors

    main

    You can generate raw Hald-CLUT images (used for film emulation or manual LUT application) using the lutgen generate command.

    From a built-in palette

    Use the -p flag to specify the palette name.

    lutgen generate -p catppuccin-mocha

    From custom hex colors

    Pass hex colors as arguments after a -- separator. The output file is specified with -o.

    lutgen generate -o custom.png -- "#ABCDEF" ffffff 000000

  12. Set up the Lutgen Wiki development environment

    main

    To develop or preview the Lutgen Wiki locally, you must have jekyll and bundler installed on your system. The wiki is located in the docs/ directory of the repository.

    cd docs/

# install deps
bundle install

# preview the site locally
bundle exec jekyll serve

# build the site
bundle exec jekyll build