Carmenta Tile Engine
Carmenta Tile Engine is a lightweight web server component that can be used to serve fast background maps using the OGC API Tiles standard interface to your Carmenta Engine client or other compatible clients.
Carmenta Tile Engine consists of an executable dependent on a Carmenta Engine runtime and a CSS file that can be run as either a standalone console application or as a service on Windows or Linux.
Tile Engine's functionality focuses on and is optimized for speed and simplicity. In the case where the service will be accessible from the internet, additional tools to cover safety and security features needs to be configured. This could include, but is not limited to, tools for authentication, overload protection, and automatic security updates.
There is a Getting started with OGC API Tiles article that can be used in parallel with this article.
Evaluation version
It is possible to run Tile Engine with configurations containing unlicensed extension for evaluation purposes. In this mode, all collections will have a watermark added to each tile. These watermarks will not be present when using a fully licensed version.
Creating configurations for Tile Engine
Tile Engine uses the Carmenta Catalog functionality to read configurations. Catalog Extension will search the directories given by the CTE_CATALOG_DIRECTORY setting to find suitable configurations located in the root of these directories, or in a "Services" directory directly under the root directory. To make a configuration readable with Catalog Extension you need to set the CatalogMap property on the View object to true. Catalog Extension configurations can only contain one View object each.
Each configuration with a CatalogMap:True setting on its view will become a "Collection" in the OGC API which is the standard unit in which OGC API divides up its services or data sets.
Carmenta Tile Engine can be used with all types of Engine configurations, except for:
3D configurations, built on Carmenta Engine's GlobeView.
Configurations with custom objects using any other API than Carmenta Engines C++ API.
Configurations with S-63 data.
The Crs setting on the View changes what reference system is used to setup the tile matrix for the collection. The default value is Web Mercator which will setup a service compatible with many web maps such as Google and Bing maps and will also allow the service to support the XYZ (Slippy Map) tile interface which is used by some older clients.
ScreenLayers and TileLayers will be replaced in runtime with LayerSets as they do not work well with the OGC API Tiles tiling scheme. The functionality of TileLayers is replaced by the built-in caching in Tile Engine. ScreenLayers, for example used for legends, attribution or compass directions, are currently not supported by the OGC API Tiles standard.
Running Carmenta Tile Engine as a service
You may want to run Carmenta Tile Engine as a service when using it in staging and production environments as this will allow Carmenta Tile Engine to run automatically in the background. Note that console logging will not be available when running as a service, so you probably want to setup file logging (see the CTE_LOG_DIRECTORY setting) before using Carmenta Tile Engine as a service.
Running as a service on Windows
To run Carmenta Tile Engine as a Windows service you need to register the executable.
CarmentaTileEngine.exe has integrated code to run as a Windows service, so to register it as a service you can run the following commands in a command prompt with administrative rights:
sc create CarmentaTileEngine displayname="Carmenta Tile Engine" start=auto binPath= "C:\path\to\CarmentaTileEngine.exe --service"
Carmenta Tile Engine will then appear in the Windows services manager and respond to start and stop messages for services. By default, services use the local system account to run. You can change this by adding user and password parameters to sc create or later in properties on the service in Windows service manager.
If you later want to remove the service, you can use the following command:
sc delete CarmentaTileEngine
You may need to restart after deleting a service.
Running as a service on Linux using systemd
To run Tile Engine using systemd you first need to create a .service file configuring the service.
[Unit]
Description=Carmenta Tile Engine
After=network.target
[Service]
ExecStart=/usr/bin/carmenta-tile-engine --nostop
Type=exec
Restart=always
[Install]
WantedBy=default.target
Save the file as /etc/systemd/system/carmenta-tile-engine.service. To make systemd aware of the new file, run:
sudo systemctl daemon-reload
Then you can enable the service by running:
sudo systemctl enable carmenta-tile-engine.service
And finally you can start the service using the following command:
sudo systemctl start carmenta-tile-engine.service
Settings
Carmenta Tile Engine is configured using environment variables or by using an ini-file with the same settings. In case both settings are present the .ini file setting will override the environment variable.
CTE_BASE_URL
The base URL setting allows a user to override the URL to the Tile Engine server written in HTML and JSON documents generated by Tile Engine. This can be useful if you run Tile Engine behind for instance a reverse proxy, or a load balancer where you can set the base URL to refer to said reverse proxy or load balancer rather than have Tile Engine generating documents with URLs referring to itself as is the default behavior.
 |
CTE_CATALOG_DIRECTORY
This setting specifies the catalog path to use for loading map configurations. If a catalog directory is not set Carmenta Tile Engine will use the samples/MapConfigurations directory in the Carmenta Engine installation as default.
CTE_CORS_ACCESS_HEADER
This setting is used to set the Access-Control-Allow-Origin HTTP header which allows cross domain requests. If you intend to use the collections from a Carmenta Tile Engine in a web browser, you might want to set this.
By default, web browsers restrict pages from loading certain resources from other addresses. This becomes a problem when you have a web front on one address but try to load for example JSON files from another which is often the case when using web clients such as Open Layers to display a map.
You can set this variable either to * which will allow all cross-domain requests, or a specific host name. Note that the header does not support setting a list of host or partial wildcards.
By default, this set to "*".
CTE_LOG_LEVEL
This will set the log level for Carmenta Tile Engine. The available log levels are NONE, FATAL, ERROR, WARN, INFO, DEBUG and TRACE.
Logs on the FATAL and ERROR levels are typically unexpected problems internally in the Carmenta Tile Engine, while incorrect parameters from clients are logged at the WARN level. Higher log levels are primarily for testing and diagnostics. Recommended level in production is either WARN or ERROR. See the troubleshooting section for more information on how to use the log.
The log writes to standard out or to a set of log files if this has been enabled.
Default log level is WARN.
CTE_LOG_DIRECTORY
If this variable is set to a valid directory, logs will be written to this directory with a rolling file appender in addition to the standard console logging.
CTE_LOG_FILES
This variable determines how many files the rolling file appender will use. The default value is 10. Each file will have a max size of 1 Mb and is the max file number is reach the oldest one will be overwritten.
CTE_MAX_CACHE_SIZE
Cache size in megabytes that should be an integer. This setting determines the size of the built-in memory cache for tiles in Carmenta Tile Engine. Default is 256.
CTE_PORT
Specifies which port Tile Engine will run on. The port must be in the range [80, 65535]. The default port is 8080.
CTE_LICENSE_PATH
Specifies a path to the Carmenta Tile Engine license file if other than the default path. See Using a Carmenta Engine 5 runtime license for additional information on licensing.
Using a TileEngine.ini file
The file should contain key-value pairs with the same names and possible values as the environment variables described above, one on each line on the KEYVALUE format.
Carmenta Tile Engine will look for an ini-file in the following paths on Windows, preferring the top ones:
[Work folder]/TileEngine.ini
%LocalAppData%/Carmenta/TileEngine.ini
%ProgramData%/Carmenta/TileEngine.ini
/mnt/c/ProgramData/Carmenta/TileEngine.ini (when using WSL)
On Linux the order is the following:
[Work folder]/TileEngine.ini
$HOME/.config/Carmenta/TileEngine.ini
/etc/Carmenta/TileEngine.ini
Supported Interfaces
Carmenta Tile Engine supports the OGC API Tiles (map tiles) interface as well as a XYZ interface if you are using the Web Mercator standard matrix.
OGC API Tiles (map tiles)
The OGC API Tiles (map tiles) is designed to provide image tiles that can be cached on both the server and clients for fast background maps and overlays. It is designed to be used with well known tiling schemes that can be combined with maps from other sources and that are compatible with map tiles from many large map service providers.
Requests
The OGC API is organized in a hierarchical manner and uses links to allow navigation intended both for humans (HTML) and machines (JSON). Below follows a brief description of the purpose of each page in the OGC API Tiles that is implemented in Carmenta Tile Engine. For brevity, local links in this section will omit the protocol, host, (and port), i.e. http://example.com.
Landing page
At the root URL is the OGC API landing page. This is the starting page for all OGC APIs and contains links to navigate further.
Conformance
Located at /conformance.
The conformance page declares support for the standard capabilities supported by the server. Its main use is to detect support for specific functionality that a client or user may use.
Tile Matrix Sets
Located at /tilematrixsets, individual sets at /tilematrixsets/{TileMatrixSetId}
This is a list of description for the tile matrix sets used on this server including bounds, scale levels and other information you need to place tiles correctly on a map.
Collections
Located at /collections is a list of all loaded collections. In Carmenta Tile Engine, a collection is equivalent to a map loaded by the catalog (see the setup section). From the collection list there are links to each individual collection with more information about its properties.
Specific collections
Located at /collections/{collectionId} is the description of each collection. It contains metadata and links to supported interfaces.
Map tile page
Located at /collections/{collectionId}/map/tiles is the map tile page for this collection. This page details what tile matrix sets the collection supports for map tiles and contains a link to each one. At this point the specific hierarchy for map tiles starts.
Map tile matrix set
Located at /collections/{collectionId}/map/tiles/{TileMatrixSet} is the page for a specific collection and tile matrix set, and this page contains the URL templates needed by a client to use the OGC API Tiles maps with the specified tile matrix set.
Tile templates
The server provides tile templates for PNG and JPG images, in OGC API format as well as XYZ compatible links when using the WebMercatorQuad tile matrix set. The templates will have the form:
/collections/{collectionId}/map/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}.{format}
where tileMatrix is equivalent to z or zoom level, tileRow is equivalent to y or vertical index, while tileCol is equivalent to x or the horizontal index. Supported formats are PNG and JPG.
Replacing the index parameters in a template with the desired index values will return a tile, if the index is within bounds of what the tile matrix set allows.
Manually navigating the OGC API Tiles Maps hierarchy
To navigate using the HTML pages starting from the landing page, you will need to traverse the links from landing page->collections->specific collection->map tile page->map tile matrix set; to get to the URL templates you need to get actual map tiles.
Typically, when you are using the interface you want a link that can be used in your client to display one or more collections. Some clients may be able to work using a link to the landing page, others may need the link to a specific collection, while some need the URL pattern you can find by following the links all the way down to a specific tile matrix set for a collection. Refer to the client documentation for the specific requirements.
When using an older version of Carmenta Engine without OgcApiTilesLayer or another XYZ capable client, you will need a XYZ link. This is only available for the WebMercatorQuad tile matrix set. In Carmenta Engine you can use this link in an OgcWmtsLayer which will accept XYZ links for the url property.
Programmatically navigating the OGC API Tiles Maps hierarchy
If you want to programmatically read the OGC Interface, use the JSON version of the pages which you can access either by setting the acceptType http-header to application/json in the request, or by adding the f=json parameter at the end of the URL. For example, http://[hostname]:[port]?f=json will give you the JSON version of the landing page.
All JSON pages have links with a rel property that indicates what they contain, and which you can use to get to the information required. So starting from the landing page, you can navigate to a specific template set by following the following rel links:
Steps with a * indicates multiple choices.
Starting on landing page, in the links JSON array, get the link with rel=http://www.opengis.net/def/rel/ogc/1.0/data to get to the collections page.
(*) On the collections page, in the collections JSON array, get the rel=self link for the collection you want and follow it to get to the specific collection.
On the specific collection page, in the links JSON array, get the link with rel=http://www.opengis.net/def/rel/ogc/1.0/tilesets-map with type="application/json" to get to the map tile page.
(*) On the map tile page, in the links JSON array, each link with rel=item with type=application/json is a tile matrix set you can use. Follow the link you want to get to the map tile matrix set.
(*) On the map tile matrix set page, in the links JSON array each link with rel=item, type equal to an image format such as image/png or image/jpeg and the property templated=true is an URL template you can use to get map tiles.
Furthermore, you may need the definition of the tile matrix set you want to use if you do not already know how it is defined. Each tile matrix set is defined at /tilematrixsets/{TileMatrixSetId}. You can get links to the full definitions from the links JSON array by looking for links with rel=http://www.opengis.net/def/rel/ogc/1.0/tiling-scheme on the (collections/worldmap/map/tiles). You can also navigate from the landing page by following the link with rel=http://www.opengis.net/def/rel/ogc/1.0/tiling-schemes which takes you to the tile matrix sets list page and then selecting the wanted tile matrix set from the tileMatrixSets JSON array and following the rel=self link from the links JSON array. You do not necessarily need to start navigating from the landing page. If you know the location of the collections list or a specific collection you can start there instead. However, not all servers may have an identical hierarchy. If you want to build something that works on any OGC API server, you should be able to handle starting with a link leading to anywhere in the full hierarchy. Note that some clients may require you to insert a specific URL, to for example the collections or a specific collection page and may not be able to use the landing page link.
Troubleshooting
Check Firewall
Carmenta Tile Engine runs on the port specified by CTE_PORT (default 8080). Verify that this port is open in your firewall.
Using the log
Carmenta Tile Engine automatically logs to standard output. When contacting Carmenta support about an issue with Carmenta Tile Engine it is usually very useful to include relevant logging messages.
What appears in the log depends on the log level set when Carmenta Tile Engine was started. When trying to debug a specific issue it is normally recommended to set the log level to INFO or DEBUG, as these levels make it much easier to see where in the program flow an issue occurs. When running the server normally, there is a trade off between performance and how much logging you may want. Different types of problems appear on different log levels, so depending on what issues are likely to occur, you want to select a log level that outputs useful information for that specific type of issue.
FATAL - Messages on this log level appears when the Carmenta Tile Engine needs to shut down because of a problem that it cannot recover from. Normally these types of problems are unexpected, so it is advisable to set a log level to also catch ERROR and possibly WARN messages that might occur just before one of these messages.
ERROR - Internal errors and problems that are unexpected but not fatal belongs to this category.
WARN - Warnings are typically incorrect input from clients and inconsistencies that are not necessarily a problem. This level is good for noticing compatibility problem with clients.
INFO - This level contains messages that are generated by normal program flow that are not exceptional. It is mostly relevant for internal debugging purposes but are not as performance heavy as the DEBUG level.
DEBUG - Debug information for individual request and more detailed info about startup behavior and loading configurations. These messages can be useful for every type of problem, but particularly for addressing loading problems and issues that cannot be tied to a specific request.
Verify configurations in Carmenta Explorer
Carmenta Explorer can be a very useful tool to verify data and visualization for configurations you want to use with Carmenta Tile Engine. Note that unlike Carmenta Tile Engine, Carmenta Explorer does not automatically use tiles, so some types of visualizations may appear differently in Carmenta Explorer and Carmenta Tile Engine. In particular this is relevant for texts that use any form of label placement.
Also note that the TileLayer component in a configuration does not function in the same way as tiling in Carmenta Tile Engine and cannot be used to predict how the tiles will look in Carmenta Tile Engine.
Carmenta Explorer also has a built-in profiler that we recommend that you use for new configurations. The profiler is a good tool to detect performance bottle necks in the configuration or data that you might want to address.
Requirements
Carmenta Tile Engine can be run on relatively modest hardware and does not require any advanced graphics card. Carmenta Tile Engine can run from virtual host without any special considerations.
Memory usage is heavily dependent on what configurations you load, as most of the memory used are needed for loading data and indexing data. It is recommended that you make sure there is a bit of spare memory available to avoid running out of memory. Also make sure there is enough memory to support the cache size you set for the memory cache.
Useful links
OpenLayers, OGC API Tiles compatible web client
Acknowledgments
Acknowledgments of third-party software incorporated in Carmenta Tile Engine.
Oat++
This software uses the Oat++ web server.