Watermark and Border module

[GhastCraftHD]

Hey there,

I wanted to ask what your thoughts are about two module ideas.

The first module is about placing watermarks on top of an image. These could be read from simple text, SVGs or PNGs.

The second module is about framing an image with a border filled with e.g. a solid color.

I don't know, if these ideas were up for discussion yet and just disregarded, however these are the only two things I do to my pictures outside of ART. If you like the ideas and are considering implementing then, feel free to reach out. I'd love to take over the responsibility for implementing one or both of them to give back to the project.

Cheers!

[agriggio]

Hi,
I have no plans of adding this myself, but I would be very happy to have them as contributions! So, feel free to submit one or more PRs if/when you are ready!

[GhastCraftHD]

All right, I will see to it! Could I ask you to give me a short overview of what I have to add/change to achieve the addition of a new module?

[agriggio]

I'll see what I can do. Unfortunately art is still not very modular so there will be a few files to touch

[agriggio]

So, here's a guide on how to add a new tool, courtesy of Claude. Hope it helps.

---

Adding a New Tool to ART

This guide walks through every file you must touch to add a new image-processing
tool to ART, from the parameter definition down to the processing code and the
GUI. Three pieces of ART's architecture make this simpler than it might look, and
the guide leans on all three: a flat ParamsEdited (one flag per tool), a single
centralized staged pipeline that lists every processing step in order, and a
runtime event mapper that lets a tool register its own reprocessing events
without touching any shared tables.

Throughout, we use a hypothetical tool called Foo with a member name foo
and two parameters (amount, mode) plus the usual enabled flag. Wherever you
see Foo/foo, substitute your tool's name. The two best real tools to read
alongside this guide are Film Grain (rtgui/grain.*, rtengine/ipgrain.cc)
and CA Correction (rtgui/cacorrection.*), both small and self-contained.

Overview — the moving parts

A tool touches four layers, in this order:

1. Parameters (rtengine/procparams.*, rtgui/paramsedited.*) — the data
   model: a FooParams struct, serialization to/from the .arp profile, and a
   partial-paste flag.
2. Processing (rtengine/improcfun.h, a new rtengine/ipfoo.cc,
   rtengine/improcfun.cc) — the algorithm and its slot in the pipeline.
3. Events (via rtgui/eventmapper.h) — how a GUI change tells the engine
   which part of the pipeline to re-run.
4. GUI (rtgui/foo.*, rtgui/toolpanelcoord.*,
   rtgui/partialpastedlg.cc) — the tool panel and its registration.
5. Localization (rtdata/languages/default and friends) — the UI strings.
6. Build (rtengine/CMakeLists.txt, rtgui/CMakeLists.txt) — the two new
   .cc files.

A complete checklist is at the end.

---

1. Parameters

1.1 Declare the struct — rtengine/procparams.h

Add a struct next to the existing tool structs. Every tool struct has the same
shape: an enabled flag, the data fields, a default constructor, and
operator==/operator!=. Model it on CACorrParams
(rtengine/procparams.h):

struct CACorrParams {
    bool enabled;
    double red;
    double blue;

    CACorrParams();

    bool operator==(const CACorrParams &other) const;
    bool operator!=(const CACorrParams &other) const;
};

Your version:

struct FooParams {
    enum class Mode { LINEAR, LOG };

    bool enabled;
    double amount;
    Mode mode;

    FooParams();

    bool operator==(const FooParams &other) const;
    bool operator!=(const FooParams &other) const;
};

Then add a member to the ProcParams class, in the block of tool members
(around the gradient/cacorrection/vignetting lines):

    CACorrParams cacorrection;     ///< Lens c/a correction parameters
    FooParams foo;                 ///< Foo tool parameters

The member name foo is the identifier used everywhere else — defaults,
save, load, equality, and the ParamsEdited flag must all use the same name,
because some of the machinery substitutes it textually via macros.

If your tool supports masks / regions (like SmoothingParams or
ColorCorrectionParams), derive from MaskableParams instead of a plain struct
and hold std::vector<Region> + std::vector<Mask>. That is a larger topic;
copy SmoothingParams wholesale if you need it. The rest of this guide assumes a
plain, non-mask tool.

1.2 Implement the struct — rtengine/procparams.cc

Defaults live in the constructor (not in setDefaults). Add near the other
tool implementations:

FooParams::FooParams():
    enabled(false), amount(0.0), mode(Mode::LINEAR)
{
}

bool FooParams::operator==(const FooParams &other) const
{
    return enabled == other.enabled && amount == other.amount &&
           mode == other.mode;
}

bool FooParams::operator!=(const FooParams &other) const
{
    return !(*this == other);
}

1.3 Reset — ProcParams::setDefaults()

setDefaults() just re-assigns a fresh default-constructed struct. Add one line:

    foo = FooParams();

1.4 Save to the profile — ProcParams::save(...)

Find the big ProcParams::save(ProgressListener*, bool, KeyFile&, const ParamsEdited*, ...) function. Near its top it defines:

#define RELEVANT_(n) (!pedited || pedited->n)

Add a save block alongside the others (e.g. right after the CACorrection
block). Use saveToKeyfile for scalars/bools; use the enum overload (which takes
a std::map<T, const char*>) for enum fields:

        // Foo
        if (RELEVANT_(foo)) {
            saveToKeyfile("Foo", "Enabled", foo.enabled, keyFile);
            saveToKeyfile("Foo", "Amount", foo.amount, keyFile);
            saveToKeyfile("Foo", "Mode", {
                    {FooParams::Mode::LINEAR, "Linear"},
                    {FooParams::Mode::LOG, "Log"}
                }, foo.mode, keyFile);
        }

"Foo" is the [Foo] group name in the .arp file; "Enabled", "Amount",
"Mode" are the keys. Pick stable names — they become part of the on-disk
format.

1.5 Load from the profile — ProcParams::load(...)

Find the matching ProcParams::load(...). The load side always double-guards
on has_group(...) and RELEVANT_(...), and uses assignFromKeyfile
(which only assigns when the key is present):

        if (keyFile.has_group("Foo") && RELEVANT_(foo)) {
            assignFromKeyfile(keyFile, "Foo", "Enabled", foo.enabled);
            assignFromKeyfile(keyFile, "Foo", "Amount", foo.amount);
            assignFromKeyfile(keyFile, "Foo", "Mode", {
                    {"Linear", FooParams::Mode::LINEAR},
                    {"Log", FooParams::Mode::LOG}
                }, foo.mode);
        }

Note the enum map is inverted relative to save (string → enum on load).

1.6 Equality — ProcParams::operator==

Near the bottom of procparams.cc, operator== ANDs a ppEQ_ macro over every
tool member. Add your member into the && chain:

    ppEQ_(cacorrection) && ppEQ_(foo) && ppEQ_(vignetting) &&

Miss this and profile-change detection / the History panel will not notice edits
to your tool.

1.7 Partial-paste flag — rtgui/paramsedited.h / .cc

ParamsEdited records, per tool, whether that tool should be affected by a
partial operation (such as pasting only part of a profile). It is a flat class
with one flag per tool — there is no per-field granularity — so the
authoritative list of tools is simply its set of boolean members
(rtgui/paramsedited.h). Add one:

    bool foo;

Then in rtgui/paramsedited.cc, add an assignment inside set():

void ParamsEdited::set(bool v)
{
    ...
    foo = v;
    ...
}

That is all a plain tool needs. Only the four tri-state mask tools
(colorcorrection, smoothing, localContrast, textureBoost) are unsigned
and appear in set_append() — ignore that unless your tool is a mask tool.

The connection to save/load: RELEVANT_(foo) expands to !pedited || pedited->foo. When no pedited is supplied (normal save/load) everything is
processed; when a partial profile supplies one (partial paste), only tools whose
flag is true are touched. The member name in ProcParams must match the
flag name in ParamsEdited.

---

2. Processing

2.1 Declare the method — rtengine/improcfun.h

Every tool is a member method of ImProcFunctions operating on an
Imagefloat *. There are two conventions:

• void foo(Imagefloat *rgb) — always continues the pipeline.
• bool foo(Imagefloat *rgb) — returns true to stop the pipeline (used
  only when the tool paints a mask/preview overlay into the buffer instead of the
  image).

Use void unless you need mask-preview. Add the declaration next to the others
(around the filmGrain/logEncoding/softLight block):

    void filmGrain(Imagefloat *rgb);
    void foo(Imagefloat *rgb);

2.2 Implement it — new file rtengine/ipfoo.cc

Follow the rtengine/ipsoftlight.cc template — the cleanest minimal tool. Four
load-bearing patterns: (1) an early enabled guard, (2) coerce the
shared buffer into the color space you need with setMode, (3) read all
parameters from the params member, (4) OpenMP-guarded pixel loops honoring
the multiThread member.

#ifdef _OPENMP
#include <omp.h>
#endif

#include "improcfun.h"
#include "rt_math.h"

namespace rtengine {

void ImProcFunctions::foo(Imagefloat *rgb)
{
    // (1) enabled guard — always first
    if (!params->foo.enabled || params->foo.amount == 0.0) {
        return;
    }

    // (2) force the buffer into the color space this tool works in.
    //     Use Mode::RGB for RGB tools, Mode::LAB for Lab tools (there g() is L).
    rgb->setMode(Imagefloat::Mode::RGB, multiThread);

    // (3) read parameters exclusively from `params`
    const float amount = params->foo.amount;
    const int W = rgb->getWidth();
    const int H = rgb->getHeight();

    // (4) pixel loop, OpenMP guarded by the multiThread member
#ifdef _OPENMP
#   pragma omp parallel for if (multiThread)
#endif
    for (int y = 0; y < H; ++y) {
        for (int x = 0; x < W; ++x) {
            rgb->r(y, x) *= (1.f + amount);
            rgb->g(y, x) *= (1.f + amount);
            rgb->b(y, x) *= (1.f + amount);
        }
    }
}

} // namespace rtengine

Useful members available inside any ImProcFunctions method: scale (preview
subsampling factor — divide radii/sizes by it so the preview matches the full
image), offset_x / offset_y, full_width / full_height, cur_pipeline
(OUTPUT / PREVIEW / NAVIGATOR), and multiThread. For a heavy algorithm,
keep the public method thin (guard + param reading + orchestration) and put the
number-crunching in a free function in an anonymous namespace, as
iplocalcontrast.cc and ipsharpen.cc do.

2.3 Insert into the pipeline — rtengine/improcfun.cc

ART centralizes the entire tool sequence in one function,
ImProcFunctions::process(Pipeline, Stage, Imagefloat*). This is the single
place that lists every step in order. Tools are invoked through two macros:

#define STEP_(op)   apply<void>(&ImProcFunctions::op, img)   // void tools
#define STEP_s_(op) apply<bool>(&ImProcFunctions::op, img)   // bool (stop) tools

The function is a switch over four stages. Add your STEP_ call at the
position you want, in the appropriate stage:

    case Stage::STAGE_3:
        STEP_(creativeGradients);
        stop = stop || STEP_s_(textureBoost);
        if (!stop) {
            STEP_(filmGrain);
            STEP_(foo);              // <-- your tool, after grain, before log
            STEP_(logEncoding);
            STEP_(saturationVibrance);
            ...

Choosing the stage matters because each stage runs in a specific color space and
at a specific point in the tone/color chain. As a rough guide:

Stage	Contains (examples)	Typical use
STAGE_0	dehaze, dynamic range compression	very early, scene-referred
STAGE_1	channel mixer, exposure, HSL, tone equalizer	linear RGB, pre-tone
STAGE_2	sharpening, denoise, defringe, color correction	detail / local
STAGE_3	grain, log encoding, saturation, curves, B&W	creative / display-referred

Insert your STEP_ between the neighbours whose "before/after" ordering you
want. For a bool (stop) tool, follow the stop = stop || STEP_s_(foo);
pattern and place it where the guarding if (!stop) logic makes sense.

Optionally bump NUM_PIPELINE_STEPS (a constant near the top of the same file)
so the progress bar stays accurate.

You do not need to edit dcrop.cc, simpleprocess.cc, or
improccoordinator.cc — all three call process() generically, so a tool added
to a stage automatically runs in the interactive preview, the batch/export
output, and the navigator.

---

3. Events (making a GUI change re-process)

When the user changes a widget, the panel calls
listener->panelChanged(EvSomething, description). The engine looks up which
part of the pipeline that event affects and re-runs only what is needed. ART
creates these events at runtime via the event mapper — you do not edit
the static procevents.h enum or the refreshmap.cc array for a new tool.

In your panel's constructor (see §4) you request events:

#include "eventmapper.h"
...
    auto m = ProcEventMapper::getInstance();
    EvEnabled = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_ENABLED");
    EvAmount  = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_AMOUNT");
    EvMode    = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_MODE");

The first argument (the "action") is a refresh level from
rtengine/refreshmap.h. It determines which pipeline stages re-run. The
mapping between refresh masks and stages is:

• M_RGBCURVE → re-runs from STAGE_1
• M_LUMACURVE → re-runs from STAGE_2
• M_LUMINANCE | M_COLOR → re-runs STAGE_3 only

Pick the action constant matching the earliest stage your tool needs
re-run. Convenient pre-defined constants (all in refreshmap.h):

Constant	Re-runs from	Use for a tool in
RGBCURVE	STAGE_1	STAGE_1 / STAGE_2 / STAGE_3
SHARPENING	STAGE_2	STAGE_2 / STAGE_3
LUMINANCECURVE	STAGE_3	STAGE_3
DIRPYREQUALIZER	STAGE_3	STAGE_3
TRANSFORM	geometry	geometry tools

For our foo tool placed in STAGE_3, LUMINANCECURVE (or the equivalent
DIRPYREQUALIZER, which Film Grain uses) is the minimal correct choice;
RGBCURVE also works but re-runs more than necessary. The second argument is the
name of a history-message translation key (see §5) shown in the History
panel; pass "" if you don't want a history entry.

Under the hood, ProcEventMapper::newEvent calls
RefreshMapper::getInstance()->newEvent() for a fresh event id and
mapEvent(event, action) to record its refresh level — so the action you pass
here is the refresh-map entry. No static table edit is required.

---

4. GUI

4.1 The panel — new files rtgui/foo.h / rtgui/foo.cc

Model on rtgui/grain.*. The panel inherits ToolParamBlock (the widget
container), FoldableToolPanel (the collapsible expander + enable checkbox +
reset button + the read/write/setDefaults virtuals), and any listener
interfaces for the widgets it uses (AdjusterListener for sliders).

rtgui/foo.h:

#pragma once

#include "adjuster.h"
#include "toolpanel.h"
#include <gtkmm.h>

class Foo: public ToolParamBlock,
           public AdjusterListener,
           public FoldableToolPanel {
public:
    Foo();

    void read(const rtengine::procparams::ProcParams *pp) override;
    void write(rtengine::procparams::ProcParams *pp) override;
    void setDefaults(const rtengine::procparams::ProcParams *defParams) override;
    void adjusterChanged(Adjuster *a, double newval) override;
    void adjusterAutoToggled(Adjuster *a, bool newval) override {}
    void enabledChanged() override;
    void modeChanged();
    void toolReset(bool to_initial) override;

private:
    Adjuster *amount;
    MyComboBoxText *mode;

    rtengine::ProcEvent EvEnabled;
    rtengine::ProcEvent EvAmount;
    rtengine::ProcEvent EvMode;

    rtengine::procparams::FooParams initial_params;
};

rtgui/foo.cc:

#include "foo.h"
#include "eventmapper.h"

using namespace rtengine;
using namespace rtengine::procparams;

Foo::Foo():
    FoldableToolPanel(this, "foo", M("TP_FOO_LABEL"), false, true, true)
    //                                                 |      |     |
    //                                       need11 ---+      |     |
    //                                       useEnabled (on/off) ---+     |
    //                                       useReset (reset button) ----+
{
    auto m = ProcEventMapper::getInstance();
    EvEnabled = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_ENABLED");
    EvAmount  = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_AMOUNT");
    EvMode    = m->newEvent(rtengine::RGBCURVE, "HISTORY_MSG_FOO_MODE");
    EvToolReset.set_action(rtengine::RGBCURVE);

    amount = Gtk::manage(new Adjuster(M("TP_FOO_AMOUNT"), 0., 100., 1., 0.));
    amount->setAdjusterListener(this);
    amount->show();

    Gtk::HBox *hb = Gtk::manage(new Gtk::HBox());
    hb->pack_start(*Gtk::manage(new Gtk::Label(M("TP_FOO_MODE") + ": ")),
                   Gtk::PACK_SHRINK);
    mode = Gtk::manage(new MyComboBoxText());
    mode->append(M("TP_FOO_MODE_LINEAR"));
    mode->append(M("TP_FOO_MODE_LOG"));
    mode->signal_changed().connect(sigc::mem_fun(*this, &Foo::modeChanged));
    hb->pack_start(*mode);
    hb->show();

    pack_start(*amount);
    pack_start(*hb);
}

void Foo::read(const ProcParams *pp)
{
    disableListener();                // block callbacks while loading
    setEnabled(pp->foo.enabled);
    amount->setValue(pp->foo.amount);
    mode->set_active(int(pp->foo.mode));
    enableListener();
}

void Foo::write(ProcParams *pp)
{
    pp->foo.enabled = getEnabled();
    pp->foo.amount = amount->getValue();
    pp->foo.mode = FooParams::Mode(mode->get_active_row_number());
}

void Foo::setDefaults(const ProcParams *defParams)
{
    amount->setDefault(defParams->foo.amount);
    initial_params = defParams->foo;   // saved for toolReset
}

void Foo::adjusterChanged(Adjuster *a, double newval)
{
    if (listener && getEnabled()) {
        if (a == amount) {
            listener->panelChanged(EvAmount, a->getTextValue());
        }
    }
}

void Foo::modeChanged()
{
    if (listener && getEnabled()) {
        listener->panelChanged(EvMode, mode->get_active_text());
    }
}

void Foo::enabledChanged()
{
    if (listener) {
        if (get_inconsistent()) {
            listener->panelChanged(EvEnabled, M("GENERAL_UNCHANGED"));
        } else if (getEnabled()) {
            listener->panelChanged(EvEnabled, M("GENERAL_ENABLED"));
        } else {
            listener->panelChanged(EvEnabled, M("GENERAL_DISABLED"));
        }
    }
}

void Foo::toolReset(bool to_initial)
{
    ProcParams pp;
    if (to_initial) {
        pp.foo = initial_params;
    }
    pp.foo.enabled = getEnabled();
    read(&pp);
}

Key rules:

• read() copies params → widgets; wrap it in disableListener() /
  enableListener() so it doesn't fire change events.
• write() copies widgets → params. It must be the exact inverse of read().
• adjusterChanged / modeChanged fire listener->panelChanged(EvXxx, text),
  guarded by if (listener && getEnabled()). listener is the coordinator,
  wired up automatically (§4.2).
• setDefaults stashes initial_params for the reset button; toolReset
  restores it.

4.2 Register with the coordinator — rtgui/toolpanelcoord.*

In rtgui/toolpanelcoord.h:

1. Add the include near the other tool includes:

   #include "foo.h"

2. Add a member pointer in the protected block with the other panels:

   Foo *foo;

In rtgui/toolpanelcoord.cc, in the constructor:

3. Allocate it with the other Gtk::manage(new ...) calls:

   foo = Gtk::manage(new Foo());

4. Add it to a tab with addfavoritePanel(<panel>, foo);. The tab VBoxes are
   exposurePanel, detailsPanel, colorPanel, transformPanel, rawPanel,
   localPanel, effectsPanel. For example, to put Foo on the Effects tab:

   addfavoritePanel(effectsPanel, foo);

   To nest it under another tool, pass that tool's getPackBox() and a level:
   addfavoritePanel(lenspanel->getPackBox(), foo, 2);.

That is the entire registration. read(), write(), setDefaults(), the
editor provider, and the fold-state handling all iterate the internal
toolPanels / expList vectors, which addfavoritePanel → addPanel
populate — so there is nothing else to wire. The line
for (auto toolPanel : toolPanels) toolPanel->setListener(this); later in the
constructor connects your panel's listener to the coordinator automatically.

4.3 Partial paste dialog — rtgui/partialpastedlg.cc

The dialog is fully table-driven. Add one row to the get_toggles(...) table,
in whichever group column fits (the index is the group: 0 Exposure, 1 Detail,
2 Effects, 3 Color, 4 Lens, 5 Composition, 6 Local, 7 Raw, 8 Meta). For a plain
bool flag, pass its address as the third field and nullptr as the last:

        {"PARTIALPASTE_FOO", &pedited.foo, 2, nullptr},

(Only the four tri-state mask tools use the last unsigned* field instead; a
plain tool leaves it nullptr and passes &pedited.foo as the bool*.) The
first field, "PARTIALPASTE_FOO", is a translation key (§5).

---

5. Localization

All UI text goes through the M("KEY") macro, which looks the key up in the
language files under rtdata/languages/. The canonical file is
rtdata/languages/default (English); every key you reference must exist there.
Add entries for every string you introduced:

HISTORY_MSG_FOO_ENABLED;Foo
HISTORY_MSG_FOO_AMOUNT;Foo - Amount
HISTORY_MSG_FOO_MODE;Foo - Mode
PARTIALPASTE_FOO;Foo
TP_FOO_LABEL;Foo
TP_FOO_AMOUNT;Amount
TP_FOO_MODE;Mode
TP_FOO_MODE_LINEAR;Linear
TP_FOO_MODE_LOG;Log

Convention: TP_* for tool-panel labels, HISTORY_MSG_* for History-panel
descriptions, PARTIALPASTE_* for the paste dialog. The format is
KEY;Text, one per line, kept sorted. You only need to add to default;
translators fill in the other language files, and missing keys fall back to the
default text.

---

6. Build

Add each new .cc (headers are picked up implicitly) to the appropriate
CMakeLists.txt:

• rtgui/CMakeLists.txt — add foo.cc to the NONCLISOURCEFILES set.
• rtengine/CMakeLists.txt — add ipfoo.cc to the engine source list.

Then rebuild. A .arp profile written by the new build will carry a [Foo]
group; older builds ignore unknown groups, and your load code ignores missing
ones, so the format stays forward/backward compatible.

---

Checklist

Parameters:

• rtengine/procparams.h — struct FooParams { ... } + FooParams foo; member.
• rtengine/procparams.cc — constructor (defaults), operator==, operator!=.
• rtengine/procparams.cc — setDefaults(): foo = FooParams();.
• rtengine/procparams.cc — save(): if (RELEVANT_(foo)) { saveToKeyfile(...); }.
• rtengine/procparams.cc — load(): if (has_group("Foo") && RELEVANT_(foo)) { assignFromKeyfile(...); }.
• rtengine/procparams.cc — operator==: add ppEQ_(foo) &&.
• rtgui/paramsedited.h — bool foo;.
• rtgui/paramsedited.cc — foo = v; in set().

Processing:

• rtengine/improcfun.h — declare void foo(Imagefloat *rgb);.
• rtengine/ipfoo.cc — implement (guard → setMode → read params → pixel loop).
• rtengine/improcfun.cc — insert STEP_(foo); in the right Stage; optionally bump NUM_PIPELINE_STEPS.

GUI + events:

• rtgui/foo.h / rtgui/foo.cc — the panel (events via ProcEventMapper).
• rtgui/toolpanelcoord.h — #include "foo.h" + Foo *foo;.
• rtgui/toolpanelcoord.cc — allocate + addfavoritePanel(<tab>, foo);.
• rtgui/partialpastedlg.cc — one row in get_toggles.

Strings + build:

• rtdata/languages/default — TP_*, HISTORY_MSG_*, PARTIALPASTE_* keys.
• rtgui/CMakeLists.txt — foo.cc.
• rtengine/CMakeLists.txt — ipfoo.cc.

---

Reference tools to copy from

Aspect	Read this
Minimal params + panel	CACorrParams in procparams.*, rtgui/cacorrection.*
Params + panel + enum combo + dynamic events	Film Grain: rtgui/grain.*, GrainParams
Minimal processing method	rtengine/ipsoftlight.cc
Processing that delegates to another tool	rtengine/ipgrain.cc
Lab-space, mask-aware, stop-returning tool	rtengine/iplocalcontrast.cc
Mask / region tool (params)	SmoothingParams, ColorCorrectionParams

[GhastCraftHD]

Alright, thanks, I'm on it!