Documentation | API Overview
This document introduces basic concepts about the TatukGIS API. It is not a comprehensive reference guide - the TatukGIS API consists of thousands of methods and classes. This document provides more of a bird-eye overview.
The various TatukGIS Developer Kernel product editions, despite language differences, share the same API across all supported development platforms. The same API can be used on VCL, FMX, WinForms, WPF, ActiveX, Java Swing, and even with TatukGIS Editor scripting. The use of the term “Same API” does not mean class naming and everything else is 100% the same - this is not possible due to platform technology differences. Still, the code across platforms is highly similar. The sample below, written on six very different platforms, demonstrates the high level of code similarity:
layer = new TGIS_LayerShp() ; layer.Path = "states.shp" ; GIS.Add( layer ) ;
layer = new TGIS_LayerShp() ; layer.Path = "states.shp" ; GIS.Add( layer ) ;
layer = new TGIS_LayerSHP() ; layer.Path = "states.shp" ; GIS.Add( layer ) ;
DK.Delphi (VCL and FMX frameworks):
layer := TGIS_LayerShp.Create ; layer.Path := 'states.shp' ; GIS.Add( layer ) ;
DK.FMX v.11 for iOS/Andriod (Delphi):
layer := TGIS_LayerSHP.Create ; layer.Path := 'states.shp' ; GIS.Add( layer ) ;
layer = new TGIS_LayerSHP() ; layer.setPath("states.shp") ; GIS.Add( layer )
layer = TGIS_LayerSHP() layer.setPath("states.shp") GIS.Add( layer )
Therefore, in the remainder of this document, the API relationship is described without reference to a particular platform and language.
This chapter casts some light on basic API concepts such as shape, layer, and viewer and the relationship between these concepts.
The Viewer is probably the most basic and commonly used part of the API when creating a new application. The Viewer can be thought of as a container that holds the whole map and is responsible for rendering the map on the user device.
Every map is constructed from a number of layers, with each layer typically containing a different kind of map feature, e.g., borders, lakes, cities, roads, etc.
After placing the
TGIS_ViewerWnd component on a form, for simplicity we usually (as is done in all the source code samples) rename this component to GIS. Let's take a look at what happens if we use the code:
GIS.Open( 'world.shp' ) ;
Basically, the Viewer will:
TGIS_Viewer.FullExtentto fully place the layer inside the Viewer and then repaint the whole Viewer
So what happens if we call:
GIS.Open( 'myproject.ttkproject' ) ;
The viewer will:
TGIS_Viewer.Lockto avoid reading multiple layers
Layers in the Viewer draw in the order starting from Item to Item[n]. This means the first added layer is drawn at the bottom, then the next layer is drawn above it, and so on.
TGIS_Viewer, it just contains the
TGIS_Viewerobject and implements
IGIS_Viewerinterface. Why does it not inherit? A component must inherit from platform specific controls. Without this, the component cannot be placed on a form.
Visual operations done automatically upon user mouse/touch activity, include:
Non-visual operations (though the Viewer will refresh its content if necessary), include:
A layer is an object that holds map data, which can be:
A layer has knowledge about the coordinate system and where the layer should be placed on the globe:
Extentholds information about the surroundings of a layer in coordinate system units
CSholds the layer coordinate system information (projection, etc.)
The Viewer contains layers, though a layer can exist without the Viewer. Without assigning a layer to the Viewer (but upon calling
Open method on a layer), most methods and properties are still available. Never-the-less, some operations strictly depend on a Viewer relationship:
Locate, etc., in which coordinates are passed, expect coordinates in the Layer coordinate space; if a layer is attached to the Viewer, generally a Viewer coordinate space is expected; so, basically, if a layer is assigned to the Viewer, the matter of coordinate conversion can be forgotten because this is handled by the Viewer coordinate space and the Layer↔Viewer relationship.
The vector layer is a kind of container for geometric shapes. A vector layer can contain one or many shapes. Vector layers fall into two main categories:
Generally, a vector layer can hold any type of shape feature (e.g., points, lines, polygons). Some vector formats, however, such as the SHP format, permit only one shape type per file. The property SupportedShapes is used to query for which shape type(s) are supported by a given layer. A similar layer restriction applies to supported dimensions: X and Y (2D), XYZ (3D), andXYZM (3D + Measure). The property SupportedDimensions queries for which dimensions are supported by a given layer.
One specific consideration to be remembered is, due to the possibility of an on-demand scenario, a shape retrieved by GetShape or fetched by a Loop is valid only temporarily. Therefore, a pointer to this shape can be invalid upon the next iteration. To make a pointer validity persistent, call:
persistent_shp = shp.MakeEditable
No direct property gives access to a list of all shapes. Shapes can be read on-demand for layers containing millions of entities. Property items give access only to in-memory items. To query for items within a layer, the recommended way is to use iterators like:
foreach( tmpshp in lv.Loop( layer.Extent, “CITYNAME like 'New%' ) begin tmpshp.IsSslected = true ; end ;
Furthermore, Loop iterator allows querying for shapes that have a topological relationship to another shape using the DE-9IM model (to find spatial relationships between shapes such as touch, within, intersect, etc.). Together with TGIS_Topology.MakeBuffer, this gives the means to perform advanced spatial querying and analysis.
If a vector layer contains coordinate system (projection, etc.) information, upon being attached to the Viewer the layer is (if necessary) automatically reprojected on-the-fly to the coordinate system selected in the Viewer. This means layers can be attached to the Viewer without concern for the coordinate system of each layer - all layers are presented smoothly together in the Viewer coordinate system. This also means all layer and shape operations are performed by default in the Viewer coordinate system. So, for example, loading and editing shapes are performing using the Viewer coordinate system.
TatukGIS has no concept of a “native” layer format or even a preferred format. All layers have the same interface, open/save transparently, and are treated equally. All data formats are read directly without any kind of transcoding. Therefore, SHP, MIF, TAB, Oracle Spatial, and all other supported formats can be considered “native”, making data format selection solely a matter of customer choice. Remember, however, not everything is supported on all supported formats. For example, SHP format specifications permit saving only one shape type per file, whereas GML has no such restriction. On the other hand, SHP is faster with huge layers than text-based GML. For some layers (i.e., formats) TatukGIS has implemented only reading support, so there is no ability to write data to such layers (typically due to insufficient customer demand and/or the greater difficulty of offering write support for formats that are not openly documented).
Links lead to the Delphi version of the documentation.
A pixel layer can hold a bitmap (photo) or a grid (such as a digital elevation model). As with vector layers, image layers can be:
As with vector layers, pixel layers with coordinate system information are, when attached to the Viewer, automatically reprojected on-the-fly to the Viewer coordinate system (if necessary).
Grid layers attached to the Viewer are automatically treated as a DEM (digital terrain model), so other image layers and 2D vectors are automatically draped over the grid layer.
As with vector layers, TatukGIS has no “native” or preferred pixel layer format, so format selection is solely a matter of customer choice. All supported pixel layers have the same interface, open/save transparently without any format conversion, and are treated equally.
A vector layer shape object is responsible for storing the geometric information for a single feature.
A vector layer contains shapes. A shape, however, can exist without being assigned to a layer. Never-the-less, some operations are strictly dependent on a layer relationship:
This chapter offers a few very basic operations to demonstrate using the API.
TGIS_ViewerWndon a form and rename it to GIS.
GIS.Open( DATA_PATH + “World\WorldDCW\world.shp”)
// button "Zoom" click event GIS.Mode = TGIS_ViewerMode.ZoomEx; // button "Drag" click event GIS.Mode = TGIS_ViewerMode.Drag;
That's all! Now, after clicking on the “Zoom” button, moving the mouse with the left mouse button depressed will cause map zooming. After clicking on the “Drag” button, moving the mouse with the left mouse button pressed will cause map dragging.
// button "Select" click event GIS.Mode = TGIS_ViewerMode.Select;
// map TapSimple event // event passes X, Y coordinates shp as TGIS_Shape // ignore clicking if mode is other then select if GIS.Mode <> TGIS_ViewerMode.Select then exit // convert screen coordinates to map coordinates ptg as TGIS_Point ptg = GIS.ScreenToMap( Point( Round(X), Round(Y) ) // deselect all previously selected shapes lv as TGIS_LayerVector lv = (TGIS_LayerVector)(GIS.Items) lv.DeselectAll // calculate precision of location as 5 pixels precision as Double ; precision = 5 / GIS.Zoom ; // let's try to locate a selected shape on the map shp as TGIS_Shape shp = (TGIS_Shape)( GIS.Locate( ptg, precision ) ) ) // not found? if shp = null then exit // mark shape as selected shp.IsSelected = not shp.IsSelected // and refresh a map GIS.InvalidateSelection
That's all! Now upon clicking the “Select” button, the map changes to select mode and any click on the map selects/deselects a shape.
// button “Create Shape" click event // let's find if such layer already exists ll as TGIS_LayerVector ll = GIS.Get( “edit layer” ) if ll <> null then exit ; // create a new layer and add it to the viewer ll = new TGIS_LayerVector ll.Name = “edit layer” ll.CS = GIS.CS // same coordinate system as the viewer // in a previous sample we created a solid polygon // to make it nicer we need it to be transparent ll.Params.Area.OutlineColor = TGIS_Color.Blue ll.Params.Area.Pattern = TGIS_BrushStyle.Clear //Add layer to the viewer GIS.Add( ll ) // create a new shape and immediately add it to the layer shp as TGIS_Shape // create a shape and add it to polygon shp = ll.CreateShape( TGIS_ShapeType.Polygon ) ; // we group operations together shp.Lock( TGIS_Lock.Extent ) ; shp.AddPart // shape can have multiple parts like islands, holes // add some vertices shp.AddPoint( new TGIS_Point( 10, 10 ) ); shp.AddPoint( new TGIS_Point( 10, 80 ) ); shp.AddPoint( new TGIS_Point( 80, 90 ) ); shp.AddPoint( new TGIS_Point( 90, 10 ) ); shp.Unlock // unlock operation, close polygon if necessary // and now refresh map GIS.InvalidateWholeMap
That's all! Now, upon clicking on the “Add Shape“ button, a new vector layer is created and a new shape (covering part of Europe) is added.
// button “Find shapes" click event // lets find if such layer already exists ll as TGIS_LeyerVector ll = GIS.Get( “edit layer” ) if ll = null then exit ; // lets get a layer with world shape // names are constructed based on layer name lv as TGIS_LayerVector ; lv = GIS.Get( “world” ) // deselect all previously selected shapes lv.DeselectAll // and we need a created shape, with we want // to use as selection shape selshp as TGIS_Shape selshp = ll.GetShape(1) // just a first shape form the layer // for file based layer we should pin shape to memory // otherwise it should be discarded selshp = selshp.MakeEditable // so now we search for all shapes with DE9-IM relationship // which labels starts with 's' (with use of SQL syntax) // in this case we find “T*****FF*” contains relationship // which means that we will find only shapes inside the polygon tmpshp as TGIS_Shape ; foreach( tmpshp in lv.Loop( selshp.Extent, “label LIKE 's%'”, selshp, “T*****FF*” ) begin tmpshp.IsSslected = true ; end // and now refresh map GIS.InvalidateWholeMap
That's all! Now, upon clicking on the “Select shapes” button, we will:
In just a few steps we have illustrated basic concepts for working with the Viewer, layers, and shapes.
To compile samples and open within the IDE requires the TatukGIS Developer Kernel, trial or retail version. The download of either version includes an extensive set of source code samples, including the very basic samples discussed here.
The resulting map looks like this:
Source and compiled versions of this sample for supported platforms can be found here:
Along with the Viewer component featured in this API overview, the TatukGIS Developer Kernel includes a number of other components.
Viewers are responsible for map rendering and presentation.
Legend control, responsible for rendering on an application canvas a tree of layers, ordering/reordering layers, and visual style editing, is implemented in
Scale component, responsible for rendering scale bar on an application canvas, is implemented in
North Arrow control, responsible for rendering a compass rose on an application canvas, is implemented in
Attributes control, responsible for rendering and editing shape attributes (fields) on an application canvas, is implemented in
GPS control, capable of direct reading NMEA data from a Com Port or LocationServices and rendering the locations on an application canvas, is implemented in
Non visual Data set connector, used to connect a vector layer into grid controls, is implemented in
Along with the basic Viewer/Layer/Shape operations, a number of high-level classes perform some common tasks. This subchapter mentions most of these common tasks.
Exporting Viewer content as an image is implemented in
Printing is implemented on each platform separately to match platform specific requirements and is available as
Creating vector contours from a grid image layer is implemented in
Geocoding and reverse-geocoding layers (without calling some web service to do this) is implemented in
Image or vector layer rectification, using polynomial transformation of the 1st, 2nd, an 3rd order and Ground Control Points (GCP), is implemented in
TGIS_TransformPolynomial and is available in
Basic shape topological checks, fixes, relational operations, making buffers, etc. are implemented in
Common utility functions like creating a point, finding an extent or intersection, etc., are implemented in