effector/README.md

Effector

An image effects app: a GTK4 interface and a headless CLI over a set of pluggable effects. Effects are self-contained classes that declare their own parameters; the interface builds its widgets and the CLI builds its flags from those declarations, so a new effect needs no UI or CLI code.

Build

Requirements: a C++20 compiler (GCC 13+), CMake 3.20+, gtkmm-4.0 and gdk-pixbuf-2.0 development packages. On Arch: gcc cmake ninja gtkmm-4.0.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

The binary lands at build/effector; cmake --install build --prefix ~/.local installs it to ~/.local/bin.

Run

build/effector                  # GTK interface
build/effector --list-effects
build/effector --help

Headless rendering, no display needed:

build/effector -o out.png -s 1920x1080 \
    --strip-height 8 --jitter 4 --seed 42 photo1.jpg photo2.png

The canvas is either a size in pixels (-s 1920x1080, the Custom entry in the interface) or one of the standard formats, which --help lists in full:

build/effector -o post.png --format instagram-post -e tiles
build/effector -o sheet.png --format a4 --dpi 300 -e scanlines

A web format — the Instagram sizes, Full HD, 4K UHD — is a fixed pixel size. A print format — A5, A4, A3, US Letter — is a sheet of paper, and becomes pixels at --dpi (36–1200, 300 by default), so A4 at 300 dpi is 2480×3508. Picking a format in the interface fills the width and height in and greys them out; Custom hands them back, keeping whatever the format last worked out to. A format is saved with the project, so an A4 project reopens as A4 rather than as the pixels it happened to be.

Any option can also be passed when launching the interface; it becomes the starting state (images, canvas size, effect settings, seed).

Reading a batch of large photographs takes seconds, so it never blocks the interface: decoding runs in the background and a progress window shows how many files are done, which one is being read, and a Cancel button that stops the batch. Small batches finish before the window would be drawn, so it only appears if the decode is still going after 250 ms. On a terminal the headless mode keeps a single reading n/total line updated on stderr; redirected output stays clean.

Effects

scanlines

Fills the canvas top to bottom with horizontal strips cut at random positions from the source images. Strips are taken at native scale, cropped at a random horizontal offset, and tiled when the source is narrower than the canvas.

Parameter	Flag	Meaning
strip_height	--strip-height	Height in pixels of each extracted line
jitter	--jitter	Random ± variation of that height (0 = uniform)
keep_order	--keep-order	Cycle the images in order instead of picking randomly

The seed makes a result reproducible: same sources, settings and seed give the same image, on any machine — the generator (src/core/rng.hpp) is a hand-rolled xoshiro256** rather than <random>, whose distributions are not portable. Recreate draws a new seed.

Layout

src/core/      image buffer and IO, param specs, effect base, registry, rng, thread helper
src/effects/   one file per effect
src/cli/       argument parsing (flags generated from the registry)
src/gui/       gtkmm 4 interface
tests/         core checks, run by ctest
python-reference/  the original Python prototype, kept for reference only

effector_core is a GUI-free static library that links only gdk-pixbuf, so headless rendering never touches GTK or a display. The GTK front end links on top of it.

Adding an effect

1. Create src/effects/myeffect.{hpp,cpp} with a subclass of Effect:

class MyEffect : public Effect {
    std::string name() const override { return "myeffect"; }
    std::string title() const override { return "My Effect"; }
    std::string description() const override { return "..."; }

    const std::vector<ParamSpec>& params() const override {
        static const std::vector<ParamSpec> specs = {
            ParamSpec::makeInt("amount", "Amount", 4, 1, 64, "How much."),
        };
        return specs;
    }

    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
                 const ParamValues& values) const override {
        const long amount = paramInt(values, "amount", 4);
        ...  // return a width x height RGB image
    }
};

2. Add it to _EFFECT_CLASSES-style list in src/core/registry.cpp and to the source list in CMakeLists.txt.

Widgets and flags follow from params() automatically. Draw everything random from the Rng you are handed so results stay reproducible, and use parallelFor (src/core/parallel.hpp) for the pixel work.

Performance notes

The render loop first draws the whole strip plan from the seeded generator, then copies the pixels in parallel across the hardware threads; each row is a memcpy, and horizontal tiling doubles the filled span per pass. Source images are decoded in parallel too, which is what dominates a headless run.

A 7680×4320 canvas at --strip-height 2 from three multi-megapixel JPEGs renders in ~35 ms, against ~73 ms for the Python prototype; the interface reports the render time of the current preview in its status line.

Decoding threads take the next file from a shared cursor rather than a fixed slice of the list, so one very large file cannot stall the files queued behind it and progress advances at a steady rate.