User Tools

Site Tools


guides:overview:overview

API Overview

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.

Portability

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 event with TatukGIS Editor scripting. Use of the term “Same API” does not mean class naming and everything else is 100% 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:

DK.NET (C#):

  layer = new TGIS_LayerShp() ;
  layer.Path = "states.shp"  ;
  GIS.Add( layer )  ;

DK.ASPNET (C#):

  layer = new TGIS_LayerShp() ;
  layer.Path = "states.shp"  ;
  GIS.Add( layer )  ;

DK.ActiveX (C#):

  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 )  ;

DK.Swing (Java):

  layer = new 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.

Basic concepts

This chapter casts some light on basic API concepts such as shape, layer, and viewer and the relationship between these concepts.

Viewer

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.

How the viewer works

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:

  • close any existing map
  • open the file ‘world.shp’
  • verify the format of the file and create a corresponding layer object, in this case TGIS_LayerShp
  • open the newly created layer using TGIS_Layer.Open method
  • add the layer object to the Viewer using TGIS_Viewer.Add method
  • and finally, call TGIS_Viewer.FullExtent to 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:

  • open the file 'myproject.ttkproject'
  • because the file is recognized as a TatukGIS project, the viewer will:
    • call TGIS_Viewer.Lock to avoid reading multiple layers
    • add each layer by layer as described in a previous topic
    • for each layer, assign corresponding parameters such as color, width, etc., if these parameters exist in the project file; if not, a default is applied
    • if project extent is stored in the project file, assign the TGIS_Viewer.Extent; if not, the viewer will call TGIS_Viewer.FullExtent
    • and, finally, call TGIS_Viewer.Unlock to release any pending redraw

Layers in the Viewer draw in the order starting from Item[0] to Item[n]. This means the first added layer is drawn at the bottom, then the next layer is drawn over it, and so on.

Viewer inheritance

  • IGIS_Viewer
    Defines the general Viewer API (the API all viewers must implement).
  • TGIS_Viewer
    A basic Viewer object that does not know how to draw the map, but knows how to handle layers.
  • TGIS_ViewerWnd
    A Viewer object responsible for visual presentation on a screen. This component is typically dropped on an application form. It DOES NOT inherit from TGIS_Viewer, it just contains the TGIS_Viewer object and implements IGIS_Viewer interface. Why does it not inherit? A component must inherit from platform specific controls. Without this, the component cannot be placed on a form.
  • TGIS_ViewerBmp
    Similar to TGIS_ViewerWnd, but non-visual and rendered to a bitmap instead of to a screen. However, the Viewer content will never be updated automatically. To render a map, draw TGIS_ViewerBmp.Draw.

Basic viewer operations

Visual operations done automatically upon user mouse/touch activity, include:

  • Zooming/Swiping
  • Dragging

Non-visual operations (though Viewer will refresh its content if necessary), include:

Layer

Layer is an object that holds map data, which can be:

  • a vector file, such as SHP format file
  • an image, such as a Jpeg image file
  • a digital elevation model or other grid file
  • a SQL server connection to vector or image data
  • a web service connection, such as to a WMS
  • a layer that contains sublayers (an example is DXF layer)

A layer has knowledge about the coordinate system and where the layer should be placed on the globe:

  • property Extent holds information about the surroundings of a layer in coordinate system units
  • property CS holds the layer coordinate system information (projection, etc.)

A Viewer contains layers, though a layer can exist without a 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:

  • property Name is set before attaching layer to the Viewer and uniquely identifies a layer within the Viewer
  • by changing an Active property, visibility of a layer within the Viewer can be set
  • by using property ZOrder or Move, the layer order within the Viewer is set
  • all methods such as Loop, Locate, etc., in which coordinates are passed, expect coordinates in a 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.

Basic layer operations

  • check if layer is attached to the Viewer (property Viewer)
  • set (but before attaching to the Viewer) or read the layer unique name (property Name)
  • check layer path (or connection string for server layers) (property Path)
  • open newly constructed layer (method Open)
  • change the order position of the Layer in the Viewer (method Move and property ZOrder)
  • turn layer on/off upon rendering (property Active)
  • check if layer can be saved or exported to (property IsExportable)
  • check if layer has a persistent representation, such as for file or server data (property IsPersistent)
  • provide access to sublayers (if any) (property SubLayers)

Layer inheritance

  • TGIS_Layer
    A basic layer object which implements very common layer functionally shared by all types of layers. This object should not be created directly.
    • TGIS_LayerVector
      A basic layer object which implements a vector layer (layer in which geometries are stored as sets of coordinates). This object can be created directly to an in-memory layer (a layer that has no a physical representation on a disk).
    • TGIS_LayerPixel
      A basic layer object which implements a pixel layer (layer containing an image or grid data). This object can be created directly to an in-memory layer (a layer with no a physical representation on a disk).

Vector layers

Vector layer is a kind of container for geometric shapes. A vector layer can contain one or many many shapes. Vector layers fall into two main categories:

  • in-memory
    when all information is stored right in memory; some disk based formats are required to be fully loaded into memory, such as DXF, GML, and generally all formats stored as a text file.
  • on-demand
    when data is read on demand. This category includes SHP, SQL layer based formats, and all binary formats.

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 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 not openly documented).

Basic operations

Links are leading to Delphi version of the documentation.

  • verify which shape types and dimensions layer supports (properties SupportedShapes and SupportedDimensions)
  • create a shape and add to Viewer (function CreateShape)
  • retrieve a shape by unique identifier (procedure GetShape)
  • directly access shape(s) that reside in-memory (property Items)
  • find a shape on a particular coordinate (function Locate)
  • query layer to find and edit all shapes using DE-9IM relationship-to-shape query and/or attribute query (for each enumerator Loop)
  • build a new layer with a corresponding storage file or SQL data (procedure Build)
  • access UID list of selected shapes (property SelectedList)
  • deselect all selected shapes (method DeselectAll)
  • restructure layer (procedures AddField, DeleteField, RenameField)
  • import/export layer from/to another vector layer of a different format (procedures ImportLayer and ExportLayer)

Pixel layers

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:

  • in-memory
    when all information is stored right in memory; due to memory footprint required, only relatively small data sets can be managed this way; an example of such data is ASCII Grid and generally all formats stored as a text file.
  • on-demand
    when data is read on demand and memory footprint is minimized; TIFF and BMP are examples of such layers.

As with vector layers, pixel layers with coordinate system information, when attached to the Viewer, are (if necessary) automatically reprojected on-the-fly to the Viewer coordinate system.

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.

Basic operations

Shape

A vector layer shape object is responsible for storing the geometric information for a single feature.

Geometry construction:

  • Every shape contains one or more parts. For example, one part of a polygon shape might represent the main area while other parts of the same polygon shape might represent holes or islands.
  • Each shape part is formed by one or more vertices which constitute geometry. Vertices are TGIS_Point or TGIS_Point3D type.
  • For every polygonal area part, the first and last vertices should be the same (which means the shape is closed). With any TatukGIS created polygonal shape, closure is ensured.
  • Every linear feature should have at least two vertices (sometimes referred to as points). With any TatukGIS created line shape, this is ensured.
  • A shape can contain X and Y coordinate information only, XYZ (3D), or XYZM (3D + Measure).
  • For proper operations, shapes should be topologically correct:
    • polygons not twisted
    • line and polygon outlines free of loops (no incidences of self-crossing)
    • shapes in the same layer never overlap
    • polygon perimeters has clockwise winding and interior (holes) have counter-clockwise winding
    • shape method FixShape ensures all the above

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:

  • saving and reading is done on the layer level
  • a shape has no knowledge about coordinate system; without a layer relationship, a shape's coordinates are treated only as “somewhere” and functions such as LenghtCS and AreaCS do not work
  • selecting/deselecting shapes requires a layer relationship
  • in most situations, attributes (data fields) are connected to geometry on the vector layer level (which, for example, manages .DBF file access); so, without a layer, a shape is generally only a pure geometric object

Basic shape operations

Shape inheritance

  • TGIS_Shape
    A basic shape object which implements very common layer functionality shared by all types of vector layers. This object should not be created directly.
    • TGIS_ShapePoint
      point (marker) feature; only one part and only one vertex allowed
    • TGIS_ShapeMultiPoint
      multi-point (marker) feature; one or more parts allowed, but each part allowed to have only one vertex
    • TGIS_ShapeArc
      poly-line (arc) feature; one or more parts allowed, each part has multiple vertices
    • TGIS_ShapePolygon
      poly-polygon (area) feature; one or more parts allowed, each part has multiple vertices
    • TGIS_ShapeComplex
      a container which can hold any number of the basic shape objects mentioned above
    • Other objects
      Another object, constructed from the above types and specific to particular format, can exist.

A very basic sample

This chapter offers a few very basic operations to demonstrate using the API.

Step by Step

We assume:

  • you have installed the sample dataset.
  • any use of DATA_PATH is equivalent to TGIS_Utils.GisSamplesDataDir() .
  • C#, C++ and JAVA users should be aware that we use “\” in a path and should replace it with ”\\”.

Open map

  • Place TGIS_ViewerWnd on a form and rename it to GIS.
  • Add a button and in button handler method add:
GIS.Open( DATA_PATH + “World\WorldDCW\world.shp”)

Thats all!

Change map mode to allow zooming / dragging

  • Let's extend the previous sample and add two buttons called “zoom” and “drag”.
  • Create button extender methods:
// 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 left mouse button depressed will cause map zooming. After clicking on the “Drag”, moving mouse with left mouse button pressed will cause map dragging.

Find a shape by clicking on the map

  • Let's extend the previous sample and add a button called “select”.
// button "Select" click event
GIS.Mode = TGIS_ViewerMode.Select;
  • And add an event handler for event GIS.TapSimple.
// 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[0])
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.

Create new shape object

  • Let's extend the previous sample and add a button called “Create 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.

Find all shapes within polygon

  • Let's extend the previous sample and add a button called “Find shapes”.
// 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:

  • loop through all shapes matching the DE-9IM relationship to the shape created in the previous sample
  • furthermore, will loop only through shapes with field label starting with 's'
  • looped shapes become selected.

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. Download of either version includes an extensive set of source code samples, including the very basic samples discussed here.

The resulting map looks like:

Source and compiled versions of this sample for supported platforms can be found here:

Components

Along with the Viewer component featured in this API overview, the TatukGIS Developer Kernel includes a number of other components.

Viewers

Viewers are responsible for map rendering and presentation.

Visual viewers, responsible for rendering to an application canvas, is implemented in TGIS_ViewerWnd. Non-Visual viewer, responsible for producing a bitmap, is implemented in TGIS_ViewerBmp.

Legend

Legend control, responsible for rendering on an application canvas a tree of layers, ordering/reordering layers, and visual style editing, is implemented in TGIS_ControlLegend.

Scale

Scale component, responsible for rendering scale bar on an application canvas, is implemented in TGIS_ControlScale.

North Arrow

North Arrow control, responsible for rendering a compass rose on an application canvas, is implemented in TGIS_ControlNorthArrow.

Attributes

Attributes control, responsible for rendering and editing shape attributes (fields) on an application canvas, is implemented in TGIS_ControlAttributes.

GPS

GPS control, capable of direct reading NMEA data from a Com Port or LocationServices and rendering locations on an application canvas, is implemented in TGIS_GpsNmea.

Data set connector

Non visual Data set connector, used to connect vector layer into grid controls, is implemented in TGIS_DataSet.

Advanced operations

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.

Image exporting

Exporting Viewer content as an image is implemented in TGIS_PixelExportManager

Printing

Printing is implemented on each platform separately to match platform specific requirements and is available as TGIS_PrintManager.

Contouring

Creating vector contours from a grid image layer is implemented in TGIS_ContourGenerator.

Triangulation

Routing

Routing and generally finding a path within a network are implemented in TGIS_ShortestPath, TGIS_Network and TGIS_IsochroneMap.

Geocoding

Geocoding and reverse-geocoding layers (without calling some web service to do this) is implemented in TGIS_AddressMatching.

Georeferencing / rectification

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 TGIS_Layer.Transform property.

Interpolation

Image interpolation is implemented in TGIS_InterpolationKriging, TGIS_InterpolationIDW, and TGIS_GaussianHeatmap.

Topology

Basic shape topological checks, fixes, relational operations, making buffers, etc. are implemented in TGIS_Topology.

Utilities

Common utility functions like creating a point, finding an extent or intersection, etc., are implemented in TGIS_Utils.

2018/08/02 09:29