Concepts
Background on MaplatEditor: its role in the Maplat ecosystem, the data formats it produces, and how it relates to the other Maplat libraries.
- What MaplatEditor does
- Data formats produced
- Layer metadata and per-reference overrides
- The two thumbnail sizes
- Base maps and API keys
- The settings screen and the application menu
- Relationship to MaplatTin / MaplatTransform
- Relationship to the Maplat viewer
- OpenLayers bundling
- See Also
MaplatEditor is the desktop data-authoring tool for the Maplat viewer ecosystem. It is an Electron + Vite application that runs on Windows, macOS, and Linux. Its job is to take a historical map image plus a set of ground control points (GCPs) and produce the data files the Maplat viewer consumes.
MaplatEditor is not published to npm (private: true in package.json).
Binaries are distributed via GitHub Releases.
MaplatEditor produces two main kinds of data:
-
Map data — placed under
maps/{mapID}.json. Defines the coordinate correspondence between the historical image and the modern map (Web Mercator, SRID:3857). Can be either the human-editable standard format (withgcps) or the pre-computed compiled format (withcompiled). -
App data — placed under
apps/{appID}.json. Aggregates multiple map sources, POI definitions, and app-level settings (home position, default zoom, fake GPS for testing, etc.). -
POI data — managed as GeoJSON. A POI source exports as plain GeoJSON, or as a ZIP package when it includes image references (the images travel alongside the feature collection); importing a ZIP resolves those internal image references automatically back onto local assets.
The current form of the
poisentry is a reference to an external file plus a set of display overrides, not POI data written into the map. A map or app therefore keeps a list of references, and the POI file itself is owned by exactly one place. Legacy map/app data may instead embed POIs directly in the map or app document (inlinepoisentries); that form is still read for backward compatibility, but it is not what the editor produces. MaplatEditor preserves such entries untouched and offers an explicit, non-destructive "Convert to GeoJSON" action that copies them into a new editable POI source draft, so the map or app can be migrated to a POI source reference at the user's own pace. -
Uploaded originals — the original image files a user uploads (map images, POI/app assets) are stored under
originals/<uid>.<ext>, named by a UUID assigned at upload time rather than by the user-facing slug. This keeps the on-disk filename stable even if the resource is later renamed, and existing slug-named files from before this convention are left in place rather than renamed (non-destructive).
For the schema details of these formats, see the Maplat Wiki Concepts page (MaplatEditor produces the same formats the viewer consumes).
The appearance of a POI layer is decided in two places, and they are easy to confuse because they use the same attribute names. Read this distinction first; the rest of the section depends on it.
- Layer metadata is part of the POI source itself. It says how that layer looks everywhere it is used.
- A per-reference override belongs to the map or app that references the layer. It says how that layer looks in this one delivery.
Layer metadata is edited in the POI source editor, in the Layer Metadata row: Layer Icon and Layer Selected Icon. Whatever you set there applies to every map and every app that uses this POI source.
It is stored in FeatureCollection.properties, which is the canonical
location the editor writes and the viewer reads. Hand-written GeoJSON that
puts these keys at the top level of the FeatureCollection is still accepted
for backward compatibility, but when a key appears in both places the value
under properties wins. If you are bringing in GeoJSON authored elsewhere,
put layer metadata under properties.
A map or app that references a POI layer can override four display
attributes for itself: title, icon, selectedIcon, and hide. These are
edited from the reference entry in the POI tab — see
Tutorials.
Overrides do not modify the referenced file. They are stored in the map or app document and applied to a copy of the layer at delivery time.
An override beats the layer metadata of the same name. That gives a simple rule of thumb:
| Put it in | When |
|---|---|
| Layer metadata | The look should be the same wherever this layer appears |
| Per-reference override | Only this map or app should look that way |
Maps and base maps each carry two thumbnails, for two different jobs: a 512px image used where a reasonably detailed preview is wanted, and a 52px icon used in dense lists and switchers. Both are managed from the Thumbnail management section of the map and base map editors.
The two are not independent. The usual way to update them is to replace the 512px image and let the 52px icon be derived from it, which is what the Also create 52px from 512px checkbox does; it is on by default. In the base map editor it is not merely on by default but forced on unless a 52px image already exists at a known location — there is otherwise nothing to keep, so deriving is the only sensible option. Generate from coverage produces both sizes in one action.
Two further points are worth knowing:
- Replacement is immediate. The file is written as soon as you pick an image. It is covered by neither Save nor Undo, and the way to revert is to replace it again. This is the single exception to the editor's otherwise uniform "nothing is written until you save" rule.
- Built-in base maps cannot have their thumbnails replaced, because built-in base maps are read-only as a whole.
The 512px image is stored as WebP; the 52px icon keeps the format it already had. The asymmetry is deliberate — the larger image benefits from the better compression, while the icon is small enough that the format does not matter.
A base map is the tile imagery a map is drawn on top of. Base maps come in
several kinds — tms for ordinary tile URLs, maplibre for style JSON,
google and mapbox for those providers' own services, and merc for
Mercator tile sets generated from a map inside the editor. Beyond the ones
you register yourself, MaplatEditor ships a large built-in catalogue, which is
re-seeded from its bundled definition at every start; built-in entries are
therefore read-only.
Google and Mapbox base maps need an API key, and the editor keeps two kinds of key so that your own working key does not leak into published apps. Both live on the Base map settings tab of the settings screen:
- Editor API Keys — used by the editor itself while you work.
- Default Publish Keys — the fallback used for previews and exports.
The settings screen warns you if the editor key and the default publish key for the same provider are identical, since separate keys are what make the distinction useful.
Resolution differs between previewing and exporting:
- Preview tries the editor key, then the app's own key, then the default publish key.
- Export tries the app's own key, then the default publish key. If neither exists, the editor asks for a key at export time and uses it for that export only, without storing it.
If no key can be found for a provider, that source is left out and a warning says so, rather than the export failing.
Because a google or mapbox base map is useless without a key, the kind
selector in the base map editor disables those two kinds until the matching
editor key is set, and says why. (maplibre is not gated, because a style
JSON can carry its own key. merc is not selectable at all: those are
created from map editing, not by hand.) The reason is shown through the same
? help button used elsewhere in the forms, so the disabled state is never
silent.
There is a second, easily-misread consequence. Google, Mapbox, and MapLibre base maps do not appear in the editor's own background-map picker while you place ground control points. That is a property of the editor's map view, not of your data: those sources are excluded from the picker, but they are rendered normally in the preview and in the exported app, which load them through the providers' own delivery.
The settings screen has two tabs:
- Basic settings — the general options, including the two JPEG decode limits described in Tutorials. Both are empty by default, which means automatic: the editor decides per image. They are caps you may impose, not operating values you must supply.
- Base map settings — the two tiers of provider keys described above.
Explanations of individual fields are not printed under them; each field carries a ? button that shows its explanation on hover or focus. The same convention is used in the map, base map, and app editors.
The application menu holds the application entry (with About MaplatEditor and quit), an edit menu (undo, redo, and the standard clipboard actions), and a Development menu. The Development menu is not present in released builds — it appears only when running from source, or in a packaged build older than a release candidate, so reload and developer tools are not exposed to end users. Release candidates already hide it, just as final releases do.
About MaplatEditor opens a small separate window showing the product name, the copyright, and the versions of the application and of the runtime components it is built on. The version numbers are read from the running application rather than written into the page, so they cannot drift out of date.
MaplatEditor uses the Maplat coordinate-transform stack internally:
-
@maplat/tin— solves the TIN transform from the GCPs the user places. -
@maplat/transform— preprocessing utilities for tile generation and compiled-data production.
When the user clicks "Save", MaplatEditor runs @maplat/tin's updateTin()
on the GCP set, checks strict_status, and serializes the result via
getCompiled() into the compiled map data file.
The data MaplatEditor produces is consumed by
Maplat (@maplat/ui) and
MaplatCore (@maplat/core).
The viewer loads the app JSON, initializes the TIN transforms from the
compiled map data, and renders the historical maps with the homeomorphic
overlay guarantee.
This is the "end-to-end" of the Maplat ecosystem:
- Author with MaplatEditor (place GCPs, generate tiles, configure app)
- Serve the data files (static hosting, CDN, etc.)
-
Render with
@maplat/ui(or@maplat/corefor custom integration)
Unlike @maplat/core and @maplat/ui, where OpenLayers is a peer
dependency the user must install separately, MaplatEditor bundles
OpenLayers (ol) as a regular dependency in its package.json. This is
because MaplatEditor is an end-user desktop application — the user should not
need to manage npm peer dependencies to use it.
For the same reason, MaplatEditor has no Peer Dependencies section in its
README and no docs/api/ directory — it is a UI application, not a library
with a public API surface.
日本語版はこちら / Read this page in Japanese
- Home
- Tutorials — creating a map in MaplatEditor
- FAQ
- Maplat Wiki Concepts — data format schemas
- MaplatTin Wiki — TIN theory
- README