Stampy

Turn any photo into a perforated postage-stamp PNG, from the command line.

Stampy is a TypeScript port of the original Python stampy tool. It takes an arbitrary input image, fits it into a stamp-shaped canvas, applies an optional photo effect, draws a themed border with a caption and denomination, and punches perforation holes around the edge so the result looks like a real postage stamp.

Install

npm install -g @ishk9/stampy
# or, run without installing:
npx @ishk9/stampy

Quick start

stampy                    # interactive wizard
stampy create photo.jpg   # one-shot

If -o is omitted the output is written next to the source as <input>-stamp.png.

Usage

stampy [--verbose]
       create INPUT [-o OUTPUT] [-c "CAPTION"] [-d "$1"]
              [-t THEME] [-e EFFECT]
              [-W INNER_W] [-H INNER_H] [-b BORDER]
              [--no-perforations] [--perf-radius N] [--perf-spacing N]
       themes
       effects
       wizard

Examples

stampy

stampy create cat.jpg

stampy create cat.jpg -o cat-stamp.png -c "POSTES * PARIS" -d "$1"

stampy create cat.jpg -t midnight -e vintage --perf-spacing 38

stampy create cat.jpg --no-perforations -W 1200 -H 1200

Themes

| Key | Label | Border | Background | | ---------- | -------------- | --------------- | --------------- | | classic | Classic Red | rgb(180, 30, 50) | rgb(255, 252, 240) | | midnight | Midnight Blue | rgb(25, 55, 120) | rgb(245, 248, 255) | | forest | Forest Green | rgb(35, 95, 60) | rgb(250, 252, 245) | | ink | Ink Black | rgb(30, 30, 30) | rgb(252, 250, 245) | | burgundy | Burgundy Gold | rgb(110, 25, 50) | rgb(252, 244, 220) |

Run stampy themes to print this table from the live registry.

Effects

| Key | Description | | ------------ | ------------------------------------------------------- | | none | Pass-through; the photo's tones are preserved as-is. | | sepia | Warm, brown-toned colorisation. | | grayscale | Luminance-only conversion. | | vintage | Faded, low-contrast colorisation with a warm cast. |

Run stampy effects to print this table.

Architecture

src/
├── cli.ts                          # CLI entrypoint (commander)
├── cli/commands/                   # `create`, `themes`, `effects`, `wizard`
├── application/
│   ├── makeStamp.ts                # MakeStampUseCase
│   └── pipelineBuilder.ts          # StampPipelineBuilder
├── domain/
│   ├── models.ts                   # Effect, StampSpec, makeStampSpec
│   ├── themes.ts                   # ThemeRegistry, defaultThemeRegistry
│   └── errors.ts                   # StampyError hierarchy
├── effects/
│   ├── base.ts                     # EffectStrategy interface
│   ├── strategies.ts               # None / Sepia / Grayscale / Vintage
│   └── registry.ts                 # EffectRegistry, defaultEffectRegistry
├── pipeline/
│   ├── base.ts                     # StampImage, StampProcessor, Pipeline
│   ├── orientation.ts              # EXIF normalisation hook
│   ├── effect.ts                   # Effect step (delegates to strategy)
│   ├── fit.ts                      # Cover-fit into innerSize
│   ├── frame.ts                    # Coloured border + concentric strokes
│   ├── caption.ts                  # Top caption text
│   ├── denomination.ts             # Bottom-corner price chip
│   └── perforation.ts              # Punch transparent holes
├── rendering/
│   ├── fonts.ts                    # FontProvider, SystemFontProvider
│   └── canvas.ts                   # @napi-rs/canvas helpers
└── infrastructure/
    └── imageRepository.ts          # SharpImageRepository (load / save)

Patterns at a glance

• Strategy — EffectStrategy lets each photo effect (NoneEffect, SepiaEffect, GrayscaleEffect, VintageEffect) implement one tonal transform with a single-method interface.
• Registry — EffectRegistry and ThemeRegistry are the only places that know about all available strategies and themes; consumers ask by key.
• Pipes-and-Filters — the rendering pipeline is a sequence of StampProcessor steps that pass StampImage from one to the next.
• Composite — Pipeline implements StampProcessor, so a whole pipeline is interchangeable with a single step.
• Builder — StampPipelineBuilder hides the construction order and dependencies of the default pipeline.
• Repository — ImageRepository abstracts I/O; only SharpImageRepository knows about sharp.
• Use Case — MakeStampUseCase is the single application entrypoint and depends only on abstractions.
• Command — each CLI subcommand is its own module under cli/commands/.
• Dependency Injection — the CLI wires the registries, font provider, repository, and pipeline at the composition root and passes them down through constructors.

SOLID

| Principle | Where it shows up | | --------- | --------------------------------------------------------------------------------- | | SRP | Each pipeline step does one thing (FitProcessor resizes, FrameProcessor draws the border, etc.). | | OCP | Adding a new effect is a registry entry plus a strategy class — no other code changes. | | LSP | All StampProcessor implementations are interchangeable; Pipeline is one. | | ISP | Narrow interfaces (EffectStrategy.apply, FontProvider.fontSpec, ImageRepository.load/save). | | DIP | MakeStampUseCase depends on ImageRepository and StampProcessor interfaces, not on sharp or @napi-rs/canvas. |

Library use

import {
  defaultEffectRegistry,
  defaultThemeRegistry,
  Effect,
  makeStampSpec,
  MakeStampUseCase,
  SharpImageRepository,
  StampPipelineBuilder,
  SystemFontProvider,
} from "@ishk9/stampy";

const themes = defaultThemeRegistry();
const effects = defaultEffectRegistry();
const fonts = new SystemFontProvider();

const repository = new SharpImageRepository();
const pipeline = new StampPipelineBuilder(effects, fonts).build();
const useCase = new MakeStampUseCase(repository, pipeline);

const spec = makeStampSpec({
  theme: themes.get("classic"),
  caption: "POSTES",
  denomination: "$1",
  effect: Effect.SEPIA,
});

const result = await useCase.execute("cat.jpg", "cat-stamp.png", spec);
console.log(`wrote ${result.outputPath} (${result.width} x ${result.height})`);

A runnable version of this snippet lives at examples/library-use.ts.

Development

npm install
npm run dev -- create cat.jpg     # via tsx
npm run build && npm start -- create cat.jpg
npm test

The test suite is vitest plus tsx-style ESM resolution, so local imports keep their .js extensions even though the sources are .ts.