Measure any site from satellite imagery, without a site visit.
Distances, areas, to-scale tents and vehicles, will it fit? and how many fit?, all in a self-hosted web app
with an OpenAPI 3.1 REST API and an embeddable map. Zero dependencies, no build step.
Live demo · Website · Download · Quick start · Use cases · API · Embedding
Quoting a job usually means driving out with a measuring wheel. LiteMap lets you do the first pass at your desk. Look the site up, outline the usable ground, drop the actual equipment on it at true scale, and get an answer such as "a 40×80 with 5 ft clearance fits, and the largest that fits is 60×120". Then share a link, export GeoJSON or CSV, or let your CRM pull the numbers through the API.
- Accurate math. Vincenty ellipsoidal distances (under 1 mm error) and ellipsoid-scaled areas. One geodesy module runs in both the browser and the API, so their numbers always match.
- The newest imagery you can get. Overlay Esri, Esri Wayback, USDA NAIP, 3-inch county aerials, NASA GIBS, or the SkyFi commercial archive, and see the capture date of each at the map center.
- Your own objects. Upload a photo or drawing. LiteMap cuts the object out in the browser with an on-device AI model, then scales it to its real size.
- Built to integrate. A documented REST API, a Swagger UI, a
postMessageiframe API, and API-key auth. - Tiny and self-hosted. About 330 KB of readable, unminified source, Node ≥ 22.9, and no
npm install. Your data stays on your server as a JSON file.
| Measure | Distances with per-segment and running totals. Areas in ft² and acres or m² and ha, with perimeter. Vertex snapping, Alt-click to delete a vertex, and full undo. |
| To-scale objects | Frame and structure tents from 10×10 to 100×200 ft, stages, dance floors, cars, trucks, 53′ trailers, containers, lifts, dumpsters, generators, parking stalls, restrooms, tables, sports courts and fields, plus custom rectangles and circles. Set the clearance for stakes, guy lines and egress. |
| Top-down skins | Every catalog object is drawn as a to-scale top-down model: tent roofs with bays and legs, vehicles, containers, tables with chairs, and courts with regulation lines. Skins follow rotation and resizing and take the object's colour. Toggle Skins off for flat footprints. The catalog carries 90 stock tents: frame and canopy tents from 10×10 to 40×160 ft, clearspans from 50×50 to 120×300 ft, and metric clearspans from 10×10 to 40×100 m. |
| 3D tent builder | Build a tent… (Object tool, Tents section) designs a tent in an orbitable 3D preview: any width and length, pyramid, hip or gable roof, leg and peak heights, bay spacing, sidewalls per side (open, solid, windows or clear) and fabric colour, with footprint, roof fabric, sidewall length, legs, ballast blocks and interior volume worked out as you go. Placed tents reopen in the builder from the inspector. Switch on 3D to stand every tent up on the tilted map. |
| Site fit | Will it fit? finds the position and rotation with the most margin. Largest fit finds the biggest size that still fits. How many fit? packs a grid aligned to the area's edges and draws the layout. |
| Upload objects | Drop, paste, or choose an image. LiteMap cuts the object out (AI for photos, colour keying for plain backgrounds) and crops it. Click an object to choose it, or drag a box. Set a known width or length, or stretch the image to exact dimensions. |
| Imagery | Find the newest imagery at the map center. Sources include Esri World Imagery and Wayback, NAIP, county 3-inch aerials, NASA GIBS (HLS Sentinel-2 and Landsat, VIIRS), SkyFi archive search, and custom XYZ or ArcGIS layers. Enhance sharpens tiles or upscales them with AI. |
| Annotate | Pins, multi-line text boxes, freehand drawing, colours, notes, and labels you can switch off globally or per object. Show measurements pins side lengths on any shape or object. |
| Share and export | Saved sites with a link, GeoJSON, CSV, text summary, a static satellite snapshot with your measurements drawn on it, and embed code. |
| Integrate | OpenAPI 3.1 REST API, Swagger UI at /docs, an iframe embed mode with a read-only option, a postMessage API, API keys, and CORS. |
- Tent and event rentals: check that a tent, its clearance and its stakes fit before quoting, find the biggest tent a yard takes, and lay out vendor rows.
- Event planning and venues: lay out stages, bars, restrooms, generators and load-in routes, and count tables or booths for an area.
- Construction and site logistics: plan where containers, dumpsters, lifts and trailers go, measure laydown yards and truck access.
- Landscaping, fencing, paving and roofing: measure square footage and linear feet for quotes, and compare before and after with dated imagery.
- Real estate and property management: measure lots, parking capacity and usable outdoor space.
- Pools and outdoor builds: check fit and setbacks, and confirm what's on the ground with the newest imagery.
- Field sales and CRM: create a site from an address via the API, measure it, and store the numbers on the deal.
Requirements: Node.js 22.9 or newer and a free Mapbox access token (a public pk.… token).
git clone https://github.com/248Tech/litemap.git
cd litemap
cp .env.example .env # then put your Mapbox token in .env: MAPBOX_TOKEN=pk.…
npm start # → http://localhost:8787There's nothing to install: no dependencies, no build. Run npm test for the geodesy and API test suite.
Or download the latest release, unzip it, and run the same cp and npm start steps.
| URL | What |
|---|---|
/ |
Mapping app |
/?site={id} |
Open a saved site |
/?embed=1&site={id} |
Embeddable view (add &readonly=1 for view-only) |
/docs |
Interactive API docs (Swagger UI) |
/openapi.json |
OpenAPI 3.1 spec for client code generation |
/examples/embed.html |
Live postMessage integration demo |
docker build -t litemap .
docker run -d -p 8787:8787 -e MAPBOX_TOKEN=pk.your_token -v litemap-data:/data litemapLiteMap is a single Node process with a data folder, so any VM, container host or PaaS works (Render, Fly.io, Railway, a VPS with systemd or pm2). Put it behind HTTPS and set:
PUBLIC_URLso the links returned by the API are correct;LITEMAP_API_KEYto require a key on the API;CORS_ORIGINSto limit which sites can call it.
Keep DATA_DIR on persistent storage.
The browser gets the token from GET /api/v1/map/config and uses it for satellite tiles and search. The server uses the same token for /geocode, /snapshot and site address lookups. If you add URL restrictions to the token, include every origin that serves LiteMap, and set MAPBOX_SERVER_TOKEN to an unrestricted token: server-side calls send no browser Referer, so a URL-restricted token can fail for them.
| Tool | Key | Notes |
|---|---|---|
| Select | V |
Click shapes to edit. Drag vertices, drag a midpoint to insert a vertex, and Alt-click a vertex to delete it. |
| Distance | D |
Click points. Click the last point or press Enter to finish. Live segment and running totals are shown. |
| Area | A |
Click points, then click the first point or press Enter to close. Shows area (ft² and acres, or m² and ha) and perimeter. |
| Pin | P |
Named marker with editable lat/lon. |
| Object | R |
Place a to-scale object from the catalog. A ghost preview follows the cursor. |
| Upload object | U |
Turn a photo or drawing into your own to-scale object. You can also drop an image anywhere on the map. |
| Text | T |
Click to place a text box, then type in the panel. Supports multiple lines, size, colour, and an optional dark background. Drag the box to move it. |
| Draw | B |
Freehand pen with colour and width. The map doesn't pan while drawing, and strokes are simplified on save. |
| Imagery | I / E |
I flips between the overlay and Mapbox; E toggles Enhance. |
| Undo / Fit all | Ctrl+Z / F |
Full edit history; zoom to everything. |
New points snap to existing vertices within 10 px. Hold Alt to place a point without snapping.
Reference objects resize from the corner handles (Shift keeps proportions) and rotate with the ↻ handle (Shift snaps to 15°). You can also type exact width, length, scale %, rotation and clearance.
Site fit (select an object, with an area drawn):
- Will it fit? places the object, plus its clearance, where it has the most margin and reports the tightest gap.
- Largest fit finds the biggest uniform scale that still fits, for example "the biggest tent this lot takes is 60×121 ft".
- How many fit? grid-packs copies aligned to the area's edges and draws the layout, for parking capacity, table counts or tent rows.
Drop, paste (Ctrl+V) or choose an image. Top-down views work best: plan drawings, drone or aerial shots, product renders. LiteMap isolates and crops the object in your browser:
- Auto picks the method. Transparent images keep their alpha. Plain or uniform backgrounds are flood-filled away from the edges. Photos go through an on-device salient-object model (U²-Net
u2netp, 4.5 MB). It makes a normal and a mirrored pass on several CPU threads, then a guided filter snaps the mask to the real edges. A photo takes about 5–15 s the first time and about 1 s for later tweaks, with live progress on screen. - Click the object to choose it; if the AI overlooked it, LiteMap looks again zoomed in around the click. Or drag a box around it. Fine-tune with Sensitivity, Main object only, Smooth edges, or Crop only.
- Rotate 90° sets the front: the image's top edge faces the object's rotation, so 0° is north.
- Enter one real dimension and Keep proportions fills in the other, or untick it to stretch the image to an exact width × length.
Saved objects appear under My objects in the catalog and can be reused on any site. On the map the picture is pinned to the footprint's corners, so it moves, rotates and scales with the handles, and works with all the site-fit tools.
Open /modeler (menu ⋯ → 3D Modeler, or the 3D Modeler button in the Tents list) for a full-page 3D workspace. It has the same controls as the tent builder: size, roof, leg and peak heights, bays, sidewalls and fabric. It adds a Ballast switch (a steel plate with two concrete blocks at every leg), the quantities for a quote, and an export pipeline:
- Save to LiteMap stores the model as an editable recipe in your library (
data/models.json). - Place on map opens the map with the model armed for placement. It is an ordinary tent on the site (size,
reference.tentand colour), so it stays to scale, works with Will it fit? and How many fit?, and stands up in 3D when the 3D switch is on. Saved models also appear under My models in the catalog. - Download .glb writes a glTF 2.0 binary for Blender, three.js, Windows 3D Viewer and similar tools (metres, +Y up, ground at y = 0, footprint centred, front toward +Z; clear walls and window panes are blended). The recipe is embedded in the file, so Import… can bring it back for editing. Download model file gives the same recipe as
.litemap-model.json, which is also what you POST to/api/v1/models.
Ballast is a map-wide display switch (Ballast next to Skins); a model's own ballast setting applies to its .glb and to the Modeler preview.
Try it online, without installing anything: 248tech.github.io/litemap/app/modeler.html.
The website and its live demo are built by node scripts/build-pages.mjs into _site/ and deployed by .github/workflows/pages.yml. The demo is the real app with public/js/demo-api.js answering the REST API in the browser (sites and models live in the visitor's localStorage; uploads, imagery dates and snapshots need a server). Set a public Mapbox token as the MAPBOX_TOKEN repository secret, ideally URL-restricted to your Pages domain. To preview locally: node scripts/build-pages.mjs --env (reads .env), then serve _site/.
Put your own objects in data/catalog.json (for example your company's tent line) and restart. They show first in the object list and in the builder's stock sizes, and the API accepts them. Sizes are in metres. Ids that start with tent- get tent skins, the 3D view and the builder, and tent sets that tent's roof, heights, bays and walls:
{ "items": [
{ "id": "tent-acme-40x60-hip", "category": "Our tents", "name": "40×60 ft hip clearspan",
"width": 12.192, "length": 18.288, "tent": { "roof": "hip", "eave": 2.44, "walls": { "back": "solid" } } }
] }data/ is git-ignored, so the list stays private.
Imagery providers update on different schedules, so one map can show a pool still being dug while another shows it finished and filled. The Imagery panel overlays other sources on top of Mapbox, and Find the newest imagery here ranks them by actual capture date at the map center (also available as GET /api/v1/imagery/dates?lon=&lat=).
| Source | Resolution | How current | Notes |
|---|---|---|---|
| Esri World Imagery | ≈30–60 cm | Several updates a year; the date is looked up per location | Often the newest free high-res source |
| Esri Wayback | ≈30–60 cm | Every Esri release since 2014 | What a site looked like before |
| USDA NAIP | 60 cm | Every 2–3 years | Contiguous US |
| County aerials (e.g. Oakland County, MI) | 3 in (7.6 cm) | Annual or biennial spring flights | Sharpest by far; shown only where the county has coverage |
| NASA GIBS (HLS Sentinel-2 and Landsat, VIIRS) | 30 m / 375 m | Every few days | Coarse; good for clearing, large builds, flooding |
| SkyFi archive (optional) | 30–50 cm | Commercial captures | Free search with date, cloud cover and price estimate; you order in SkyFi |
| Custom | any | Any XYZ template or ArcGIS ImageServer/MapServer URL |
Enhance (E) has two modes for zooming past the native resolution:
- Sharpen uses only real pixels: de-blocking, Lanczos-3 resampling and an unsharp mask. It's safe to measure on.
- AI super-resolution (beta) runs Real-ESRGAN in the browser. It makes edges crisper but can invent plausible detail, so use it to read a scene, not to take measurements.
Add your own county service for everyone by appending an entry to public/js/imagery.js. Enable SkyFi by adding SKYFI_API_KEY= to .env.
Licensing: Esri World Imagery and Wayback are free to view, but Esri's terms require an ArcGIS account for production use outside ArcGIS. NAIP and NASA GIBS are public domain. County imagery follows each county's open-data terms.
Pick the Imagine tool (G), choose 1×1 to 4×4 map tiles (a dashed box shows exactly which ones; pan or click the map to move it), describe what you want, and an AI redraws that area in place of what's there. The result is saved as a to-scale object pinned to the tiles, so you can fade it with the opacity slider, move it, delete it, or keep it with the site. Add OPENAI_API_KEY= to .env to turn it on (the model is gpt-image-1, changeable with OPENAI_IMAGE_MODEL). The satellite picture of the selected tiles and your prompt are sent to OpenAI and each render is billed to your key, so set LITEMAP_API_KEY before exposing the server. The result is an illustration, not survey data. It is not available in the online demo.
The math is effectively exact. Distances use Vincenty's formula; areas use an ellipsoid-scaled local plane, with authalic-sphere excess for very large shapes. In practice the imagery is the limit: satellite imagery is typically within about 1–3 m horizontally, can be a year or more old, and shows some building lean. Treat results as quote-grade, not survey-grade, and verify critical clearances (property lines, overhead lines, slope) before installing.
Every endpoint is under /api/v1. The full schema is at /openapi.json and the interactive docs are at /docs.
- Coordinates are GeoJSON
[lon, lat]. - Units are meters and m².
- Rotation is degrees clockwise from north along the object's length axis.
If LITEMAP_API_KEY is set, send X-API-Key: <key> or Authorization: Bearer <key>.
| Method & path | Purpose |
|---|---|
GET /health |
Status and configuration |
GET /map/config |
Public Mapbox token and style IDs |
GET /geocode?q= |
Address search (Mapbox Geocoding v6) |
GET /reference-objects |
Object catalog |
GET/POST /objects |
List or upload your own objects (PNG, WebP or JPEG up to 8 MB; ?name=&width=&length= in meters) |
GET/PATCH/DELETE /objects/{id} · GET /objects/{id}/image |
Object metadata, and the public, immutable image |
GET/POST /models · GET/PATCH/DELETE /models/{id} |
Saved 3D tent models from the 3D Modeler (the body is the model fields or an exported litemap-model file) |
GET /models/{id}/glb |
The model as a glTF binary (model/gltf-binary) |
GET /imagery/sources · GET /imagery/dates |
Imagery catalog · capture dates at a point, newest first |
POST /imagery/skyfi/archives |
Search SkyFi's archive for an area (no ordering) |
POST /measure |
Metrics for any Geometry, Feature or FeatureCollection |
POST /footprint |
Generate a to-scale object polygon |
POST /fit |
Will it fit? (findLargest: true also returns the maximum size) |
POST /pack |
How many fit? |
GET/POST /sites · GET/PUT/PATCH/DELETE /sites/{id} |
Sites (create from an address; free-form metadata and tags) |
GET/POST /sites/{id}/features · GET/PUT/DELETE /sites/{id}/features/{fid} |
Measurements |
GET /sites/{id}/geojson · GET /sites/{id}/snapshot |
GeoJSON download · static satellite image URL with measurements drawn |
# Create a site from an address, with your own CRM id
curl -X POST localhost:8787/api/v1/sites -H 'Content-Type: application/json' -d '{
"name": "Smith wedding", "address": "1200 W 55th St, Kansas City, MO",
"metadata": { "quoteId": "Q-1042" }
}'
# Will a 40×80 tent with 5 ft (1.524 m) clearance fit in a drawn area? What's the biggest that fits?
curl -X POST localhost:8787/api/v1/fit -H 'Content-Type: application/json' -d '{
"siteId": "SITE_ID", "featureId": "AREA_ID",
"templateId": "tent-40x80", "clearance": 1.524, "findLargest": true
}'
# Parking capacity of a lot
curl -X POST localhost:8787/api/v1/pack -H 'Content-Type: application/json' -d '{
"polygon": { "type": "Polygon", "coordinates": [[[-94.581,39.101],[-94.579,39.101],[-94.579,39.100],[-94.581,39.100]]] },
"templateId": "parking-stall"
}'
# Upload a cut-out (12.192 m = 40 ft wide) and place it on a site
curl -X POST 'localhost:8787/api/v1/objects?name=Frame%20tent&width=12.192' -H 'Content-Type: image/png' --data-binary @tent.png
curl -X POST localhost:8787/api/v1/sites/SITE_ID/features -H 'Content-Type: application/json' -d '{
"type": "Feature",
"properties": { "reference": { "objectId": "OBJECT_ID", "width": 12.192, "length": 24.384, "center": [-94.58, 39.1], "rotation": 30 } }
}'Generate a typed client with any OpenAPI generator:
npx @openapitools/openapi-generator-cli generate -i http://localhost:8787/openapi.json -g typescript-fetch -o client<iframe src="https://maps.example.com/?embed=1&site=SITE_ID&origin=https://crm.example.com"
width="100%" height="600" style="border:0"></iframe>Passing origin= pins both the postMessage target and the accepted sender. See public/examples/embed.html for a working demo.
| Send to the iframe | Payload |
|---|---|
litemap:loadSite |
{ siteId } |
litemap:setFeatures |
{ features: FeatureCollection, zoom? } |
litemap:addFeature |
{ feature, select?, zoom? } |
litemap:removeFeature / litemap:selectFeature |
{ featureId } |
litemap:setView |
{ center: [lon,lat], meters? | zoom?, bearing?, mapType? } |
litemap:fitAll, litemap:save |
(none) |
litemap:setUnits |
{ units: 'imperial' | 'metric' } |
litemap:setTool |
{ tool: 'select' | 'distance' | 'area' | 'marker' | 'reference' } |
litemap:getState |
{ requestId? }, which replies with litemap:state |
| Received from the iframe | Payload |
|---|---|
litemap:ready |
{ siteId, readonly } |
litemap:change |
{ siteId, dirty, features, totals } (debounced) |
litemap:select |
{ featureId } |
litemap:saved |
{ siteId, site } |
litemap:state |
{ requestId, site, view, features, totals } |
litemap:error |
{ requestId, message } |
| Variable | Default | Description |
|---|---|---|
MAPBOX_TOKEN |
Public Mapbox token (required) | |
MAPBOX_SERVER_TOKEN |
MAPBOX_TOKEN |
Token for server-side geocoding and static images |
LITEMAP_AUTO_ADDRESS |
1 |
Look up each site's street address from its location on save (Mapbox reverse geocoding). 0 turns it off; typed addresses always work |
SKYFI_API_KEY |
Enables SkyFi archive search | |
OPENAI_API_KEY |
Enables AI Imagine (tiles redrawn from a prompt) | |
OPENAI_IMAGE_MODEL |
gpt-image-1 |
OpenAI image-edit model AI Imagine uses |
PORT / HOST |
8787 / 0.0.0.0 |
Listen address |
PUBLIC_URL |
from the request | Base URL for links in API responses |
DATA_DIR |
./data |
Sites (sites.json) and uploaded objects |
LITEMAP_API_KEY(S) |
Comma-separated API keys; when set, the API requires one | |
CORS_ORIGINS |
* |
Comma-separated origins allowed to call the API |
server/ zero-dependency Node HTTP server
app.js routing, handlers, static files
features.js validation and normalization of sites and features
objects.js uploaded-object library
models.js 3D model library (3D Modeler)
imagery.js capture-date lookups, SkyFi client
mapbox.js geocoding and static images
openapi.js OpenAPI 3.1 document
store.js atomic JSON-file storage
public/ the web app (plain ES modules, no build)
js/app.js UI on Mapbox GL JS
js/geo.js geodesy, fit and pack (shared with the server)
js/references.js object catalog (shared with the server)
js/modelfile.js litemap-model document and .glb export (shared with the server)
js/modeler.js 3D Modeler page (modeler.html)
js/imagery.js imagery catalog (shared with the server)
js/*-worker.js tile enhancement and object cut-out (Web Workers)
models/ ONNX weights (Real-ESRGAN, U²-Net u2netp)
docs/ project website (GitHub Pages)
test/ node:test suites
Storage is a single JSON file written atomically, which is fine for thousands of sites. To scale beyond that, swap server/store.js for SQLite or Postgres; its interface is five methods.
- The Mapbox token you configure is a public browser token by design. Restrict it to your domains in your Mapbox account.
- Set
LITEMAP_API_KEYbefore exposing the API to the internet, and setCORS_ORIGINS. - Uploaded object images are served from unguessable, public URLs so that maps and embeds can show them. Listing, editing and deleting objects require the API key.
- AI Imagine is the one feature that sends data out: the selected tiles' satellite picture and your prompt go to OpenAI, only when you press Imagine and only if the server has an
OPENAI_API_KEY. - Object cut-out and AI enhancement run entirely in the browser. Images are only sent to your server when you save.
See SECURITY.md to report a vulnerability.
Issues and pull requests are welcome; see CONTRIBUTING.md. Please run npm test before submitting.
MIT © 2026 248Tech. Bundled model weights keep their own licenses (Apache-2.0 and BSD-3-Clause); see THIRD_PARTY_NOTICES.md. Map data and imagery are © their providers and subject to their terms.



