Sphera — Documentation

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}","deleted","label",[102],"permalink","https://www.val.town/x/williamjaesunkang/untitled-3645/code/sphera.ts","extension","actionData","errors"]