The JS-GIS data model

Table of contents

Basic assumptions

Static data. JS-GIS allows to browse static maps, which are published as images and HTML imagemaps by a dedicated software (the publisher program) from a GIS system. User can navigate through different themes, move the map, find a location, query objects by clicking on the map and having the linked data displayed in web pages. However, all the data is statically generated, and can be updated only re-running the publisher program on the GIS system. User cannot perform typically dynamic tasks like: creating new map objects, editing data, performing SQL queries, customize map layers. Maps are generated at fixed zoom levels, so the user cannot set a precise map scale which hasn't been included in those levels; maps are cut in tiles, so the user cannot center a map exactly on a point, but just load the tile containing that point.

Client-side lightweight computing. JS-GIS has been designed as a client-side tool for dynamically view geographic data which can published on the web, or an intranet, as well as on a CD-ROM. The aim of JS-GIS is distributing geographic data without the need of mapping servers or mapping client components. The weight of the whole API is less than 50Kbytes.

Georeferenced data. Everything in JS-GIS passes through a geografic reference. This means, for example, that a point file can be loaded and displayed regardless of map's current scale, theme or imagemap. A geo-index can be built in order to find objects according to their geographical location. This also means that there is no hard-coded link to images or files, so GIS publishers can modify already deployed projects adding or removing map themes, zoom levels or clickable data without the need to modify the whole publications, as the new parts will fit in place automatically thanks to geographic reference.

Tile-based model. A tile is a portion of a map suitable for visualization. Maps are statically cut in tiles by the publisher software, and visualized by JS-GIS browser pages. A map cut in tiles looks like a chessboard: every tile can be identified by a row and column number. Tiles are georeferenced, too, so JS-GIS can load in a map window the appropriate tile according to the geographic coordinates of a point that has to be shown on it.

Overview of the JS-GIS 2 data model

The JS-GIS data model describes:

  1. procedures to export maps from a GIS system in order to make them accessible from a JS-GIS browser;
  2. a common terminology for describing JS-GIS objects and operations;
  3. an OOP framework for handling published data.

The OOP JS-GIS 2 API described in this document is just one of the possible implementations of the data model object framework. The first version of JS-GIS API (formerly WebStaticMapper) didn't use object oriented programming techniques. A future implementation could introduce new objects or replace existing ones.

Although the API objects will be highlighted in the next chapter, we will use here an OOP terminology to describe the data model.

From a GIS perspective, the layer has to be considered the base class. A layer corresponds roughly to a mappable table, i.e. a database table in which every record has a geographic representation (a point, a polygon, or a line). A layer can be shown in a map window or drawn in a map layout. A map window usually contains more than one layer, and the GIS user can arrange or customize the map layers, deciding which will be visible, in which order, and which symbols use to draw them. There is a strict distinction between data and its representation: the same layer can be mapped in many different ways, and layer attributes can be used to produce thematic maps, i.e. to symbolize objects according to their properties. Moreover, zooming in and out and panning a map window is done smoothly as vector data can be drawn precisely through a great range of map scales. The user can click on a map and select layer objects in order to view or edit associated data.

In JS-GIS, however, this ability to dynamically view and query layers is dramatically reduced. Map windows are substituted by HTML image tags in which appropriate map tiles are loaded. Only a single image tile can be shown at a time, so JS-GIS themes are already combined maps rather than single-layer maps. User cannot rearrange the layers in a map, as the map settings are decided at publish time. Only imagemaps are exact representation of single layers, and can be loaded in the map to allow user to query map objects. Zooming is obtained by exporting maps at fixed, different zoom levels; the zoom levels setting is decided at publish time. Map themes and imagemaps must be associated to existing zoom levels in order to be exported and read by the JS-GIS browser interface.

So, the publisher program needs to export already-defined maps into sets of tiles, one set per zoom level. The same has to be done with imagemaps. Along with exporting maps and layers, the publisher must export a project definition file, which tells JS-GIS how exported maps are organized.


A JS-GIS Project holds all the information needed to read a GIS exported into a JS-GIS compliant format. A project is described by a single instance of a TProject JS-GIS API object. All the information needed to manage JS-GIS data will be contained in a TProject variable. The project doesn't hold the data itself; rather, it holds reference to the published data, like file names and locations, file types, image size and so on: it groups zoom levels, themes and imagemaps under a single shell.

The publishing software must be able to write a JavaScript file containing the instance definition of a project. This file must be included after the JS-GIS library in the JS-GIS application page in order to make published data accessible.

Future versions may include map projection information and allow multi-project interfaces to run (i.e. will handle passing from a national-scale project to different single regional-scale projects).

Zoom levels

The project contains a list of zoom levels, represented by TZoomLevel objects in the JS-GIS API. All the maps in a project are (can be) exported only at the fixed zoom levels of that project. At present, from 1 up to 10 zoom levels can be used per project.

A zoom level holds all the data common to all the geographic data exported at that zoom:

Please note that the zoom level reprents the geographic extent of all the tilesets exported at that zoom level, as origin and tile size and number are the same. Due to the fact that a given tile geographic size (i.e. the map zoom) may or may not divide exactly the project width/height, different extents can result. The project should get the minimum extent resulting from all its zoom levels.

For example, if the project extent has been defined (in the publisher program) as an 800 x 900 km rectangle, but the first zoom level has a 1000 km zoom, then a single 1000x1000 tile will be generated at that zoom level. The tile will contain a portion outside the project's extent. Possibly at smaller zooms a more precise subdivision will be generated: at a zoom of 100 meters, an 8 x 9 tile grid will be generated, and the zoom extent will be the same as the project's extent.


The project holds a list of themes, which can be viewed as single thematic maps, and which are represented by TTileSet objects in the JS-GIS API. Each theme may be defined for one up to all zoom levels: this means that a certain theme could not be accessible at a certain zoom level. Currently, theme attributes are:


Map Interactivity is managed by imagemaps, represented by TTileSet objects in the JS-GIS API. Imagemaps are a vector representation of mapping objects in graphic coordinates, and can be associated to geographically-matching themes in order to produce interactive maps, i.e. the user can choose which map to show independently from which map layer to query.

Currently, imagemaps attributes are:


"Document" is a wide-range term to identify published objects other than themes and imagemaps. Usually documents are html pages containing attribute data for the map objects; but there can be other kind of documents, like mappable objects definitions.

Documents are not currently represented by JS-GIS classes; this could be done in future versions, but probably there isn't a need to do so. Handling documents is really an application-specific issue, so it's difficult to establish a common framework.

The usual approach is to generate documents using a /docroot/layername/record-id.html convention, and to implement the imagemaps HREFs as JavaScript function calls like showInfo(layername, record-id), where showInfo is a custom-defined function that loads the requested document in an appropriate frame.

Map objects documents, like point lists, can be implemented as javascript files which can be included with <script src=...> tags in the map page, and which can populate a Map object's drawList with object definitions. See TMap and TMapObject for further discussion.

JS-GIS © 2001, 2002 by Luca S. Percich (
Last updated: dec 26, 2002