Browser based whole-Earth thematic maps using locally hosted data layers.
Premium DOM Component

Thematic Earth

A world of possibilities

by Read Write Tools
The Thematic Earth mapping software brings interactive cartography to browsers, allowing authors to easily map location-based data, while giving readers new insight into complex data patterns and outliers.

At a Glance

The Thematic Earth mapping software has features similar to GIS applications. It is well suited to publishers targeting today's modern browser-centric readership. Here's an overview of Thematic Earth's capabilities:

Capabilities . . .
  • Thematic Earth excels at displaying dot maps, symbol maps, choropleths, isopleths, and geographic feature maps.
  • Thematic Earth scales from neighborhood maps to whole Earth maps — from 1 ᵐ⁄ₚₓ to 1,000,000 ᵐ⁄ₚₓ
  • Users can explore, discover, and learn from maps through mouse interactions, touchscreen gestures, and floating feedback panels.
  • Cartographers can use existing vector data layers encoded as common geoJSON files or as highly compressed GFE files for fast network access.
  • Data specialists can rely on Thematic Earth to render geometries with minimal distortion, without projection hassles.
  • Designers can visualize layers with sophisticated gradients, brushes and patterns using TESS, a declarative language following CSS syntax rules.
  • Developers can use the component's JavaScript API to control the map's behavior, and use the component's event-based interface to respond to user interactions.
  • DevOps can deploy Thematic Earth maps without costly enterprise GIS server infrastructure.
  • Communities working on common areas of interest can develop and share spatial data, configurations, legends, styles, and scripts using Thematic Earth Packages.
  • Thematic Earth maps can be embedded in both online websites and offline progressive web applications.
  • Thematic Earth maps automatically resize to fit the browser's viewport, allowing it to be used on both mobile devices and large mega-pixel displays.
  • Thematic Earth maps are sandboxed, allowing a single web page to independently host side-by-side maps.
  • Thematic Earth is self-contained, relying wholly on modern web component standards that require no framework scafolding.


Many different types of maps can be created using the Thematic Earth software.

Types of maps . . .
  • Choropleth maps can use colors and patterns to shade administrative regions with banded data ranges, such as demographic patterns or political trends.
  • Isopleth maps can use contours and shading to show geographic areas of equal value, such as rainfall distributions, urban heat bubbles, or ocean salinity levels.
  • Dot maps can use filled circles with radii proportional to data magnitude, such as disease distributions, or health care availability.
  • Symbol maps can use markers to represent distinguishing data features, such as biodiversity markers, ecological trouble spots, or anthropological artifacts.
  • Geographic feature maps can use symbols, lines and shapes to tell stories about a place and its cultural and physical geography.


Users can interact with Thematic Earth maps using mouse interactions, touchscreen gestures, keyboard shortcuts, and dockable menu commands.

Two-way interaction between user and map . . .
  • Reveal information about geographic features located under the mouse pointer by simply hovering over them.
  • Click on features to build a selection list for customized feedback.
  • Explore regions of the map by zooming the map's scale from 1 ᵐ⁄ₚₓ to 1,000,000 ᵐ⁄ₚₓ
  • Focus on any point of the globe, even polar regions, reprojecting every map feature (on-the-fly) to the new point of observation.
  • Interactively draw great circle routes between any two arbitrary places.
  • Automatically show related data in dockable menu panels as the user interacts with the map.


Thematic Earth maps are constructed from spatial files, layers, legends, and symbol specifiers working together to render points, lines and polygons according to the cartographer's design.

Spatial files . . .

Maps are constructed from spatial files containing records having unprojected geographic coordinates (simple latitude/longitude pairs).

Thematic Earth supports eight types of spatial files:

  • geojson - RFC 7946 (
  • topojson - GeoJSON with topology (github/topojson)
  • gfe - Geographic Feature Encoding
  • ice - Indexed Coordinate Encoding
  • tae - Topological Arc Encoding
  • gfebin - Geographic Feature Encoding binary
  • icebin - Indexed Coordinate Encoding binary
  • taebin - Topological Arc Encoding binary

The GCS I/O tool can assist with conversions. See Better Compression of GIS Features for how to get the fastest download times with large GIS files.

Layers . . .

Layers allow a single spatial file to be used in more than one way. Layers connect spatial files to:

  • Feature keys
  • TESS identifiers
  • TESS classnames
  • Feedback menu options
Legends . . .

Legend items provide map users with a visual directory of the symbols, colors and styles used by map features. Legend items are synchronized to TESS declaration changes.

Symbol specifiers . . .

Map features are rendered using class-based and identifier-based drawing rules declared by the map's designer.

Rules are specified using Thematic Earth Symbol Specifier (TESS) declarations, which are CSS-like statements that specify classnames, identifiers, attributes, values, and at-rules.


The Thematic Earth mapping software is simple to deploy. Your web server. Your web page. Your spatial data. Any browser.

Dependency free . . .

The Thematic Earth software uses standard custom element technology built into the HTML5 specification. Thematic Earth does not use third-party frameworks, scaffolding, libraries or shims.

Thematic Earth maps can be embedded into any modern browser-based setting, whether it's a desktop, laptop, tablet or mobile phone.

Thematic Earth maps can be hosted on plain web servers; they do not need a specialized remote GIS tile server. Spatial files are retreived and cached locally, and may be embedded in offline progressive web application (PWAs).


Thematic Earth maps are configured with HTML element attributes, controlled by JavaScript statements, styled with TESS declarations, and shared using plain-text packages.

Configuring, controlling, styling, sharing . . .
  • The <thematic-earth> HTML custom element has static attributes that configure the map's viewport size, scale, point of observation, time-lapse animation, and menu panel states.
  • The software exposes a JavaScript API that allows autonomous control of the map's configuration, current state, and appearance.
  • The software provides a JavaScript event interface that developers can use to provide synchronized feedback and external control.
  • Thematic Earth Symbol Specifier (TESS) files allow map styling to be described with class-based and identifier-based visualization rules, and later refined with overriding feature-based rules.
  • Spatial files, layer definitions, legend elements, configurations, and TESS declarations can be shared and reused through simple packages that can be created using plain-text editors.


The Thematic Earth mapping software has unique features that set it apart from typical GIS software.

Features that stand out . . .
  • Thematic Earth is browser-based, taking full advantage of modern web component standards. By way of contrast, typical GIS software operates as either a desktop application or an enterprise server.
  • Thematic Earth uses JavaScript, the native language of the web, for configuration and scripting. In contrast, typical GIS scripting uses the Python language, which isn't compatible with browsers.
  • Thematic Earth uses on-the-fly coordinate projection, always keeping the map's point of observation, and viewport center, as the place of least distortion.
  • Global datasets can be rendered without ever worrying about extreme distortion in the Arctic regions, or the "end-of-the-world" at the International Dateline.
  • Spatial data is retrieved and cached locally, allowing maps to be used in offline situations, with no loss of interactivity.


How does Thematic Earth stack up to other GIS software? What type of spatial data can be used? What are the front-end, back-end, and network prerequisites?

Questions and answers . . .


How does the Thematic Earth web component compare to desktop applications like ArcGIS or QGIS?
ArcGIS and QGIS are both full fledged "geographic information systems" capable of digitizing new spatial data files and performing spatial analyses.
The Thematic Earth web component is capable of visualizing spatial data online and styling spatial layers with symbolic specifiers, but not digitizing new spatial data or performing spatial analyses.
How does the Thematic Earth web component compare to Enterprise GIS or Web GIS?
Enterprise GIS refers to a centralized cloud-based delivery mechanism where large spatial databases are shared by multiple users and applications. Its complement is Web GIS, which refers to map software that runs in a browser and retrieves spatial data through an enterprise server connection.
The Thematic Earth web component is similar to Web GIS software, but it works without a back-end enterprise server connection.
How does the Thematic Earth web component compare to maps saved as PNG, JPEG or SVG images?
Image files contain a frozen representation of routes and places within a predetermined bounding box.
The Thematic Earth web component dynamically renders interactive maps, with variable scale and perspective, that users can freely pan, zoom, reposition, and rotate.
How does the Thematic Earth web component compare to Google Maps or Apple Maps?
Google Maps and Apple Maps are principally GPS navigation tools, allowing users to search and locate commercial, administrative, and natural features.
The Thematic Earth web component is principally an information vizualization tool, allowing users to explore and compare layers of spatial data based on attributes and their values.

Spatial data files

Can Thematic Earth maps use ESRI shapefiles (SHP)?
Not directly. ESRI shapefiles are a collection of three or more files that together support many types of geometries. Many of these can be converted to geoJSON files, which can be used by Thematic Earth, using Mike Bostock's shapefile converter.
Can Thematic Earth maps use Open Geospatial Consortium GeoPackage (GPKG) files?
Not directly, however GeoPackage vector datasets (but not raster datasets) can be converted to geoJSON files using the GDAL/OGR converter from the Open Source Geospatial Foundation.
Can Thematic Earth maps use Keyhole Markup Language (KML/KMZ) files?
Not directly. Most point, line and polygon features encoded in KML files can be converted to geoJSON using the Mapbox toGeoJSON Node.js converter. NetworkLinks and GroundOverlays cannot be converted to geoJSON.
Can Thematic Earth maps use Open Street Map (OSM) Protocolbuffer Binary Format (PBF) files?
Not directly. Selected areas of Open Street Map data can be downloaded from GeoFrabrik and converted to geoJSON using Martin Raifer's osmtogeojson Node.js utility. (Open Street Map tiles are not supported.)
Does Thematic Earth software support any binary spatial data file format?
Three special binary file formats can be used to efficiently transfer spatial data:
  • gfebin - Geographic Feature Encoding
  • icebin - Indexed Coordinate Encoding
  • taebin - Topological Arc Encoding
Geojson files can be converted to each of these formats using the GCSLIB library or the GCS I/O Node.js utility.
Can the Thematic Earth software read map tiles from a GIS server.
No, Thematic Earth retrieves and caches spatial data files in their entirety. Continuous data feeds from enterprise GIS servers, based on a scaling factor and a geographic coordinate, are not supported.


How does the Thematic Earth software access spatial data?
Spatial data files are pulled from remote servers using standard HTTP methods, cached in the user's browser using instructions specified in the response headers, and reused on subsequent page visits according to the HTTP caching specification (RFC 9111).
Is there a central repository for Thematic Earth spatial data?
There is no master storage vault for data; no fees for using public domain data; no restrictions on your own data. Spatial data files can be accessed from any HTTP accessible endpoint. The Thematic Earth software has built-in metadata features to allow proper attribution and citation of third party data.
What are the back-end requirements for web pages with embedded Thematic Earth maps?
Any HTTP web server will work, but HTTP/2 is strongly recommended.
Spatial data files should be compressed, ideally with brotli (RFC 7932 ) or GZIP (RFC 1952).
Static spatial layers should be served with extended cache expiration dates. Spatial layers that are subject to frequent changes should be served with shorter cache expiration dates.
What are the front-end requirements for web pages with embedded Thematic Earth maps?
The user's browser must have JavaScript enabled. (No third-party frameworks, libraries, loaders, or bundlers are necessary.)
The Thematic Earth web component is framework agnostic, and may be used with single page applications that use popular front-end frameworks like Angular, Vue, React, Svelte, etc.
Can a Thematic Earth map obtain spatial data from third-party servers?
Yes, Thematic Earth maps can be rendered from any remote endpoint that has correctly configured CORS to allow cross-domain requests from the original back-end server.

Hello World

What do the declarations, markup, and initialization code look like for a Thematic Earth map?

HTML markup . . .

The HTML markup for an interactive map of the world:

<!DOCTYPE html>
<title>Hello World</title>
<meta name=viewport content='width=device-width, initial-scale=1' />
<link href='./example.css' rel='stylesheet' />
<thematic-earth id=earth panels="interaction point-of-reference map-scale layers locate"></thematic-earth>
<script src='/node_modules/thematic-earth/element.js' type=module></script>
<script src='./example.js' type=module></script>
CSS declarations . . .

CSS declarations to resize the map to fit the entire page:

body {
display: flex;
position: absolute;
width: 100%;
height: 100%;
margin: 0;
thematic-earth {
height: 100%;
width: 100%;
JavaScript initialization . . .

JavaScript to add map layers, add TESS declarations, and set the point of observation:

var earth = document.getElementById('earth');
var promise = earth.waitOnLoading();
promise.then(() => {
spatialDataType: 'sphere',
tessIdentifier: 'earth',
layerName: 'Earth'
spatialDataType: 'gcs',
tessIdentifier: 'land',
layerName: 'Land',
url: './seven-continents.gfebin'
spatialDataType: 'night',
layerName: 'Night & Day'
spatialDataType: 'graticule',
parallelFrequency: 5,
meridianFrequency: 5,
layerName: 'Lat/Lng Grid'
spatialDataType: 'named-meridians',
layerName: 'Prime Meridian & Dateline',
namedMeridians: { "Prime Meridian": 0, "Intl. Dateline": 180 }
spatialDataType: 'named-parallels',
layerName: 'Equator',
namedParallels: { "Equator": 0 }
TESS declarations . . .

Thematic Earth Symbol Specifier (TESS) declarations for the map:

#earth {
fill-color: #34a1eb;
#land {
stroke-color: #333;
stroke-width: 0.5;
fill-color: rgba(240, 213, 125, 0.51);
fill-gradient: radial;
fg-saturation: 200;
.named-parallels['Equator'] {
stroke-color: #f33;
.named-meridians["Prime Meridian"],
.named-meridians["Intl. Dateline"] {
stroke-color: #025bc2;
stroke-width: 3;
stroke-type: dots;


Thematic Earth mapping software can be configured by adding optional attributes to the <thematic-earth> element tag.

Element attributes . . .
Used to set the initial latitude, longitude and place of interest.
  • 'off' [default] set initial longitude, latitude and place of interest to (0.0, 0.0) and honor explicit setTangentLongitude, setTangentLatitude, setPlaceOfInterest API calls.
  • 'on' use the browser's geolocation beacon to set initial longitude, latitude and place of interest.
  • 'timezone' use the browser's current time to determine the map's initial longitude.
Used to set the initial state of the toolbar.
  • closed [default] The toolbar menu should initially be collapsed.
  • open The toolbar menu should initially be expanded.
Used to position the toolbar's location relative to the component's canvas area.
  • top-right [default]
  • top-left
  • bottom-right
  • bottom-left
Defines which keyboard function key activates the toolbar; something like F1, F2, F3, etc.
Declares the presence and order of which menu panels to activate; a space separated list of these keywords:
  • none [default] Hide all menu panels.
  • interaction Mouse gestures for manipulation and interaction.
  • legend Show the legend.
  • season Change the reference date.
  • time-of-day Change the time of day.
  • equation-of-time The variance between mean solar noon and actual solar noon.
  • solar-events The time of sunrise, solar noon, and sunset.
  • geocentric-coords The Earth's declination and right ascension for the current date and time.
  • topocentric-coords The position of the sun for the current location and time.
  • point-of-reference Change the longitude/latitude of the observation point.
  • map-scale Change the map's scale.
  • space Shift the space point of view.
  • canvas Shift the canvas origin.
  • layers Choose which layers to display.
  • locate Display longitude and latitude of mouse position.
  • discover Discover features a pointer position.
  • identify Identify underlying feature details.
  • select Highlight features.
  • distance Display distances along great-circle arcs.
  • time-lapse Rotate the earth at a set speed.
  • snapshot Capture and download an image of the map.
  • metadata Show map citations, data sources, software version, and licensing links.
  • symbol-specifier Interactive manipulation of Thematic Earth Symbol Specifiers.
  • signals Monitor system broadcasters and receivers.
A URL pointing to a Thematic Earth Package, which defines the initial configuration, settings, data layers, legends, TESS declarations, and other packages to use.


Thematic Earth mapping software dispatches messages that JavaScript can monitor and hook into through the component's addEventListener method.

Element notifications . . .
Sent when the component is fully loaded and ready to be used. As a convenience you can use the waitOnLoading() method which returns a promise that resolves when the component-loaded event is received. Call this asynchronously with await.
Confirmation that a Thematic Earth Pacakge has been added to the catalog.
Confirmation that a layer has been added to the catalog.
Confirmation that a spatial file has been added to the catalog.
Confirmation that a TESS declaration file has been added.
Confirmation that a great circle route has been added to the map.
Response containing the geographic coordinates under the mouse pointer's current position.
Response containing the list of features forwarded to the 'discover' menu panel when the user hovers over a map feature.
Response containing the list of features forwarded to the 'identify' menu panel when the user <shift> clicks on the map.
Response containing the list of features forwarded to the 'selection' menu panel when the user <ctrl> clicks on the map.
Response containing the list of features forwarded to the 'symbol-specifier' menu panel when the user <s> clicks on the map.

Beta Testing Program

The Thematic Earth mapping software is currently being distributed through a Beta Testing Program.

Beta Testing Program licensing and cost . . .

By downloading, installing or using this software you agree to be part of the Beta Testing Program. There is no cost to join. To obtain a license key and join the Program provide your name and email address using this form:

Join the Beta Testing Program

As part of the Beta Testing Program you agree to report any bugs found, any missing or inaccurate documentation, and any usability concerns you discover. You agree to be contacted by Read Write Tools to clarify any information you provide to us as part of the Program.

During this pre-release phase, new features may be added, existing features may change or be removed, and the application programming interface (API) may change from one release to the next.

The Beta Testing Program will terminate when the software has reached a stable state. By joining the Program you agree to discontinue use of the pre-release software within 90 days of the Program's termination.

This software is not freeware. There will be a licensing fee for continued use upon termination of the Program.

Thematic Earth Software License Agreement

Copyright © 2023 Read Write Tools.

  1. This Software License Agreement ("Agreement") is a legal contract between you and Read Write Tools ("RWT"). The "Materials" subject to this Agreement include the "Thematic Earth" software and associated documentation.
  2. By using these Materials, you agree to abide by the terms and conditions of this Agreement.
  3. The Materials are protected by United States copyright law, and international treaties on intellectual property rights. The Materials are licensed, not sold to you, and can only be used in accordance with the terms of this Agreement. RWT is and remains the owner of all titles, rights and interests in the Materials, and RWT reserves all rights not specifically granted under this Agreement.
  4. Subject to the terms of this Agreement, RWT hereby grants to you a limited, non-exclusive license to use the Materials subject to the following conditions:
    • You may not distribute, publish, sub-license, sell, rent, or lease the Materials.
    • You may not decompile or reverse engineer any source code included in the software.
    • You may not modify or extend any source code included in the software.
    • Your license to use the software is limited to the purpose for which it was originally intended, and does not include permission to extract, link to, or use parts on a separate basis.
  5. Each paid license allows use of the Materials under one "Fair Use Setting". Separate usage requires the purchase of a separate license. Fair Use Settings include, but are not limited to: eBooks, mobile apps, desktop applications and websites. The determination of a Fair Use Setting is made at the sole discretion of RWT. For example, and not by way of limitation, a Fair Use Setting may be one of these:
    • An eBook published under a single title and author.
    • A mobile app for distribution under a single app name.
    • A desktop application published under a single application name.
    • A website published under a single domain name. For this purpose, and by way of example, the domain names "" and "" are considered to be separate websites.
    • A load-balanced collection of web servers, used to provide access to a single website under a single domain name.
  7. This license is effective for a one year period from the date of purchase or until terminated by you or Read Write Tools. Continued use, publication, or distribution of the Materials after the one year period, under any of this Agreement's Fair Use Settings, is subject to the renewal of this license.
  8. Products or services that you sell to third parties, during the valid license period of this Agreement and in compliance with the Fair Use Settings provision, may continue to be used by third parties after the effective period of your license.
  9. If you decide not to renew this license, you must remove the software from any eBook, mobile app, desktop application, web page or other product or service where it is being used.
  10. Without prejudice to any other rights, RWT may terminate your right to use the Materials if you fail to comply with the terms of this Agreement. In such event, you shall uninstall and delete all copies of the Materials.
  11. This Agreement is governed by and interpreted in accordance with the laws of the State of California. If for any reason a court of competent jurisdiction finds any provision of the Agreement to be unenforceable, that provision will be enforced to the maximum extent possible to effectuate the intent of the parties and the remainder of the Agreement shall continue in full force and effect.


Where to get the software, and how to activate your license.

Downloading and activating the software . . .
DOM components logo Documentation READ WRITE HUB
git logo Minified source code github
DOM components logo Component catalog DOM COMPONENTS
npm logo Package installation npm
Read Write Stack logo Publication venue READ WRITE STACK


To activate your license, copy the rwt-registration-keys.js file to the root directory of your website, providing the customer-number and access-key sent to your email address, and replacing with your website's hostname. Follow this example:

export default [{
"product-key": "thematic-earth",
"registration": "",
"customer-number": "CN-xxx-yyyyy",
"access-key": "AK-xxx-yyyyy"


Module exports
ES modules true
Common JS false
Browser API
node.js none
Read Write Tools icon

Smart tech


Read Write Hub icon

Distraction-free writing



Rediscover HTML


Read Write Serve icon

Served with pure HTTP/2


Premium DOM Component

🔗 🔎