Sphera — Documentation

\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 the sphere above to explore.

Drag to rotate — Scroll to zoom — Press B to draw — Ctrl+Z to undo

\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

navigate mode — drag to rotate · press B to draw

\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 the sphere above to explore.

Drag to rotate — Scroll to zoom — Press B to draw — Ctrl+Z to undo

\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

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

Diff · v9