Oracle Spatial and Graph – technical tips, best practices, and news from the product team

  • March 18, 2020

Visualizing Oracle Spatial Map Visualization Component (formerly MapViewer) themes using the Open Source Mapbox GL JS API

Carol Palmer
Senior Principal Product Manager

This guest post is by Liujian Qian.


Since the release of MapViewer, and the Oracle Spatial Map Visualization Component 19.1.0 (which contains all the essential functions of Oracle FMW MapViewer) there has been a lesser known but powerful new feature called “Vector Tile Service”. This service can be used to generate and stream vector tiles that contain data for a single pre-defined SMVC (Spatial Map Visualization Component) theme on the fly.

Vector tiles, in case you are wondering, is a compact binary data format where each vector tile (divided geographically according to the same popular World Mercator tiling scheme used by many world-map services) can contain geometry and attribute data for one or more map layers. For more details about Vector Tiles, check out the Mapbox blog here.

Note that SMVC currently does not cache previously generated vector tiles, unlike image map tiles which are typically cached to the disk.

So how do you visualize large volumes of Oracle Spatial managed spatial data using vector tiles? Currently SMVC does not provide any tool out of the box for visualizing the vector tiles it generates, but there are a number of open source API options, including the OpenLayers API and the Mapbox GL JS API.  In this blog we will show an example of using the Mapbox API, but the same concept applies when using the OpenLayers API.


How to run the example

The above screenshot illustrates what you will see when you run this demo. Note that the demo has been tested with SMVC version 19.1.

All the files and source code for the demo are located here:  https://github.com/ljqian/oraclemaps. To run this example, you must already have SMVC 19.1 or MapViewer installed and running, with the “mvdemo” sample data schema defined as a SMVC data source named “mvdemo”.  Note that if you didn’t have this data schema or data source defined, you can still run the demo by changing the name of the data source and the theme, as well as the properties used in the example for showing a popup. Also, it is best that your own theme contains point type geometries which are what the demo is designed to show.  It is trivial to modify the demo code so that other types of geometries such as linestring or polygon can be displayed.  The vector tiles generated by SMVC can contain any type of geometries.

If your SMVC or MapViewer server is up and running, the next step is to copy the demo files to your application’s web server document folder so you can open the demo.html page in a browser.

The demo code itself is entirely embedded in the demo.html file, with detailed comments to help understand the code. If you are already familiar with the Mapbox GL JS API in general then the demo should be fairly easy to understand. 

Stylesheet for the background world map

The demo starts by creating a new Mapbox Map instance. Its background map uses the image map tiles hosted on Oracle Maps Cloud Service. The image tiles are part of a SMVC tile layer. Note that Oracle Maps Cloud Service can only be used for demo purposes and cannot be incorporated into an end-user application.

In the demo’s map-styles sub-folder you will find the JSON stylesheet for the world-map as well as the accompanying sprites and fonts, which are not used in this demo but might be useful down the road in a more sophisticated application.  If you want to use your own SMVC defined tile layer as your application map’s background, just make sure the tile layer is created using the Google-like Web Mercator tiling scheme, as any other tile scheme will not work with Mapbox GJ JS. To use your own SMVC defined tile layer as a background", you will need to change the JSON stylesheet so that it references tiles generated from your local SMVC instance instead of the one running on Oracle Maps Cloud Service.

Do note that while this demo displays a background map that is based on a SMVC (image) tile layer, you can easily switch to a Mapbox or OpenStreetMap hosted background (world) maps which can be either image or vector tile based.  If you already have a subscription account with Mapbox and custom maps then those are likely what you will be using as background maps.

Displaying Theme and Showing a Pop-up

The rest of the demo code is clearly documented as inline comments and should be self-explanatory. The key steps are:

  1. Defining a Mapbox vector tile source. In this case it includes a single URL for fetching the SMVC generated vector tiles for the given SMVC theme “CUSTOMERS”.
  2. Defining a Mapbox map layer (out of the vector tile source) including its rendering details or “paint”. Since our vector tile source contains only one layer, this is pretty straightforward as well.
  3. Adds a “click” listener so that when you click on a customer feature on the map, a pop-up will be displayed. In the event listener we are simply adding all the attributes for the clicked customer to a very simple pop-up.  Note that the attribute names correspond to the names of the “Info” columns defined in your SMVC theme.

We hope this simple demo provides enough information to get you started developing your own SMVC vector tile applications using the Mapbox GL JS API.

Final Note

  While any given vector tile generated by SMVC can only contain one pre-defined theme, that does not mean in your application's map visualization you are limited to showing only one such theme at a time. Using the Mapbox API (or OpenLayers) you are free to add as many data layers as needed, as long as you define the source for each and add the theme contained in it as a layer to the Mapbox Map object. The below screenshot shows such a map where three different SMVC themes (customers, sales territories and inter-state highways) are displayed on top of a single background map. Here the "customers" layer is displayed using Mapbox API's heatmap rendering type, while the territories and highways are displayed using the fill and line rendering types. At run time for each area on the map that falls inside a tile's bounding box, 4 separate tile requests will be made, one to get the background map's tile, and one each for a vector tile containing the customers, sales territories and highways data.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.