Documentation

Overview

Realness is a rotoscoping tool. With it you can trace photos into layered SVG posters with animatable mosaics, shadows, and gradients. Posters export to SVG, PNG, PSD, video, or GLB. Print layers on transparency film and stack them like Disney-era cel animation.

Everything runs on your device — no AI, just classical computer vision. Sign in to sync with a small community. What you make uploads right away; the feed catches up on an eight-hour rhythm. Or host your own Realness.

Quick start

Add Realness to your home screen.

  1. Open the app, tap the camera, and take a picture.
  2. Realness rotoscopes the photo into a vector poster: five Mosaic layers, four Shadow layers, and up to eighteen gradients pulled from the image.
  3. Write statements alongside posters to build a thought.
  4. Sign in with your phone number to sync across your devices.

Interface

The application Island lives at the bottom of your screen.

  • Add — file picker for photos you already have. One or many posters.
  • 3D — toggle the 3D viewer.
  • Camera — quick photo capture, improvisational and fun — zoom without quality loss.
  • Animation — toggle poster animation.
  • Preferences — open the preferences panel.

On desktop, paste anywhere to queue a poster—same queue as Add. Keyboard shortcuts are in Preferences.

Thoughts

Thoughts pair statements with posters. Each new entry extends the current thought, giving you 13 minutes to build on what you're thinking.

Statement input

A pill-shaped text field sits at the top of the feed. It's always visible. Tap or click to focus, type your statement, and leave the field to save. The field grows with your text. Press Tab to jump to the first poster in the feed.

Statements within 13 minutes of a poster attach as overlay captions on that poster (marked by a teal border) and don't appear separately in the feed. Text-only thoughts stand alone.

Community feed

Thoughts is a shared feed for your instance — a small circle of people, not the whole internet. There are no likes, counts, or comments. When something moves you, you text the person.

Before you sign in, Thoughts shows only the community moderator's posts. Sign in to see the full community feed and add your own.

Top left of Thoughts: a switch with three silhouettes. Red means phonebook mode — the full community feed. Tap to toggle between the phonebook and a feed of just your work.

The feed moves on an eight-hour rhythm — not a live stream. What you post on this device still goes up right away. When something moves you, text the person; Realness is not built to keep you checking back.

Statements

Text entries in the feed, grouped by day. Tap any statement to edit it in place. URLs stay as plain text, not links. Works offline without sign-in; syncs once you sign in.

Profile

Tap an avatar in the feed to open that person's profile - their posters and statements grouped by day. Download any poster. Profiles are cached offline; visits are not tracked.

Posters

Posters appear in Thoughts and on profiles, grouped by day. Use Add or Camera on the island, or paste on desktop.

Anatomy of a poster

Each poster is a layered SVG.

Mosaic — transparent cutouts from photo contrast. Five layers: Boulders, Rocks, Gravel, Sand, Sediment. In 3D view, finer layers are raised creating the illusion of dimension.

Shadow — tonal bands (lightest to boldest): Light, Regular, Medium, Bold. Background is an optional fill behind them.

Stroke — outlines along the shadow paths.

Gradients — eighteen colors from your photo, coloring the shadows.

Interactive features

  • Poster details - long-press a poster on touch, or click it on desktop, to expand its caption area. Your own posters show overlay statements, download, and set-as-avatar. Other people's posters show their profile chip and a download button.
  • Animation - GPU color transitions. Toggle and cycle speed from Preferences.
  • Drama - front and back light bars. Toggle and cycle combinations from Preferences.
  • Mosaic layers - on touch, press and hold to highlight a layer. On desktop, hover to highlight the layer under the cursor.
  • Fit or fill - long-press toggles between meet (poster inside the frame) and slice (poster fills the frame). On desktop, click.
  • Pan - in portrait slice mode, swipe left or right to move the poster within the frame.
  • Aspect ratio - cycle presets from Preferences on desktop.
  • Slice alignment - nudge the crop in slice mode from Preferences on desktop.
  • Storytelling - switch the feed to horizontal scroll from Preferences on desktop.
  • Presentation - a keyboard shortcut fills the screen with the poster and hides the interface. Press again to exit. The key is listed in Preferences.
  • Set as avatar - on your own posters, the poster details area lets you set that poster as your profile avatar.

Subjects — being built live

Your own posters have a mask pen (the ✎ in the poster menu) for grouping mosaic cells into subjects — the things in the picture, like a face, a flower, or the foreground. Press a cell and drag to grow the selection out through cells of a similar tone; press an already-selected cell and drag to erase. Pinch to zoom in for precision.

This one is being written in the open. Today you can create and color subjects on a poster, but saving them isn't wired up yet — a subject lives only for the current session. Naming, saving, and pulling a subject out as its own layer come next.

Because it's being built live, your feedback shapes it. Try the grow-select and tell me how it should feel — open an issue or say hello in About.

3D viewer

Toggle from the island or Preferences. With 3D on, tune spread, opacity, camera, atmosphere, and motion in the preferences panel.

Mobile — drag to pan. Tilt follows your finger and device gyro (when allowed).

Desktop — drag for parallax. Hold a modifier while dragging or scrolling to pan; scroll with the primary modifier to zoom; arrow keys tilt. The exact keys are listed in Preferences when 3D is on.

Vector work runs in web workers. View state persists locally.

Download and export

Open the poster menu first (long-press on touch, click on desktop). A blue sweep border means an export is running.

Exports clone the live poster on screen—not a separate render path.

  • SVG — matches what you see (visible layers, opacity, crop, drama). Any size. Turn on the adobe color preference to write HEX gradient stops that Adobe tools read correctly.
  • PNG — same flat snapshot at 3840px wide, plus a small Realness watermark.
  • PNG layers — one file per layer for compositing—not one on-screen snapshot.
  • PSD — Shadows (Background, Light, Regular, Medium, Bold), Stroke, Mosaic (Sediment through Boulders). Separate layers for printing. 1920px on touch, 3840px on desktop.
  • Video — one animation cycle as .mov, 24fps
  • GLB — 3D model for Blender and similar tools. Uses the open 3D viewer when it is on; otherwise builds from the poster.

Printing a cel animation

Posters are built for transparency. Mosaic cutouts stay clear; shadow and gradient layers stack like colored gels—made to shine through on a light table or projector. Each printed sheet is a cel: register a stack of them and you get the same layered look golden-age Disney and the other hand-painted studios used.

There are three ways to print, depending on how much of that layering you want to do by hand.

Print the whole poster. Export PNG or SVG and send the full poster to one sheet of overhead film. Every layer lands already composited—one cel, the fastest path, and the closest to what's on screen. Choose this when you want a finished image on transparency without assembling anything.

Print each layer. Export PNG layers or PSD and print one layer per sheet of transparency. PSD keeps them named and ordered for you—Shadows (Background, Light, Regular, Medium, Bold), Stroke, then Mosaic (Sediment through Boulders). This is the path for registration: trim to a common edge or use registration holes so each sheet drops into the same position.

Stack all of it together for the full experience. Print the layers, print the background on paper—it gives the shadows something to sit on—and register the transparencies on top of it in order, lightest shadow to boldest, mosaic on top. Light it from behind on a light table or projector and you're looking at a hand-built cel: the layers read as depth, and you can lift, swap, or re-shoot individual sheets the way an animation stand does.

A laser printer (toner) is the best fit for the film: sharp vector edges, opaque color where you need it, clear where you don't. Inkjet transparencies work in a pinch—let the ink dry fully before stacking.

How posters are made

No AI. Classical computer vision on your device—not machine learning or generative models. Realness doesn't do the hard part of tracing itself; it stands on two open-source projects that have spent years getting it right, and owes them the credit.

  • vtracer, by the visioncortex team — turns photo contrast into the mosaic cutouts. The five mosaic layers are vtracer's color-region tracing, tuned for the look Realness is after. It does the work that makes the layered, stained-glass quality of a poster possible.
  • potrace, by Peter Selinger — the starting point for the shadow layers. The tonal bands (Light, Regular, Medium, Bold) and the strokes along them began as potrace and have since been heavily rewritten to Realness's needs. The foundation—turning a bitmap into clean, hand-inked curves—is Selinger's; what grew from it is its own thing.

Both are the real engine of a poster. Realness is the darkroom around them—capture, layering, color, and export.

Sign-on

Sign in with your phone number and a display name. You join this instance. Your posters and statements show in Thoughts alongside everyone else.

Realness is one instance per moderator. A small community of their people. You can sign in here to try it and participate. The real community is the one you build by hosting your own for your studio, family, union hall, or circle. See Project below for setup and docs.

Realness is invisible to search engines—no tracking, no advertising. The server handles auth and storage only; your data lives on your device.

Account

Sign-in required:

  • Sign off — sign out.
  • Name — display name.

Install

Realness is a Progressive Web App — install it and it runs like a native app, offline, with full keyboard shortcuts and desktop GPU. The walkthrough below matches your device; open Other devices for the rest.

Add Realness to your dock

Works like a native app, straight from the web. macOS · Safari

Other devices

  • iPhone & iPad

  • Android

  • Chrome · Edge · Brave

  • macOS Safari

Sync

Sync runs when you return to the app or come back online.

What goes up

Posters, statements, profile changes, and anything you saved offline on this device upload as soon as you have a connection.

What comes down

Realness checks for new work once every eight hours — not more often. Open the app at noon and again at three, you will see the same feed. Open it the next morning, you will see what posted overnight.

That check brings in statements from your other devices, plus new profiles, statements, events, and posters from everyone on the instance. Your name and avatar are verified every visit; the rest waits for the eight-hour mark.

Slow on purpose. No live ticker, no reason to refresh every few minutes. Open the app, catch up, make something, leave.

When sync runs, changed profiles and statements refresh and the feed reloads. A blue sweep border around the app means sync is in progress.

Status borders

Border around the app:

  • Blue sweep — syncing, exporting, processing, or refreshing.
  • Yellow — offline; editing paused.
  • None — online and idle.

A teal border is different: it sits on a single poster (not the app frame) to mark attached caption statements — see Thoughts.

A Realness of your own

The Realness source code is available. This page documents the tool; the repo has setup, deploying your own, and some deeper background to explore.

  • README — overview, local dev, Firebase deploy.
  • Philosophy — why moderators, small communities, and client-first design.
  • Architecture — storage, sync, offline-first, serverless stack.
  • Contributing — branch workflow, tests, pull requests.
  • Verify a release — npm run verify confirms a live instance matches a GitHub release.

Preferences

Layers, geology, motion, 3D atmosphere - every poster responds to what you turn on. Reset everything to start clean.

Mosaic

mosaic

Tiles defining shape over shadowg

sediment

Finest piecesB

sand

Small piecesV

gravel

Medium piecesC

rocks

Large piecesX

boulders

Largest piecesZ

Shadow

shadow

Value layers, Light -> Boldf

background

81% luminosity fillb

light

44-60% luminosityv

regular

20-44% luminosityc

medium

10-20% luminosityx

bold

0-10% luminosityz

stroke

Outline shadows

Motion

drama

Dynamic lightingd

Dcycles lights

animate

Active backgrounds & 3d motiona

Acycles speed

Color cycle

Logo tiles cycle brand colors

View

3D

View poster in 3Dq

grid

Composition grid

info

FPS overlayi

storytelling

View each poster in a fullscreen side scrollw

Chrome

Island

Show app islandM

Changelog

v2.6.4 — July 25, 2026

  • Download menu had no surface over a poster — the poster footer styled its menus with a descendant selector and then reset background/backdrop-filter on anything nested, which caught the download sheet along with the author row. Footer menu rules are scoped to direct children now, and the bar's glass moved to a ::before so the bar stops being a Backdrop Root — nested backdrop-filter was sampling the bar instead of the poster, leaving the sheet's blur dead.
  • PNG, PSD, and layer exports cropped the poster edges — every raster path clones the live <svg>, which carries preserveAspectRatio="xMidY… slice" to fill its grid cell. slice scales to cover the target canvas, so it can only ever crop; export clones now set xMidYMid meet to fit the whole viewBox.
  • Download menu rebuilt — formats are real <button>s (focusable, Enter activates) in a column sized to its labels; the per-layer PNG export moved from an unlabelled icon buried in the corner of the PNG button to its own chip alongside it; sheet and chip slide up on the poster grid's easing curve.

v2.6.3 — July 24, 2026

  • Favicons and OG image matched to the bone-background icons — 192.png, 512.png, and og.png were still generated on the old dark surface; the generator now renders them on bone with dark text.

v2.6.2 — July 24, 2026

  • Storytelling mode trapped touch users — the poster <svg> hardcoded touch-action: pan-y, blocking the horizontal swipe storytelling scrolls on; and the footer nav (the only way to reach Preferences and turn storytelling back off) unmounted whenever storytelling was on, leaving no touch-reachable escape since the toggle is keyboard-only (w). Fixed both: posters allow horizontal pan while storytelling, and the footer stays mounted.

v2.6.1 — July 22, 2026

  • Homepage was blocked from indexing — robots.txt disallowed / with no exception for the homepage itself, and sitemap.xml never listed it. Added Allow: /$ and the homepage entry so Google can crawl and index it.

v2.6.0 — July 21, 2026

  • Build no longer rewrites public/sitemap.xml — every build regenerated it with today's date, leaving a perpetual uncommitted diff after each deploy. dist/sitemap.xml (what actually ships) is unaffected; public/sitemap.xml stays as the static checked-in copy until next touched deliberately.

v2.5.13 — July 21, 2026

  • Folder sync rebuilt — File System Access API directory handle persisted in IndexedDB, mutex-guarded queue mirrors thought/poster saves and deletes as human-readable files (date-titled thought folders, snippet-named poster SVGs/PNGs) instead of raw itemid dumps. New sync_svg preference toggles SVG export.
  • Account page rebuilt — Sync folder section (choose/re-sync, live progress, Brave detection with a how-to-enable dialog) and notifications now both live under Account, visible ahead of sign-in status resolving.
  • base-line.styl split — constants-only now; the actual reset/root-properties/fluid-type-scale CSS output moves to a new reset.styl loaded once from index.styl.
  • About hero fade — tagline and hero poster now fade/rise in with the rest of the hero instead of snapping in or sitting blank; stagger tightened so the reveal settles quickly.

v2.5.12 — July 17, 2026

  • Verifiable releases — Keep a changelog ## Unreleased (hidden on /docs until cut); npm version promotes and tags, npm run ship publishes build-manifest + notes to GitHub. Copy points skeptics at the ritual.
  • realness-design realign — views/components drop invented class hooks for markup state, rename --on-emphasis → --contrast, align with design skill conventions.
  • Markdown as an element stylesheet — content typography moved from Stylus mixin into src/style/elements/markdown.styl.
  • Notification opt-in onboarding — once per device after sign-in, a modal offers push when the instance supports it.
  • Mosaic logo smalti wobble — clipped fragment paths on each tile, paced off the glint cycle, for more physical glitter.
  • Preferences markup tidy — notifications fieldset rename, tweakpane slide simplified to attribute selectors; orphan grid.svg removed.
  • npm run verify — deploy checksum CLI defaults clarified; docs updated for independent GitHub-manifest checks.
  • Test coverage surge — ~2k net test lines across posters, profile, views, sync/persistence, potrace, and utils.

v2.5.10 — July 13, 2026

  • Codebase-wide bug-fix pass — systematic review across persistence, components, composables, workers, and 3D/potrace; fixed real bugs (mutex double-acquire, sync-queue race, tracer cross-contamination, SVG focusability, sign-in hang, textarea keymap, Three.js leaks, divide-by-zero, stalled upload queue). Every fix with a regression test.
  • Cloud archive consistency — partial poster archive failure now rolls back cleanly instead of leaving orphaned files.
  • Pricing page rewritten as real HTML — tier content hand-authored per semantic-HTML convention instead of generated from JS data.
  • Poster video export overhauled — fixed ~8x-too-fast playback, cross-fade frames, 1440p/14 Mbps encode.

v2.5.9 — July 11, 2026

  • Materials-and-roles design system — palette converted to OKLCH, materials as static CSS custom properties with derived weights, new --info role. Automated contrast/harmony guardrails.
  • /colors view — live palette renderer in-app with swatches, roles, geology demo, Depth demo.
  • Stylus → native CSS migration — element styles that don't need mixins moved to plain .css.
  • Shared focus-ring() mixin — fixed silently dropped keyboard focus indicators.
  • Realness mosaic logo — placeholder glyph replaced with mosaic mark: palette colors, smalti masks, per-tile drift, color cycle, press-to-flatten via Web Animations API.
  • Pricing split into per-tier carousel — /pricing/:tier drives tier nav, prev/next, touch swipe, all synced to URL.
  • Switched to GPL-2.0 — closed-source-license gap closed; name/logos trademarked outside GPL; commercial tiers as support contract.
  • Drag-and-drop image upload — photos and SVGs dropped onto the app queue like paste; SVGs resize through the vectorize path.
  • Small fixes: dark-mode compose caret, --basalt-transparent reference, clamp() order bug, button/checkbox style leaks, Colors header, Buy Button iframe reflow, TOC not tracked in git.

v2.5.8 — July 4, 2026

  • Instance capabilities — runtime /capabilities probe discovers optional features (push, phone integrity); falls back to shipped capabilities.json (all off). Firebase auth split into its own vendor chunk.
  • Deleted posters stay gone — cached posters no longer resurrected; remove_missing_poster purges HTML, shadow, geology layers, and cached directories on delete.
  • Root indexable — home route dropped noindex for search engines.
  • Thoughts shell drops after mount — static <h1> removed from DOM once Vue mounts.
  • Preload Lato Light — closes FCP→LCP gap from font repaint.
  • Dated poster labels — poster SVGs announce "Poster from " instead of generic "Poster".

v2.5.7 — July 4, 2026

  • Static LCP shell for home route — index.html renders <h1>Thoughts</h1> in #app at first HTML parse, gated by pathname. Placeholder <header> reserves real header height. LCP 2.0 s, performance 93, accessibility 100, CLS 0.002.
  • Poster SVG labels — role="img" + aria-label + aria-roledescription="poster"; aria-label on avatar toggle, messenger sms: link, delete button. Lighthouse accessibility 74 → 100.
  • Fonts cached a year — /fonts/** max-age=31536000, immutable.
  • Deleted posters drop from visitor feeds — missing loads no longer render blank figures.

July 3, 2026 — Removed EXIF metadata feature

  • EXIF capture + overlay removed — iOS Photos picker strips camera/date/GPS before our code runs. Deleted exif files, preference, and capture code. Rationale: docs/monopoly.md.

July 2, 2026 — Performance

  • Lazy vectorize on first paint — use_vectorize loads via dynamic import after rAF; boot imports ~80KB lighter.
  • Deferred init_serverless — Firebase auth after Vue mount to not block first paint.
  • Trimmed preconnects — removed 8 unused preconnect/dns-prefetch links; only firebasestorage.googleapis.com remains.
  • Lazy InstallGuide + PreferencesMenu — defineAsyncComponent for 242KB video and preferences panel.
  • CLS shell — #app gets min-height: 100dvh to prevent layout shift on mount.
  • Stable feed render — Thoughts rendered improved from 4.2s to ~2.7s.

July 2, 2026 — Support layout, build-time TOC, scroll & swipe

  • Support layout — site-nav rendered once by support-layout.vue replacing 5 hand-rolled copies.
  • Build-time TOC — scripts/generate-toc.js precomputes heading trees; views import static arrays instead of runtime markdown_toc().
  • Swipe-back & scroll — removed scrollRestoration = 'manual'; TOC links use router-link replace; scrollBehavior handles to.hash with smooth scroll.
  • Mobile TOC UX — larger sub-level fonts, touch-action: manipulation, heading scroll-margin-top for safe-area.
  • Pricing page — padding fixes, space between buy button and actions, removed redundant price text.

July 2, 2026 — Account, performance

  • Require a name — nameless users redirected to /account; validation on save and sign-on.
  • Lazy 3D and download — defineAsyncComponent for viewer and download in poster figures.
  • Smaller first feed page — optimize() caps each author's directory to SIZE.MAX (55).

July 2, 2026 — Discoverability & social previews

  • Open Graph cards — marketing URLs prerender with full og:* and Twitter Card tags.
  • og.png (1200×630) — social image with headline, value prop, CTA.
  • Meta tag pass — titles, descriptions, og:image:alt, twitter:image:alt.
  • Sitemap & robots — crawlable marketing pages in sitemap.xml; app shell unindexed.
  • Static docs — public/documentation.md and public/llms.txt for crawlers and LLM discovery.

July 1, 2026 — Early in the v2.5.7 cycle

  • Stripe buy buttons wired into $100/$500 pricing tiers.
  • Mask subjects — named path groups with grow-select/erase (WIP).
  • 3D mode poster menu gesture — reveal poster menu in 3D with same gesture as SVG mode.

v2.5.6 — June 29, 2026

  • Blank duplicate-poster avatars fixed — visibility-aware canonical election.
  • PSD export — stroke stripped from shadow fill layers.
  • Statement text selectable; touch callout suppressed on tappable elements.
  • "Copy prompt" agent buttons inline in docs and pricing.
  • SSR hardening — prerender and standalone guards; var(--base-line) in viewport-relative calc()s.

v2.5.5 — June 28, 2026

  • Account overhaul — inline sign-in, web push notification preference, Stripe reduced to CTA.
  • Pricing and legal pages — ToS simplified (arbitration removed), LICENSE updated, security.txt refreshed.

v2.5.4 — June 17, 2026

  • Install guide — native install prompt, platform detection, synthetic walkthrough animations (HyperFrames) for iOS/Android.

v2.5.3 — June 15, 2026

  • Big simplification — removed phonebook, relations, events, picker; simplified profile/poster menus; expanded docs.
  • Preferences menu — hints, icons, keybindings; animated silhouette toggle for only_mine feed filter.
  • About page refresh with gallery cap and lore.
  • Archive location map with self-healing sync:index.

v2.5.1–2.5.2 — June 11, 2026

  • Prerendered marketing pages and public site structure.
  • About page rebuilt — integrations, feature list, balanced gallery; archive loading fixes.
  • Frosted-glass styling consolidated; account UI polish; 3D "haze" renamed to atmosphere.

v2.5.0 — May 31, 2026

  • Mask pen drawing tool debuts.

May 16, 2026 → 05-25 — v2.4.x: 3D posters land

  • 3D poster viewer and export tooling migrated in from projects/3d; scene motion refactored with tests; device orientation handling; iOS touch/orientation polish.

2026-04 → 05 — v2.3.x: platform

  • Vite+ toolchain transition.
  • Stripe sponsorship integrated; profile account hero; homescreen icon management.
  • One poster on the page — deduplicated rendering; caching and performance work.

2026-02 → 04 — v2.0–v2.2: the Thoughts interface

  • Interface re-centered around Thoughts; navigation removed; color scheme green → blue.
  • Safari feed performance; off-screen cutout removal; feed ordering fixes.
  • Sync folder for poster output export; download-video improvements; landscape poster swipe.
  • Local dev setup simplified.

2025-10 → 2026-02 — v2.0.0: the rebuild

  • Offline/anonymous poster creation synced after sign-in; cutouts and shadows stored for later sync; PNG and PSD export alongside SVG; layer naming; dark-mode color-scheme declared.

2024 → mid-2025 — v1.5–v1.8: the on-device tracer

  • vtracer (wasm) integrated — on-device color-region tracer behind mosaic layers.
  • Offline actions merged with sign-in sync; iPad standalone detection; preferences and docs growth.

2017 → 2023 — origins

First commit December 20, 2017. Realness grew up as a phone-number-identity social PWA — profiles, avatars, statements, events, phonebook — with dark mode by 2018 and steady releases through v1.x. The poster emerged as the core creative object through experiments from 2018 to 2022. Most of that social surface was shed in 2026 (v2.5.3) to focus on posters and thoughts.