Offer standard web and print canvas formats

The canvas was two spin buttons, so "an Instagram story" or "A4 at 300 dpi"
was a number the user had to work out. src/core/canvas.cpp now holds one
table of standard sizes both front-ends read: a web format is a fixed pixel
size, a print format a sheet in millimetres that becomes pixels at a dpi.
Adding a format is a line in canvasFormats() — the dropdown, --format and
--help all walk the table.

The pixels stay the truth everywhere; renderChain never hears about formats.
A format is the presentation of a canvas, carried alongside the pixels in
Options and Project and empty for a custom size, and where one is named it
decides the pixels — so a project saved as A4 reopens as A4 rather than as
whatever it happened to measure.

In the interface a format fills the width and height in and greys them out
rather than hiding them: the size a sheet works out to is worth seeing. A
print format also shows a DPI row, and Custom hands the spins back keeping
the last size, which makes starting from a format and then tweaking it the
ordinary path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/cli/options.cpp

@@ -5,6 +5,7 @@
 #include <cstring>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/effect.hpp"
 #include "core/registry.hpp"
@@ -74,6 +75,20 @@ Options parseOptions(int argc, char** argv) {
                                   "each side between " + std::to_string(kMinCanvasSide) + " and " +
                                   std::to_string(kMaxCanvasSide));
             }
+        } else if (arg == "--format") {
+            const std::string value = requireValue(argc, argv, i, arg);
+            if (canvasFormatByKey(value) == nullptr) {
+                throw EffectError("unknown canvas format '" + value + "', see --help");
+            }
+            options.format = value;
+        } else if (arg == "--dpi") {
+            const std::string value = requireValue(argc, argv, i, arg);
+            long dpi = 0;
+            if (!parseLong(value, dpi) || dpi < kMinDpi || dpi > kMaxDpi) {
+                throw EffectError("invalid dpi '" + value + "', expected " +
+                                  std::to_string(kMinDpi) + "-" + std::to_string(kMaxDpi));
+            }
+            options.dpi = static_cast<int>(dpi);
         } else if (arg == "--seed") {
             const std::string value = requireValue(argc, argv, i, arg);
             long seed = 0;
@@ -140,6 +155,11 @@ Options parseOptions(int argc, char** argv) {
             options.images.push_back(arg);
         }
     }
+    // Applied once everything is parsed, so --dpi may come before --format and
+    // so a format always wins over an -s given alongside it.
+    if (const auto* format = canvasFormatByKey(options.format)) {
+        canvasFormatSize(*format, options.dpi, options.width, options.height);
+    }
     if (options.effects.empty()) options.effects.push_back(defaultEffectName());
     return options;
 }
@@ -153,10 +173,21 @@ std::string usage(const char* programName) {
         << "  -o, --output FILE     render headlessly to this file and exit\n"
         << "  -s, --size WxH        canvas size, each side " << kMinCanvasSide << "-"
         << kMaxCanvasSide << " (default: 1920x1080)\n"
+        << "      --format NAME     canvas format, overrides --size (see below)\n"
+        << "      --dpi N           resolution of a print format, " << kMinDpi << "-" << kMaxDpi
+        << " (default: " << kDefaultDpi << ")\n"
         << "      --seed N          random seed (default: random)\n"
         << "      --list-effects    list available effects and exit\n"
         << "  -h, --help            show this help and exit\n";
 
+    out << "\nCanvas formats (--format):\n";
+    for (const auto& format : canvasFormats()) {
+        out << "  " << format.key;
+        if (format.key.size() < 20) out << std::string(20 - format.key.size(), ' ');
+        out << "  " << format.label << ", " << canvasFormatDetail(format)
+            << (format.print ? " at --dpi" : "") << "\n";
+    }
+
     for (const auto& effect : effects()) {
         out << "\n" << effect->title() << " options:\n";
         for (const auto& spec : effect->params()) {

src/cli/options.hpp

@@ -5,6 +5,7 @@
 #include <string>
 #include <vector>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/params.hpp"
 
@@ -16,6 +17,8 @@ struct Options {
     std::string output;              // empty -> launch the interface
     int width = 1920;
     int height = 1080;
+    std::string format;      // a named canvas format, empty for plain pixels
+    int dpi = kDefaultDpi;   // only a print format is rendered at a resolution
     std::optional<std::uint64_t> seed;
     ParamValues params;              // only the keys the user actually passed
     bool listEffects = false;

src/core/canvas.cpp

@@ -0,0 +1,76 @@
+#include "core/canvas.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <locale>
+#include <sstream>
+
+#include "core/chain.hpp"
+
+namespace effector {
+namespace {
+
+// 210 mm reads as "210", 215.9 mm as "215.9". In the C locale whatever the
+// user's is: gtkmm sets the global locale from the environment, so a stream
+// left to its default writes "210,0" on a German desktop.
+std::string millimetres(double mm) {
+    std::ostringstream out;
+    out.imbue(std::locale::classic());
+    out.setf(std::ios::fixed);
+    out.precision(1);
+    out << mm;
+    std::string text = out.str();
+    if (text.size() > 2 && text.compare(text.size() - 2, 2, ".0") == 0) text.resize(text.size() - 2);
+    return text;
+}
+
+}  // namespace
+
+const std::vector<CanvasFormat>& canvasFormats() {
+    // Written out once and handed back by reference: the table is fixed, and
+    // both front-ends walk it for their menu and their --help.
+    static const std::vector<CanvasFormat> formats = {
+        {"instagram-post", "Instagram post", false, 1080, 1080, 0.0, 0.0},
+        {"instagram-portrait", "Instagram portrait", false, 1080, 1350, 0.0, 0.0},
+        {"instagram-story", "Instagram story", false, 1080, 1920, 0.0, 0.0},
+        {"hd", "Full HD", false, 1920, 1080, 0.0, 0.0},
+        {"uhd", "4K UHD", false, 3840, 2160, 0.0, 0.0},
+        {"a5", "A5", true, 0, 0, 148.0, 210.0},
+        {"a4", "A4", true, 0, 0, 210.0, 297.0},
+        {"a3", "A3", true, 0, 0, 297.0, 420.0},
+        {"letter", "US Letter", true, 0, 0, 215.9, 279.4},
+    };
+    return formats;
+}
+
+const CanvasFormat* canvasFormatByKey(const std::string& key) {
+    if (key.empty()) return nullptr;
+    for (const auto& format : canvasFormats()) {
+        if (format.key == key) return &format;
+    }
+    return nullptr;
+}
+
+void canvasFormatSize(const CanvasFormat& format, int dpi, int& width, int& height) {
+    if (!format.print) {
+        width = format.width;
+        height = format.height;
+        return;
+    }
+    const int clamped = std::clamp(dpi, kMinDpi, kMaxDpi);
+    const auto pixels = [clamped](double mm) {
+        const long value = std::lround(mm / 25.4 * clamped);
+        return static_cast<int>(std::clamp<long>(value, kMinCanvasSide, kMaxCanvasSide));
+    };
+    width = pixels(format.widthMm);
+    height = pixels(format.heightMm);
+}
+
+std::string canvasFormatDetail(const CanvasFormat& format) {
+    if (format.print) {
+        return millimetres(format.widthMm) + " × " + millimetres(format.heightMm) + " mm";
+    }
+    return std::to_string(format.width) + " × " + std::to_string(format.height) + " px";
+}
+
+}  // namespace effector

src/core/canvas.hpp

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace effector {
+
+// A named canvas size both front-ends offer, so "A4 at 300 dpi" is one choice
+// rather than a pixel count the user has to work out. Web formats are a fixed
+// pixel size; print formats are a physical size in millimetres and only become
+// pixels once a resolution is given, which is why the dpi belongs to the
+// canvas rather than to any one format.
+struct CanvasFormat {
+    std::string key;    // written in a project and given to --format, e.g. "a4"
+    std::string label;  // shown in the interface, e.g. "A4"
+    bool print = false;
+    int width = 0;         // pixels, web formats only
+    int height = 0;        //
+    double widthMm = 0.0;  // millimetres, print formats only
+    double heightMm = 0.0;
+};
+
+// The dpi a print format is rendered at. The bounds keep A3 — the largest
+// sheet here — inside kMaxCanvasSide at the top end, and keep a sheet from
+// coming out too small to see at the bottom.
+inline constexpr int kMinDpi = 36;
+inline constexpr int kMaxDpi = 1200;
+inline constexpr int kDefaultDpi = 300;
+
+// In the order they are offered: the web formats first, then the paper sizes.
+const std::vector<CanvasFormat>& canvasFormats();
+
+// Null when the key names no format, which is how a custom canvas — the user's
+// own pixel sizes — is spelled everywhere: an empty or unknown key.
+const CanvasFormat* canvasFormatByKey(const std::string& key);
+
+// The pixel size of a format. `dpi` is ignored by a web format, which already
+// is a pixel size; a print format is rounded to the nearest pixel and clamped
+// to the canvas bounds.
+void canvasFormatSize(const CanvasFormat& format, int dpi, int& width, int& height);
+
+// "1080 × 1080 px" or "210 × 297 mm", for the dropdown and for --help.
+std::string canvasFormatDetail(const CanvasFormat& format);
+
+}  // namespace effector

src/core/project.cpp

@@ -10,6 +10,7 @@
 #include <locale>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/effect.hpp"
 #include "core/registry.hpp"
 
@@ -306,6 +307,18 @@ int canvasSide(const Json& value, const char* what) {
     return static_cast<int>(value.number);
 }
 
+// Checked as a double before narrowing, exactly as a canvas side is.
+int canvasDpi(const Json& value) {
+    if (value.kind != Json::Kind::Number || value.number != std::trunc(value.number)) {
+        throw EffectError("the canvas dpi must be a whole number");
+    }
+    if (!(value.number >= kMinDpi) || !(value.number <= kMaxDpi)) {
+        throw EffectError("the canvas dpi must be between " + std::to_string(kMinDpi) + " and " +
+                          std::to_string(kMaxDpi));
+    }
+    return static_cast<int>(value.number);
+}
+
 std::string resolve(const std::string& path, const std::string& directory) {
     std::filesystem::path file(path);
     if (file.is_absolute() || directory.empty()) return path;
@@ -323,8 +336,15 @@ std::string projectToJson(const Project& project, const std::string& directory)
     out.imbue(std::locale::classic());
     out << "{\n";
     out << "  \"effector_project\": 1,\n";
-    out << "  \"canvas\": {\"width\": " << project.width << ", \"height\": " << project.height
-        << "},\n";
+    out << "  \"canvas\": {\"width\": " << project.width << ", \"height\": " << project.height;
+    // The pixels are always written, so a project opens the same in a reader
+    // that knows nothing of formats; the format and its dpi come after them
+    // and only when there is one to name.
+    if (const auto* format = canvasFormatByKey(project.format)) {
+        out << ", \"format\": " << quote(format->key);
+        if (format->print) out << ", \"dpi\": " << project.dpi;
+    }
+    out << "},\n";
     if (project.seed) out << "  \"seed\": " << *project.seed << ",\n";
 
     out << "  \"sources\": [";
@@ -396,6 +416,18 @@ Project projectFromJson(const std::string& text, const std::string& directory) {
         if (const auto* height = canvas->member("height")) {
             project.height = canvasSide(*height, "height");
         }
+        if (const auto* dpi = canvas->member("dpi")) project.dpi = canvasDpi(*dpi);
+        // A format the build does not know is simply a custom canvas: the
+        // pixels were written too, so the project still renders as it was
+        // saved. Where the format is known it decides the pixels, so a
+        // hand-edited dpi takes effect and a preset stays true to its name.
+        if (const auto* name = canvas->member("format"); name != nullptr &&
+                                                         name->kind == Json::Kind::String) {
+            if (const auto* format = canvasFormatByKey(name->text)) {
+                project.format = format->key;
+                canvasFormatSize(*format, project.dpi, project.width, project.height);
+            }
+        }
     }
 
     if (const auto* seed = root.member("seed")) {

src/core/project.hpp

@@ -5,6 +5,7 @@
 #include <string>
 #include <vector>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/params.hpp"
 
@@ -18,6 +19,12 @@ struct Project {
     std::vector<ChainStage> stages;
     int width = 1920;
     int height = 1080;
+    // The named format the canvas came from, empty for a custom pixel size.
+    // The pixels above stay the truth for the render; this is what the
+    // interface puts back in its dropdown, and what a print format needs its
+    // resolution for.
+    std::string format;
+    int dpi = kDefaultDpi;
     std::optional<std::uint64_t> seed;
 };
 

src/gui/window.cpp

@@ -7,6 +7,7 @@
 #include <filesystem>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/project.hpp"
 #include "core/registry.hpp"
@@ -175,28 +176,7 @@ Gtk::Widget& EffectorWindow::buildSidebar() {
     sidebar->append(sourcesExpander_);
 
     sidebar->append(*sectionLabel("Canvas"));
-    auto* grid = Gtk::make_managed<Gtk::Grid>();
-    grid->set_column_spacing(8);
-    grid->set_row_spacing(6);
-    widthSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
-    widthSpin_.set_increments(1, 100);
-    widthSpin_.set_value(1920);
-    heightSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
-    heightSpin_.set_increments(1, 100);
-    heightSpin_.set_value(1080);
-    for (auto* spin : {&widthSpin_, &heightSpin_}) {
-        spin->set_hexpand(true);
-        spin->signal_value_changed().connect(sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
-    }
-    auto* widthLabel = Gtk::make_managed<Gtk::Label>("Width");
-    widthLabel->set_xalign(0.0F);
-    auto* heightLabel = Gtk::make_managed<Gtk::Label>("Height");
-    heightLabel->set_xalign(0.0F);
-    grid->attach(*widthLabel, 0, 0);
-    grid->attach(widthSpin_, 1, 0);
-    grid->attach(*heightLabel, 0, 1);
-    grid->attach(heightSpin_, 1, 1);
-    sidebar->append(*grid);
+    sidebar->append(buildCanvasSection());
 
     auto* seedBox = Gtk::make_managed<Gtk::Box>(Gtk::Orientation::HORIZONTAL, 8);
     auto* seedLabel = Gtk::make_managed<Gtk::Label>("Seed");
@@ -220,6 +200,122 @@ void EffectorWindow::updateSourcesLabel() {
                                           : "Source images (" + std::to_string(count) + ")");
 }
 
+// The canvas is either a named format — a web size, or a sheet of paper at a
+// resolution — or the user's own pixels. A format owns the two spin buttons
+// while it is picked, which is why they are shown greyed out rather than
+// hidden: the size a format works out to is worth seeing.
+Gtk::Widget& EffectorWindow::buildCanvasSection() {
+    auto* box = Gtk::make_managed<Gtk::Box>(Gtk::Orientation::VERTICAL, 6);
+
+    // Index 0 is "Custom"; every later index is canvasFormats()[index - 1].
+    std::vector<Glib::ustring> labels{"Custom"};
+    for (const auto& format : canvasFormats()) {
+        labels.push_back(format.label + " (" + canvasFormatDetail(format) + ")");
+    }
+    formatDrop_.set_model(Gtk::StringList::create(labels));
+    formatDrop_.set_selected(0);
+    formatDrop_.set_tooltip_text("Standard web and print sizes, or your own pixels");
+    formatDrop_.property_selected().signal_changed().connect(
+        sigc::mem_fun(*this, &EffectorWindow::syncCanvasWidgets));
+    box->append(formatDrop_);
+
+    auto* grid = Gtk::make_managed<Gtk::Grid>();
+    grid->set_column_spacing(8);
+    grid->set_row_spacing(6);
+    widthSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
+    widthSpin_.set_increments(1, 100);
+    widthSpin_.set_value(1920);
+    heightSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
+    heightSpin_.set_increments(1, 100);
+    heightSpin_.set_value(1080);
+    dpiSpin_.set_range(kMinDpi, kMaxDpi);
+    dpiSpin_.set_increments(1, 50);
+    dpiSpin_.set_value(kDefaultDpi);
+    for (auto* spin : {&widthSpin_, &heightSpin_, &dpiSpin_}) {
+        spin->set_hexpand(true);
+    }
+    for (auto* spin : {&widthSpin_, &heightSpin_}) {
+        spin->signal_value_changed().connect([this] {
+            if (!suspendCanvasSync_) onParamChanged();
+        });
+    }
+    // The dpi decides the pixels of a sheet, so moving it goes through the
+    // same path a format change does.
+    dpiSpin_.signal_value_changed().connect([this] {
+        if (!suspendCanvasSync_) syncCanvasWidgets();
+    });
+
+    auto* widthLabel = Gtk::make_managed<Gtk::Label>("Width");
+    widthLabel->set_xalign(0.0F);
+    auto* heightLabel = Gtk::make_managed<Gtk::Label>("Height");
+    heightLabel->set_xalign(0.0F);
+    auto* dpiLabel = Gtk::make_managed<Gtk::Label>("DPI");
+    dpiLabel->set_xalign(0.0F);
+    dpiLabel_ = dpiLabel;
+    grid->attach(*widthLabel, 0, 0);
+    grid->attach(widthSpin_, 1, 0);
+    grid->attach(*heightLabel, 0, 1);
+    grid->attach(heightSpin_, 1, 1);
+    grid->attach(*dpiLabel, 0, 2);
+    grid->attach(dpiSpin_, 1, 2);
+    box->append(*grid);
+
+    // Quietly: the sidebar is still being built, and nothing is to be rendered
+    // until the initial options or a project have had their say.
+    suspendCanvasSync_ = true;
+    syncCanvasWidgets();
+    suspendCanvasSync_ = false;
+    return *box;
+}
+
+std::string EffectorWindow::canvasFormatKey() const {
+    const auto selected = formatDrop_.get_selected();
+    if (selected == GTK_INVALID_LIST_POSITION || selected == 0) return {};
+    const auto index = static_cast<std::size_t>(selected) - 1;
+    const auto& formats = canvasFormats();
+    return index < formats.size() ? formats[index].key : std::string();
+}
+
+// A key the build does not know — an old project, or a hand-edited file — lands
+// on "Custom", which leaves the pixels the project carries alone.
+void EffectorWindow::setCanvasFormat(const std::string& key, int dpi) {
+    const bool suspended = suspendCanvasSync_;
+    suspendCanvasSync_ = true;
+    dpiSpin_.set_value(std::clamp(dpi, kMinDpi, kMaxDpi));
+    guint selected = 0;
+    const auto& formats = canvasFormats();
+    for (std::size_t i = 0; i < formats.size(); ++i) {
+        if (formats[i].key == key) selected = static_cast<guint>(i + 1);
+    }
+    formatDrop_.set_selected(selected);
+    syncCanvasWidgets();  // still suspended, so the spins follow without a render
+    suspendCanvasSync_ = suspended;
+}
+
+void EffectorWindow::syncCanvasWidgets() {
+    // Suspended means a caller is putting the canvas together — the initial
+    // options, or a project being opened — and will ask for the render itself.
+    const bool quiet = suspendCanvasSync_;
+    const auto* format = canvasFormatByKey(canvasFormatKey());
+    const bool print = format != nullptr && format->print;
+    dpiLabel_->set_visible(print);
+    dpiSpin_.set_visible(print);
+    widthSpin_.set_sensitive(format == nullptr);
+    heightSpin_.set_sensitive(format == nullptr);
+
+    if (format != nullptr) {
+        int width = 0;
+        int height = 0;
+        canvasFormatSize(*format, static_cast<int>(dpiSpin_.get_value()), width, height);
+        const bool suspended = suspendCanvasSync_;
+        suspendCanvasSync_ = true;  // one render for the change, not one per spin
+        widthSpin_.set_value(width);
+        heightSpin_.set_value(height);
+        suspendCanvasSync_ = suspended;
+    }
+    if (!quiet) onParamChanged();
+}
+
 Gtk::Widget& EffectorWindow::buildPreview() {
     picture_.set_can_shrink(true);
     picture_.set_content_fit(Gtk::ContentFit::CONTAIN);
@@ -429,6 +525,7 @@ void EffectorWindow::applyInitial(const Options& initial) {
 
     widthSpin_.set_value(initial.width);
     heightSpin_.set_value(initial.height);
+    setCanvasFormat(initial.format, initial.dpi);  // a format fills the spins itself
     if (initial.seed) {
         seed_ = *initial.seed;
         seedEntry_.set_text(std::to_string(seed_));
@@ -1098,6 +1195,8 @@ Project EffectorWindow::currentProject() const {
     project.stages = stages_;
     project.width = static_cast<int>(widthSpin_.get_value());
     project.height = static_cast<int>(heightSpin_.get_value());
+    project.format = canvasFormatKey();
+    project.dpi = static_cast<int>(dpiSpin_.get_value());
     project.seed = seed_;
     return project;
 }
@@ -1114,6 +1213,7 @@ void EffectorWindow::applyProject(const Project& project, const std::string& pat
 
     widthSpin_.set_value(project.width);
     heightSpin_.set_value(project.height);
+    setCanvasFormat(project.format, project.dpi);
     seed_ = project.seed.value_or(Rng::randomSeed());
     seedEntry_.set_text(std::to_string(seed_));
 

src/gui/window.hpp

@@ -49,6 +49,14 @@ private:
     void cancelLoad();
     void appendSourceRow(const std::string& path);
     void updateSourcesLabel();  // the collapsed expander shows the count
+
+    Gtk::Widget& buildCanvasSection();
+    // "" while "Custom" is picked, otherwise the format's key.
+    std::string canvasFormatKey() const;
+    void setCanvasFormat(const std::string& key, int dpi);  // dropdown and dpi
+    // A format owns the pixel sizes, so the spins follow it and are greyed
+    // out; "Custom" hands them back to the user untouched.
+    void syncCanvasWidgets();
     void removeSource(Gtk::ListBoxRow* row);
 
     Gtk::Widget& buildChainSection();
@@ -146,8 +154,14 @@ private:
     Gtk::Label* loadFileLabel_ = nullptr;
     Gtk::Expander sourcesExpander_;
     Gtk::ListBox sourceList_;
+    Gtk::DropDown formatDrop_;
     Gtk::SpinButton widthSpin_;
     Gtk::SpinButton heightSpin_;
+    Gtk::SpinButton dpiSpin_;
+    Gtk::Label* dpiLabel_ = nullptr;  // hidden along with the dpi spin
+    // Set while a format fills the spins, so their own handler does not queue
+    // a second render on top of the one the format change asks for.
+    bool suspendCanvasSync_ = false;
     Gtk::Grid paramGrid_;
     Gtk::Label paramHeading_;
     Gtk::Entry seedEntry_;