Sphera — Documentation

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_166":167,"_168":169},"routes/_app.x.$handle.$name",{"_95":94,"_33":46,"_103":85,"_28":104,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":27,"_118":119,"_120":25,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_44":45,"_33":46,"_39":47,"_48":-5,"_49":27,"_50":51,"_52":51,"_53":-5,"_54":-5,"_18":55,"_56":-5,"_57":27,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":-5,"_67":-5,"_68":69,"_70":69,"_71":72,"_73":72,"_74":72,"_75":69,"_76":69,"_77":78,"_79":80,"_81":82,"_83":27},"version",20,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":27,"_28":29,"_30":29},"file",{"_31":32,"_33":29,"_34":38,"_36":37,"_39":40,"_41":14,"_42":43,"_24":27},"previous",{"_31":32,"_33":29,"_34":35,"_36":37},"deleted",true,"deletedHere",false,"path","new-file-7490.ts","latestPath","fileId","97e93b52-2e16-11f1-9dd0-42dde27851f2","name","fileType","script","content","/**\n * sphera.ts\n * ---------\n * Val.town HTTP handler for the Sphera interactive documentation page.\n *\n * Sphera is a 3D sphere canvas that lets users rotate a globe freely and\n * draw geodesic brush strokes directly onto its surface.\n *\n * Features\n * --------\n * - Orthographic sphere rendering via the HTML5 Canvas 2D API\n * - Arcball-style rotation (drag) and zoom (pinch / scroll)\n * - Middle-mouse or two-finger pan to reposition the sphere\n * - Geodesic stroke drawing with configurable colour and thickness\n * - Brush settings panel that slides in from the right edge\n * - Full trackpad support: two-finger swipe rotates, pinch zooms\n * - Canvas export as PNG\n *\n * Coordinate conventions\n * ----------------------\n * - All mouse/touch positions are in CSS pixels throughout.\n * - The sphere is projected orthographically onto the canvas centre.\n * - rotY = yaw (rotation around world Y-axis, applied first).\n * - rotX = pitch (rotation around local X-axis, applied after yaw).\n * - Spherical coords: theta = longitude [-π, π], phi = latitude [-π/2, π/2].\n */\n\nexport default async function handler(_req: Request): Promise {\n return new Response(buildHTML(), {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n}\n\n// =============================================================================\n// HTML template\n// =============================================================================\n\nfunction buildHTML(): string {\n return `\n\n\n \n \n Sphera — Documentation\n \n \n \n\n\n\n\n\n\n\n

\n\n

\n navigate mode — drag to rotate · press B to draw\n

\n\n

\n\n \n

\n \n brush\n

\n\n \n

\n \n\n \n

colour

\n custom\n \n

\n\n \n

thickness

\n thin\n 3px\n thick\n

\n \n

\n\n \n

\n scroll for docs\n

\n \n

\n\n

\n\n\n

\n\n \n\n

\n\n

Draw anywhere on a sphere

\n Sphera is an interactive 3D canvas. Rotate freely, zoom in, and paint\n directly on the sphere surface — strokes follow the curvature in real time.\n

\n Drag to rotate — two-finger swipe on trackpad —\n pinch to zoom — press B to toggle draw mode.\n

\n\n

Quickstart

import { Sphere } from 'sphera';\n\nconst sphere = new Sphere(canvas, {\n  radius:   1.0,\n  showGrid: true,\n});\n\nsphere.mount();\nsphere.useTool('brush', { color: '#ff9057', size: 4 });

\n Install via npm install sphera or include the CDN script tag.\n Mount on any <canvas> element.\n

\n\n

Core concepts

\n Every point on the surface is described by θ (longitude,\n −180°…180°) and φ (latitude, −90°…90°). Pointer events cast\n a ray from the camera through the pixel and intersect it with the sphere.\n The intersection is un-rotated back to local sphere coordinates and stored\n as { theta, phi }.\n

\n Strokes are sequences of geodesic segments — the shortest paths between\n consecutive sample points on the sphere's surface. All drawing composites\n into a 4096×2048 equirectangular texture atlas; only dirty tiles are\n re-uploaded to the GPU per frame.\n

\n\n \n\n

Drawing tools

Brush BFreehand strokes, anti-aliased, pressure-sensitive with a stylus

Eraser EComposite-level mask — non-destructive, strokes remain in memory

Fill F Flood-fill a closed region on the sphere surface

Stamp S Circles, rectangles, arrows — projected onto the sphere

Text T Raster labels; double-click to edit — new in v1.4

\n\n

Layers

const layer = sphere.layers.add({\n  name:      'annotations',\n  opacity:   0.8,\n  blendMode: 'multiply',\n});\n\nsphere.layers.setActive(layer.id);

\n Supported blend modes: normal, multiply,\n screen, overlay, darken,\n lighten. Use sphere.layers.flatten([id1, id2])\n to merge layers and reduce GPU upload overhead.\n

\n\n

Sphere — constructor options

radius number World-unit radius. Default 1.0.

background string Canvas background colour.

showGrid boolean Latitude/longitude grid overlay. Default false.

zoomMax number Maximum zoom multiplier. Default 50.

textureSize number Atlas width in pixels — must be a power of two. Default 4096.

antialias boolean Enable MSAA antialiasing. Default true.

\n\n

Brush — properties

color string CSS colour value. Read/write.

size number Stroke width in equator pixels at 1× zoom. Range 0.5–200.

opacity number Stroke opacity 0–1, composited with layer opacity.

smoothing number Smoothing factor 0–1. Higher values produce smoother but laggier strokes.

isDrawing boolean Read-only. true while a stroke is in progress.

\n\n

Events

ready WebGL context initialised; safe to call all API methods.

stroke:start Payload: { point, layerId }.

stroke:end Complete Stroke object: id, points, style, bounds, timestamp.

rotate Payload: { theta, phi }. Throttled to 60 fps.

zoom Payload: { level }.

error Internal error — always attach a handler for this event.

\n\n

Export & share

PNG sphere.toDataURL('png') — full equirectangular texture atlas.

OBJ sphere.exportOBJ({ segments: 128 }) — UV-mapped mesh with diffuse texture.

JSON sphere.toJSON() / sphere.fromJSON(data) — full vector state, typically 10–100× smaller than PNG.

\n Prefer JSON for save/load workflows and PNG when sharing with external\n tools such as Blender or Photoshop.\n

\n\n

Keyboard shortcuts

Toggle draw / navigate mode B

Eraser / Fill / Stamp / Text E F S T

Brush size up / down ] [

Undo / Redo Ctrl+Z Ctrl+Shift+Z

Reset camera Home

Toggle grid G

Constrain to straight line Shift (hold while drawing)

\n\n

\n\n\n\n`;\n}","http","createdAt",["D",1775081018843],"branchVersion","branchId","44dfdd40-2523-11f1-8829-42dde27851f2","id","44de8468-2523-11f1-8829-42dde27851f2","sphera-project",["D",1774096883470],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","imageUrl","019c1c74-7b88-71cc-8562-fbd34a3494d5","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","019c1c74-7b88-71cc-8562-fcd1274ee4eb","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_95":94,"_102":98},"org",{"_95":94,"_96":-5,"_97":98,"_18":55,"_99":100,"_101":27},"branch",{"_13":84,"_33":85,"_44":43,"_86":45,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":46,"_93":94},"isOwned",32,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","williamjaesunkang","handle","displayName","avatar","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/3b63dd6d-c869-4d45-4ab3-174597d14500/square512?exp=1789588799&sig=9f79b0c98e2960e1c702e7a1b972951439813121346e33854adf9de2889d338b","tier","free","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_44":45,"_33":46,"_39":162,"_48":-5,"_49":27,"_50":51,"_52":51,"_53":-5,"_54":-5,"_18":55,"_56":-5,"_57":27,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":-5,"_67":-5,"_68":69,"_70":69,"_71":72,"_73":72,"_74":72,"_75":69,"_76":69,"_77":163,"_79":164,"_81":165,"_83":27},"tree",[153,154],"files",[153,154],"counts",{"_142":61,"_143":144,"_145":61,"_146":147,"_148":149},"contents",[125,126],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_44":138,"_33":29,"_31":32,"_130":-5,"_42":43,"_41":14,"_132":27,"_39":139,"_13":140,"_34":38,"_36":37,"_24":27,"_136":-5,"_28":141},{"_44":127,"_33":128,"_31":129,"_130":-5,"_42":43,"_41":131,"_132":27,"_39":133,"_13":134,"_34":38,"_36":135,"_24":27,"_136":-5,"_28":137},"9d0c8e50-2e15-11f1-ae9c-42dde27851f2","sphera.ts","46bebfbe-2e0b-11f1-8474-42dde27851f2","parentId",17,"latest",["D",1775080578910],12,"export default async function handler(req: Request): Promise {\n const html = `\n \n\n\n\n\n\n\nSphera — Documentation\n\n\n\n\n\n\n\n\n

navigate mode — drag to rotate · press B to draw

\n\n \n

\n \n brush\n

\n\n \n

\n \n\n

colour

\n custom\n \n

\n\n

thickness

\n thin\n 3px\n thick\n

\n \n

\n\n

\n scroll for docs\n

\n \n

\n\n

\n start\n \n \n \n features\n \n \n \n api\n \n \n \n more\n \n \n

\n\n

Draw anywhere on a sphere

Sphera is an interactive 3D canvas. Rotate freely, zoom in, and paint directly on the sphere surface — strokes follow the curvature in real time.

Drag to rotate — two-finger swipe to rotate on trackpad — pinch to zoom — press B to toggle draw mode.

\n\n

Quickstart

import { Sphere } from 'sphera';\nconst sphere = new Sphere(canvas, {\n  radius: 1.0, showGrid: true,\n});\nsphere.mount();\nsphere.useTool('brush', { color: '#ff9057', size: 4 });

Install via npm install sphera or drop the CDN script. Mount on any <canvas> element.

\n\n

Core concepts

Every point on the surface is described by θ (longitude, −180°…180°) and φ (latitude, −90°…90°). Clicks cast a ray from the camera and intersect the sphere — strokes are sequences of geodesic segments, the shortest paths between sample points on the surface.

All drawing composites into a 4096×2048 equirectangular texture atlas; only dirty regions are re-uploaded to the GPU.

\n\n \n\n

Drawing tools

Brush BFreehand, anti-aliased, pressure-sensitive with stylus

Eraser EMasks strokes at composite level; non-destructive

Fill FFlood-fill closed regions on the sphere surface

Stamp SCircles, rects, arrows — warped to sphere surface

Text TRaster labels, editable by double-click — new in v1.4

\n\n

Layers

const layer = sphere.layers.add({\n  name: 'annotations', opacity: 0.8,\n  blendMode: 'multiply',\n});\nsphere.layers.setActive(layer.id);

Blend modes: normal multiply screen overlay darken lighten. Flatten layers with sphere.layers.flatten([id1, id2]) for performance.

\n\n

Sphere — constructor options

radiusnumberWorld-unit radius. Default 1.0

backgroundstringCanvas background colour

showGridbooleanLat/lon overlay. Default false

zoomMaxnumberMax zoom multiplier. Default 50

textureSizenumberAtlas width px, power of two. Default 4096

antialiasbooleanMSAA. Default true

\n\n

Brush — properties

colorstringCSS colour. Read/write.

sizenumberWidth in equator px at 1× zoom. Range 0.5–200.

opacitynumber0–1. Composited with layer opacity.

smoothingnumber0–1. Higher = smoother but laggier.

isDrawingbooleanRead-only. True while stroke is in progress.

\n\n

Events

readyWebGL context initialised

stroke:start{ point, layerId }

stroke:endFull Stroke object — id, points, style, bounds, timestamp

rotate{ theta, phi } — throttled to 60 fps

zoom{ level }

errorInternal error — always handle this

\n\n

Export & share

PNGsphere.toDataURL('png') — equirectangular atlas

OBJsphere.exportOBJ({ segments: 128 }) — mesh + texture

JSONsphere.toJSON() / sphere.fromJSON(data) — full vector state

Use JSON for save/load, PNG for sharing with external tools like Blender or Photoshop.

\n\n

Keyboard shortcuts

Brush / Eraser / Fill / Stamp / TextB E F S T

Brush size up / down] [

Undo / RedoCtrl+Z Ctrl+Shift+Z

Reset viewHome

Toggle gridG

Temp navigate while drawingAlt hold

Straight line snapShift hold

\n\n

\n\n\n\n`;\n\n return new Response(html, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n}","label",[128],"a3457286-2e16-11f1-83a2-42dde27851f2",["D",1775081018843],2,[29],"pulls","branches",1,"forks","envVars",{"_150":61,"_152":61},"connections",{"_150":61,"_151":61},"count","unfilledCount","emptyCount",{"_44":138,"_33":29,"_31":32,"_130":-5,"_42":43,"_41":14,"_132":27,"_39":159,"_13":140,"_34":38,"_36":37,"_24":27,"_136":-5,"_156":160,"_28":161},{"_44":127,"_33":128,"_31":129,"_130":-5,"_42":43,"_41":131,"_132":27,"_39":155,"_13":134,"_34":38,"_36":135,"_24":27,"_136":-5,"_156":157,"_28":158},["D",1775080578910],"children",[],[128],["D",1775081018843],[],[29],["D",1774096883470],{"_95":94,"_102":98},{"_95":94,"_96":-5,"_97":98,"_18":55,"_99":100,"_101":27},{"_13":84,"_33":85,"_44":43,"_86":45,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":46,"_93":94},"ctx",{"_77":-5,"_122":199,"_200":201,"_202":203,"_204":27,"_205":27,"_206":27,"_207":25,"_208":-5,"_209":-7,"_210":-7,"_211":61,"_212":27,"_213":27,"_214":-5,"_215":27,"_216":27,"_217":27,"_218":-5},"ENV",{"_170":171,"_172":173,"_174":85,"_175":176,"_177":178,"_179":180,"_181":182,"_183":184,"_185":186,"_187":188,"_189":190,"_191":192,"_193":194,"_195":196,"_197":198},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","fdb67791413f4386b4dbf18f354029a617f6160f","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v20