Skip to content

Helpers

Pages that prepare the files the manager asks for and clean up the results. They run in the browser. Each opens with a short form and a link to try it with sample data; after loading, the form folds into a line at the top of the side panel, and Change opens it again. While a helper is working, a spinner shows next to its status line, and Loading map... shows at the top left of the map until the map has finished drawing. Large results files, such as the Pemba Island fishing boat project, take several seconds to read.

  • Area finder

    Paste an image from imagery.hotosm.org, or open merged images from the imagery merger. Download the imagery footprint or shapes you draw as the area of interest, and save a cover image.

  • Tutorial builder

    Load the project's processed tasks, click tiles and cells to mark the tutorial answers, and download the scenario file.

  • Imagery merger

    Add two or more images from imagery.hotosm.org. Get one tile URL that shows them all, and check it on the map.

  • Results map

    Paste the link of a finished project, set the share of volunteers a cell needs, and download the cells as GeoJSON.

  • Auto labeller

    Paste the link of a finished project, tap or drag around each group of objects on the tiles volunteers marked, and download a YOLO dataset with a GeoJSON of the labels.

  • Labels checker

    Open a labels.geojson before you deliver it. The checker lists what passes and what to fix, counts the labels per type, and shows them over the imagery.

The area finder and the tutorial builder are explained step by step in Create a Locate project and Create the tutorial.

Imagery merger

Use it when the project area needs more than one image.

Two Banepa images merged, zoomed in, and the tile URL copied

  1. Copy the page address or Copy TMS of each image on https://imagery.hotosm.org/browse, as in step 1 of Create a Locate project.
  2. In the imagery merger, paste one image per field under Images. Add image adds a field and Remove drops one. Click Merge.
  3. Zoom in where the images meet. Each image has a red outline, and the list on the right shows its date.
  4. Click Copy tile URL and use it in the manager and in the tutorial builder.
  5. Click Open in area finder to find the footprint of all the images and draw the area of interest across them.

Try the Banepa example merges two images over Banepa, Nepal.

How the tile URL merges the images

The tile URL lists the image IDs (/raster/collections/openaerialmap/tiles/...?ids=<id>,<id>), and the HOT imagery API merges those images on every tile request (titiler-pgstac documentation). To change the mosaic, edit the IDs in the URL.

  • Where images overlap, the newest is drawn on top: pgstac sorts items by datetime descending by default (source).
  • The URL sets exitwhenfull=false and skipcovered=false, so an older image still fills the parts of a tile where a newer image doesn't have pixels.
  • White or near-black edges of a newer image are drawn on top of older imagery. When they hide what volunteers need to see, leave that image out.

Results map

Use it on a finished project to get only the cells volunteers marked, as GeoJSON.

Kept cells, a cell's votes, and the download button

  1. In the results map, paste the project link, the address of the project page on the MapSwipe website (see Download the results), and click Load.
  2. Move the Volunteer share slider to the share of volunteers a cell needs, for example 50%. Click a cell to see its votes.
  3. Click Download cells. Label in QGIS and Label in OpenStreetMap continue from this file.

To share the results, copy the page address. It opens at 50%, so tell others the share you used.

Try the Freetown example loads the Freetown solar panel project.

Projects not on the website

The MapSwipe website lists production projects, and the stage website (https://website-stage.mapswipe.org/) some stage projects; links to both work. The websites are rebuilt every six hours (source). For a project not on the website yet, paste its Aggregated Results link (https://backend.mapswipe.org/...csv.gz or https://backend-stage.mapswipe.org/...csv.gz) from the MapSwipe API in the same field.

How cells are kept, and the downloaded properties

A cell is kept when Single Feature and Multiple Features answers together make up at least the chosen share of the volunteers who saw it. Each kept cell becomes a square, cut from its tile row by row from the top left in Web Mercator, the projection the tiles are cut in (source). On the map, Multiple Features cells have the darker fill.

Property Meaning
tile_id The tile, as zoom-x-y (the task_id of the results)
cell_index The cell inside the tile, counted row by row from the top left, starting at 0 (the task_partition_index of the results)
majority_answer Multiple Features when at least as many volunteers answered Multiple Features as Single Feature, otherwise Single Feature. No answers are left out of the comparison
single_feature_votes How many volunteers answered Single Feature (one tap)
multiple_features_votes How many volunteers answered Multiple Features (two taps); 0 for projects without that answer
volunteers_total How many volunteers saw the cell
feature_vote_percent Single Feature and Multiple Features votes together, as a percentage of volunteers_total, rounded

The vote counts show how volunteers split: 6 Single Feature and 5 Multiple Features votes give Single Feature, but nearly half saw several objects, so check such cells on the imagery. feature_vote_percent and volunteers_total together show how sure the result is: 100% of 1 volunteer and 75% of 20 volunteers both pass a 50% threshold, but the second rests on many more answers.

Imagery from tiles.openaerialmap.org

The map shows the imagery from the url column of the file. tiles.openaerialmap.org sends each tile request on to titiler.hotosm.org without CORS headers, which browsers refuse, so the helpers read those tiles from the titiler.hotosm.org address directly. The helpers build that address from the redirect tiles.openaerialmap.org answered with in October 2026; the redirect is not documented, so the address can change.

Auto labeller

Use it on a finished project to mark each object on the tiles volunteers marked, as training data for a YOLO model.

Two taps and a drag mark three solar panel groups, then the outlines show

  1. In the auto labeller, paste the project link, set the Volunteer share, for example 50, and the Object name, for example solar panel, and click Load. The first load downloads the EdgeTAM model, about 41 MB.
  2. Each tile is darker outside the cells volunteers marked, with a yellow line around them. For each object, tap its middle or drag a box close around it. Touching solar panels form one array and get one label.
  3. When the result is wrong, press Undo, which removes the newest object on the tile, and drag closer. When it stays wrong, turn on Draw, which stays on until you turn it off: drag along one side of the object, then tap the opposite side. A tap before any drag still asks the model. With Outlines, a drag keeps an upright box as drawn.
  4. Move between tiles with Previous and Next.
  5. Choose the Output and click Download dataset.

For objects with types, Attribute and Values add a value to each label, such as roof:material with metal, roof_tiles. Pick a value with its button above the tile, or with its number key on a keyboard; Objects with types shows the steps.

Download tile images saves every marked tile image, to label in another tool. Load labels (GeoJSON) puts polygons drawn in QGIS or taken from OpenStreetMap on the marked tiles, as in Create a training dataset.

A Freetown tile with the marked cells inside a yellow line and four boxes

Output Shape YOLO task
Boxes The smallest box around the outline, at any angle Oriented bounding boxes, OBB (format)
Outlines The outline of each object Segmentation (format)

Every object keeps its outline, and its box is worked out from the outline, so the Output can change at any time. The objects stay in the browser: loading the same project with the same share brings them back.

Try the Freetown example loads the Freetown solar panel project.

What the download holds

The .zip file holds, for each tile with at least one object:

File Content
images/<tile_id>.jpg The 1024 by 1024 pixel tile image
labels/<tile_id>.txt One line per object, class first (0, or the value's place in Values counting from 0), positions as shares of the image side. A box corner past the image edge is moved onto it, because the format takes values between 0 and 1
data.yaml The image folders and the class names for Ultralytics: the object name, or each value. It uses all images for both training and validation; split them before a real training run
labels.geojson One polygon per object in longitude and latitude (EPSG:4326), in the chosen output
README.md The project, share, model and counts, the tile URL to add in QGIS as an XYZ connection, and the QGIS steps

Each feature in labels.geojson has tile_id, image (the file in the .zip file), object_name, the attribute with its value when one is set, output (rotated box or outline), source (the model, drawn by hand, or the name of a loaded GeoJSON file), marked_cells (how many cells volunteers marked on the tile) and imagery_url. Pixel positions are turned into longitude and latitude through the tile's place in the Web Mercator tile grid, and each outer ring runs counterclockwise, as RFC 7946 asks.

On a phone

EdgeTAM is a version of SAM 2 (Segment Anything Model 2) made for devices: its README describes it as "an on-device executable variant of the SAM 2" that "achieves 16 FPS on iPhone 15 Pro Max without quantization" (paper). That figure comes from the EdgeTAM authors. The GIF below was recorded in desktop Chromium at phone size (390 by 844 pixels); the speed of the page on a real phone has not been measured.

The same steps at phone size

Both GIFs can be downloaded and shared: laptop, phone.

How the auto labeller works

Everything runs in the browser. The page reads the project page, the results file, the project's imagery and the model files, and sends nothing back.

  1. The page keeps the cells where Single Feature and Multiple Features answers together reach the chosen share, as the results map does, and lists every tile with at least one kept cell.
  2. Each tile is shown two zoom levels deeper than the project zoom: 16 imagery tiles joined into one 1024 by 1024 pixel image. For a zoom 20 project, the imagery must serve zoom 22 and send CORS headers. Parts beyond the edge of the image are black.
  3. The EdgeTAM image encoder (vision_encoder.onnx in the model repository) turns the tile into embeddings once, when the tile opens. Transformers.js runs it on the CPU with WebAssembly: with the Freetown example in Chromium on an Intel Core i9-14900HX laptop, about 1 second, and about 6 seconds with the CPU slowed four times. On an HTTPS page the browser keeps the model files (useBrowserCache).
  4. A tap is sent to prompt_encoder_mask_decoder.onnx as one point, and a drag as a box with its centre point. Each takes under a second. The page keeps the candidate mask with the highest predicted quality score. A box drawn with Draw skips the model.
  5. The outline is traced with d3-contour, keeps the largest shape and is simplified to within one pixel with @turf/simplify. The box is the smallest rectangle around the outline's convex hull (@turf/convex).

The inputs were measured on 20 Freetown tiles with 36 hand-drawn reference boxes, counting a result as tight when it overlaps the reference box by at least 0.75. Simulated drags moved each edge of the reference box by a random share of its size.

Input Tight results Mean overlap
Tap in the middle of the group 30 of 36 0.83
Drag with each edge up to 10% off 35 of 36 0.88
Drag with each edge up to 20% off 29 of 36 0.84
Drag 20% larger than the group on every side 11 of 36 0.67

A drag close around the group gives the best result. A drag much larger than the group includes nearby roofs and objects. Outlines of large, dark arrays on similar roofs can be ragged; check them with Outlines before downloading.

Labels checker

Check labels.geojson before you submit it (What to deliver). The files stay in the browser.

The labels checker with the Stellenbosch example: building outlines in yellow over the drone imagery, the checks with 1,036 metal roofs of the 1,000 needed, and the spread check to fix at 33 tiles at zoom 19

  1. In the labels checker, choose labels.geojson and, optionally, the area-of-interest.geojson of each Locate project. Click Check.
  2. Each check shows Passed, To fix or Warning, and checks on single labels list the feature numbers. Those labels are red on the map. A warning leaves the delivery accepted.
  3. Choose the Project zoom (filled in for auto labeller files) and, for types, the Type attribute, such as surface.
  4. Labels per type shows the labels, share, kilometres of line and tiles at the project zoom for each type. The bar above it counts labels, or tiles when the file holds only lines. For boxes and outlines, a second bar counts the tiles all labels touch: red below 500, amber from 500, green at 1,000.
  5. Check on the map that every object inside the area has a label.

Try the Stellenbosch example checks 1,056 buildings and their roof:material from a block of 16 tiles of HOT's roof type training dataset, with each building's whole outline from OpenStreetMap (© OpenStreetMap contributors, ODbL), on the OpenAerialMap image Khayamandi Drone Imagery by Integrated Aerial Systems (CC-BY 4.0). Every check passes except the spread check: the labels touch 33 tiles at zoom 19, below the 500 a delivery needs.

What each check looks at
Check Flags when
A GeoJSON FeatureCollection with features The file has another type, or the features list is empty
imagery_url at the top of the file It is missing, starts without https://, or lacks {z}, {x} or {y}
Longitude and latitude, EPSG:4326 A coordinate is beyond 180 or 90 degrees, or the file names another CRS
Boxes, outlines or lines A feature is a point or a geometry collection, lacks a geometry, or nests its coordinates at the wrong depth
object_name on every feature A feature lacks object_name
Closed outlines and lines with a length A ring has fewer than four positions, ends away from its start, or encloses zero area, or a line has fewer than two positions (RFC 7946) or all its positions on one point
One feature per object, each shape once Two features have the same geometry
Outlines that don't cross themselves An outline crosses itself (turf kinks); lines may cross themselves, as a road can loop
Every label inside the area of interest A point on the label (turf pointOnFeature) is outside every area file chosen
At least 1,000 of the most common type The largest type has fewer than 1,000 labels; labels without a value under Type attribute don't count toward it
At least 1,000 tiles of one type, for a file of lines The type with the most tiles touches fewer than 1,000 tiles at the project zoom, the project zoom is unset, or every label lacks a value under Type attribute
Spread over at least 1,000 tiles, for boxes and outlines All labels together touch fewer than 500 tiles at the project zoom; 500 to 999 tiles, or an unset project zoom, gives a warning

Lines are measured with turf length and their tiles with tile-cover; each line counts as one label, so a road split into segments counts once per segment.