Tutorials
Step-by-step guides for using MaplatEditor.
Note (2026-07): This page's Legacy Tutorial section is based on the legacy Wiki content (0.1.x era, circa 2018) and is kept for historical reference. The Current workflow section above it covers the present UI. For the latest quick start and download links, see the README.
The current desktop application has a substantially larger feature set than the legacy 0.1.x editor described below: a POI editor, five resource lists (Map / App / POI / Base Map / Asset) with full-text search across all five, plus filter area search for four of them (Map, POI, Base Map, and App), auto-saving drafts, and app-level export/import. This section walks through the current workflow; the step-by-step legacy tutorial is preserved further down for historical reference.
MaplatEditor opens on the Manage Maps screen, listing every saved map plus
a New button to start one and an Import button to bring in a
previously exported map (.zip). A map that is created but not yet saved
shows up here as an orange Draft card instead of being written to disk —
see Drafts and saving below.
Map metadata is edited in the Edit Metadata tab of the map editor. Three fields are required: the ID, the Title, and the Map image attribution. The Display label is optional.
The two names are for different places, which is why both exist. The Title is the map's proper name — it is what the card in the map list and the header of the editor show. The Display label is the short name the viewer puts in its map switcher, where a long title would not fit; leave it empty and the title is used. Both can be written per language.
Besides these you can choose a
Map image license (license) and a Data license (dataLicense),
each with a free-form Map image license note (licenseNote) / Data license note
(dataLicenseNote) field. License choices include All rights reserved, the
CC family, Public domain, plus ODbL and Custom. Choosing
Custom lets you write the attribution freely in the note field (e.g. an
approval number or a source URL). The note fields can be written per language
via the language chips.
The historical map image is registered from the same Edit Metadata tab, with the Register Map Image button that sits next to the image width, height, and extension fields.
Choosing a file is the whole operation. MaplatEditor splits the image into map tiles by itself, in the same step — there is no separate "generate tiles" command to run afterwards. Progress is reported in two stages: Splitting map image into tiles, then Generating map thumbnail.
No external software is required. Tiling runs inside the application in pure JavaScript. In particular, ImageMagick is not needed. The legacy tutorial further down still asks for it, but that requirement belonged to the 0.1.x development environment and applies to neither users nor developers today.
Very large images are handled with three distinct outcomes. These checks read the JPEG header, so they apply to JPEG input; other formats skip straight to tiling.
- Above roughly 100 megapixels, a confirmation dialog warns that the import will take a long time and cannot be canceled once it starts.
- If the image exceeds a decode limit you set yourself, the import stops and names the value on the Settings page to raise. Both JPEG limits are empty — meaning automatic — unless you fill them in, so this outcome only occurs when you have set one.
- If the image is too large for the machine itself, the import stops and asks you to shrink the image before importing it. Raising a setting cannot get past this one.
Nothing is decoded and no existing tiles are touched until these checks pass, so declining the confirmation leaves the map exactly as it was.
Running the button again on a map that already has an image asks for confirmation before replacing it. The ground control points are kept — only the image and its tiles are replaced.
Registering an image is also what unlocks GCP editing: until a map has one, the Edit GCP tab stays disabled and gives Register a map image first as the reason.
The tiles produced here live in the draft's own staging area and are committed together with the rest of the map when you save, following the same "not created until saved" rule described in Drafts and saving.
Opening a map with a registered image shows the Edit GCP tab, which places the historical map image on the left and an accurate modern map on the right. Ground control points (GCPs) are the corresponding-location pairs that let Maplat warp the historical image onto real-world coordinates; the numbered markers and connecting lines in the screenshot below show four such pairs. The modern-map side includes geocoder-assisted address search and a one-click button to estimate the map's home position and zoom level from the GCPs already placed. Right-clicking a correspondence line inserts a midpoint GCP and splits the line — a workflow inherited from the original editor.
Modern map tiles: © OpenStreetMap contributors.
The POI editor lets you add, move, and delete points of interest directly on a map, and edit multilingual name/description/HTML/address/URL/icon fields for each one. Three content modes are available per POI — Standard, HTML, and Web Page — plus inline image references that resolve to assets uploaded through the shared Assets picker. A Raw toggle exposes the underlying GeoJSON for direct editing, and all edits support undo/redo (Cmd/Ctrl+Z, Shift+Cmd/Ctrl+Z or Y).
Background map tiles: © OpenStreetMap contributors.
A map or an app does not hold POIs itself; it lists references to them. The Select POIs tab of the map editor shows that list, badging each entry that is not a plain reference to a registered POI source with what it is:
- Map-embedded POI — POI data written directly into the map or app document (the legacy inline form).
- External URL reference — a bare URL pointing at a POI file.
- External file reference — the same thing wrapped so that display attributes can be overridden for this map or app.
A bare External URL reference shows an Add overrides button. Pressing it wraps the reference so you can set four display attributes for this map or app only:
| Field | What it does |
|---|---|
| Title override | Replaces the layer's title here |
| Icon override | Replaces the marker icon here |
| Selected-state icon override | Replaces the icon of a selected marker here |
| Hidden by default here | Starts the layer hidden; the viewer can still turn it on |
The referenced file is never modified. The overrides live in the map or app document and are applied to a copy when the data is delivered, so the same POI file can be shared by several maps that each present it differently. Clearing a field removes that override again; leaving all four empty is the same as not overriding at all.
Older map/app data may carry POIs embedded directly inside the map or app
document (legacy inline pois entries). These are preserved as-is: the POI
data tab groups them into panes per viewer layer and shows them read-only,
with an item count and the badges above, and they are passed through unchanged
on save and export. To edit them, use the explicit per-layer Convert to
GeoJSON action (one convert button per layer — a single-layer array
converts as a whole, while in a multi-layer list each FeatureCollection card
converts on its own) — this creates a new POI source draft (with an
automatically numbered slug) without changing the original data; you can
then edit and save the draft from the POI list, and delete the original
embedded entries (with a confirmation dialog) once you have switched the map
or app over to the new POI source reference. While embedded data remains in
the list, GeoJSON POI sources cannot be added alongside it, because the
viewer cannot mix the two forms in one list.
The app editor combines a base map, one or more registered maps as sources, and a POI source, then lets you draw the app target area and fill in the metadata an exported app needs. Its tabs are Edit Metadata, Select Maps, Select POIs, and Preview.
The Edit Metadata tab carries the title, the slug, the default language, the description and keywords, the App target area, and two blocks of settings.
HTTP Settings is a row of eight toggles — PWA, Overlay UI, Hide Marker UI, Marker List UI, Envelope UI, Cache, State URL, and Share. Each carries a ? button that explains what the toggle does. The map, base map, and app forms all use that convention now, so field meanings are read in place rather than looked up in this Wiki.
Two of the toggles are linked. Cache depends on PWA: while PWA is off, Cache cannot be set at all, and switching PWA off forces Cache off. Switching PWA back on does not bring Cache back — it stays off until you set it again. The Manifest Settings block (icons, splash image, and the rest of the Web App Manifest) appears only while PWA is on.
Newly created apps start with PWA off, Cache off, and Marker List UI on. Existing and imported apps keep the values they already have; opening them does not rewrite anything.
The Select Maps tab lists the chosen sources as cards. Each card carries
the source's thumbnail and title, a radio button marking the Initial map
shown when the app opens, and — for tms sources — a role selector choosing
between a base layer and an overlay.
Inside each card is a small form. The only master value an app may override is the Display label. Everything else — the title, attribution, licenses, zoom range, thumbnail — comes from the base map or map record itself and is edited there; the ten other overrides that used to exist here have been removed. The label field shows the master's own value as its placeholder, so you can see what you are overriding, and clearing the field drops the override and returns to the master value. There is no separate "reset" button. The label can be edited in languages other than the app's default language.
Built-in base maps get the same form as any other source. There is no tile URL field on these cards at all: the URL belongs to the base map record.
Three values on the card belong to the app rather than to the master: the Usage extent (the area this app actually uses this map for, which is what gets passed to the app and determines tile delivery), and, for overlays, the mercator X/Y shifts. Copy from coverage fills the usage extent from the base map's coverage in one press, and Pick on map opens a picker that shows the map's coverage and the app target area as guides.
The Preview tab renders the app exactly as an end user would see it, using the sources and POIs selected on the other tabs. The language switch for the preview sits in a one-line bar directly under the tabs — it used to float as a card on top of the preview itself, where it competed for space with the viewer's own controls.
Edits auto-save as local drafts a couple of seconds after you stop typing, and are restored if you close and reopen a resource. Map, App, POI, Base Map, and Asset all follow the same "not created until saved" flow: an abandoned new-resource draft is never written to disk, and instead shows up as a draft card in the resource list (visible in the map list screenshot above) that you can resume or discard.
Switching away from a resource does not throw the edits away. The draft is flushed first: if there are unsaved changes they are written to the draft store, and if there are none the draft is cleared. A draft is only discarded when you ask for it — with Discard draft in the editor, or by deleting the draft card from the list. If you undo your way back to the state you started from, the draft removes itself, since there is nothing left to restore. A crash does not cost you the draft either: it survives and is restored at the next start like any other draft. What the startup pass clears, before any window opens, is only staging residue — tile directories that no longer belong to any draft.
The map image tiles created in Registering the map image and tiling follow the same rule: they are written to the draft's own staging area and moved into place only when the map is saved.
Thumbnail replacement is the one exception to all of this. Replacing a 512px or 52px thumbnail writes the image file immediately — it is covered by neither Save nor Undo. To revert, replace the image again. Everything else in the editors waits for Save.
Deleting a map moves the original uploaded image to the operating system's trash instead of erasing it, so a mistaken deletion can still be recovered from there. The derived files (tiles and thumbnails) are removed outright, since they can be produced again from the original.
A base map (the definition of the tile imagery used as the backdrop of a map) is created and edited from the Manage Base Maps list.
The edit form includes Title, ID (slug), Display label, and Map Image Tile URL, plus attribution and license fields:
-
Map image attribution (
attr, required) -
Map image license (
license) and Map image license note (licenseNote) -
Data attribution (
dataAttr) -
Data license (
dataLicense) and Data license note (dataLicenseNote)
The license choices are the same as for maps (All rights reserved, the CC family, Public domain, ODbL, and Custom). A base map can leave its license unset (empty). Choosing Custom lets you write the attribution freely in the note field. Built-in base maps are read-only and cannot be edited.
For a base map of the tms kind, the form also offers Load from TileJSON: paste the URL of a TileJSON document and press Import. The tile URL template, the zoom range, the attribution, the title, and the coverage are all filled in from the document in one step, so you do not have to transcribe them by hand.
If the URL turns out to describe a vector tileset, the import stops with a message saying so and telling you to register the style JSON URL using the MapLibre kind instead. The other refusals — an unsupported URL scheme, a network or HTTP error, a document that is too large, malformed JSON, or one with no tile URLs — each report their own reason.
The Thumbnail management section shows the 512px and 52px thumbnails side by side, with Replace 512px… and Replace 52px… buttons and a Also create 52px from 512px checkbox. Generate from coverage builds both sizes at once from the drawn coverage.
The replace buttons stay disabled until the editor knows where to write the image, and the reason is shown next to them rather than being left to guesswork — a map has to be saved first (Save the map first to replace its thumbnail.), and a base map needs its slug (ID) filled in. Note that replacing a thumbnail is not covered by Save or Undo: the file is written immediately, and the way to revert is to replace it again.
The map editor's Mercator Tiles tab turns the map you have georeferenced into an ordinary web-mercator tile set and registers it as a base map, so it can be used as a backdrop like any other base map.
Press Generate Mercator Tiles to run it. The button is disabled while the GCP setup is incomplete or the tiles are already up to date with the current GCPs, and it says so in place — the tin solution has to be strict, and the tiles have to be older than the current GCP set, for generation to be available at all.
What happens next depends on what already exists:
- If this map has no Mercator tile set yet, one is created without further
questions. Its ID is the map's own ID with
-mercappended (numbered if that is taken). - If it does, a Select Mercator Tile Set dialog lists the existing sets generated from this map. Pick one to update it in place, or choose Create New to add another. Creating a new one lets you edit the title, the ID, and the attribution up front; the attribution can also be left for later and filled in from the base map edit screen.
A new set inherits the source map's attribution and license as its starting values, and its coverage is taken from the generated tiles. Everything is editable afterwards from Editing a base map.
Generation decodes the source image, so the same size limits described under Registering the map image and tiling apply here too.
- Maps are exported with the Export button in the map editor's header (visible in the GCP tab screenshot above); it is available regardless of which editor tab is active. A new map is imported from a previously exported file with the Import button on the Manage Maps list (visible in the map list screenshot above).
- POI sources export as GeoJSON, or as a ZIP package when they include image
references, and can be imported back with internal image references
resolved automatically. Apps export as a single ZIP (
{appID}.zip), optionally including a static, PWA-ready build. Both use the same Export button pattern in their own editor headers (visible in the POI editor and app editor screenshots above). - If an app uses a Google or Mapbox base map and no publish key is available for it — neither on the app itself nor as the default publish key in the settings — exporting first asks for one in an Enter Publish API Key dialog. What you type there is used for that export only and is not stored anywhere. Leaving it blank is allowed: the export goes ahead and the background map that needed the key is left out of it. Cancelling the dialog cancels the export.
- A map with unresolved ground-control-point errors cannot be previewed, but exporting the map itself still succeeds; an app that includes such a map, or that references a map missing from the database (e.g. deleted), is blocked from saving, previewing, and exporting until the issue is fixed. (Quoted from the README's Export and Import section — see there for the complete, up-to-date wording.)
The steps below are preserved from the legacy (0.1.x, circa 2018) Wiki content for historical reference. They describe an older, simpler editor (single map list + GCP-setting tab) and do not reflect the POI editor, master-detail resource lists, drafts, or export/import features added since. The current workflow is described in the Current workflow section above; the current development setup is documented in the README § Development.
When MaplatEditor starts, the map list is shown. Click the New button to create a new map.
Fill in the metadata form. Three fields are required:
- Map ID — becomes the filename. Half-width alphanumeric only. Use the Uniqueness check button to verify no duplicate exists.
- Title — the human-readable title.
- Map image attribution — the attribution string shown in the viewer.
Once the required fields are filled, the Save button becomes available. After saving, the map appears in the list on the next launch.
Click the Map upload button on the edit screen.
Select a JPEG image in the file dialog (only .jpg is supported in the
legacy UI; check the README for the current supported formats).
After upload completes (may take a while for large images), the GCP setting tab becomes available.
The GCP setting tab shows the historical map on the left and an accurate modern map on the right.
Use the magnifier button on the right map to search by place name and narrow the region.
Use the top-right button on the right map to switch the base layer (OpenStreetMap / GSI / historical aerial photos / 今昔マップ on Web etc.). Older aerial photos and historical maps are useful when modern roads and rivers no longer match the historical image.
Right-click on either map at the desired location and choose Add marker. Place markers alternately on the left and right maps — each pair becomes a single GCP.
- Move — left-click and drag a marker to reposition it.
- Delete — right-click a marker and choose Delete marker. Both halves of the GCP pair are removed at once.
- Show pair — right-click and choose Show corresponding marker to locate the other half of the GCP pair. Useful when the map is crowded.
Press Save at any point to persist the GCPs and metadata.
The instructions below are the legacy Electron + ImageMagick + submodule sparse-checkout flow from 0.1.x. The current development setup uses Vite + pnpm and is documented in the README § Development.
The ImageMagick requirement below no longer applies to anyone. Tiling is done inside the application in pure JavaScript today — see Registering the map image and tiling. Do not install ImageMagick on account of this page.
The legacy setup required:
- Node.js + Electron
- ImageMagick (for the
convertcommand used by the tile generator) - Repository clone with submodule sparse-checkout (to slim the bundled Maplat source)
These steps are no longer required for end users — download the desktop installer from the README instead.