TatukGIS Developer Kernel 11

User Tools

Site Tools

guides:overview:overview

Table of Contents

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 and introductory GIS Tutorial for Delphi, Java, Python, C# and VB.

Portability

Despite language differences, the various TatukGIS Developer Kernel product editions 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. Using 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:

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 )

DK.Python: 

  layer = TGIS_LayerSHP()
  layer.setPath("states.shp")
  GIS.Add( layer )

Therefore, the remainder of this document describes the API relationship 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 the most basic and commonly used part of the API when creating a new application. The Viewer can be considered a container that holds the whole map and is responsible for rendering the map on the user's device.

Every map is constructed from several 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, and then the next layer is drawn above 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“
    This is 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 the Viewer will refresh its content if necessary), include:

Layer

A 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 format file
  • a digital elevation model or other grid files
  • 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 a DXF layer)

A layer knows 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.)

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. Nevertheless, 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 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.

Basic layer operations

  • check if layer is attached to the Viewer (property Viewer)
  • set (but before attaching to the Viewer) or read the unique layer name (property Name)
  • check the 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 a file or server data (property IsPersistent)
  • provide access to sublayers (if any) (property SubLayers)

Layer inheritance

  • “ TGIS_Layer“
    A basic layer object which implements a 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 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 without a physical representation on a disk).

Vector layers

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

  • in-memory
    when all information is stored right in the memory, some disk-based formats must 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 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 a given layer supports shape type(s). A similar layer restriction applies to supported dimensions: X and Y (2D), XYZ (3D), and XYZM (3D + Measure). The property SupportedDimensions queries for which dimensions a given layer supports.

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.

Suppose a vector layer contains coordinate system (projection, etc.) information upon being attached to the Viewer. In that case, the layer is (if necessary) automatically reprojected on-the-fly to the coordinate system selected in the Viewer. It 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 accomplished 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 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 kept 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).

Basic operations

Links lead to the Delphi version of the documentation.

  • verify which shape types and dimensions a layer supports (properties SupportedShapes and SupportedDimensions)
  • create a shape and add to the Viewer (function CreateShape)
  • retrieve a shape by unique identifier (procedure GetShape)
  • directly access shape(s) that reside in-memory (property Items)
  • find a shape located 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 the memory; due to the memory footprint required, only relatively small data sets can be managed this way; an example of such data is the ASCII Grid format, and generally all formats that are stored as a text file.
  • on-demand
    when data is read on demand, and the memory footprint is minimized, TIFF and BMP are examples of such layers.

As with vector layers, pixel layers with coordinate system information are automatically reprojected on-the-fly to the Viewer coordinate system when attached 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.

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 constituting 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 automatically.
  • Every linear feature should have at least two vertices (sometimes referred to as points). With any TatukGIS-created line shape, this is ensured automatically.
  • A shape can contain X and Y coordinate information only, XYZ (3D), or XYZM (3D + Measure).
  • For proper operations, each shape should be topologically correct:
    • polygons not twisted
    • lines and polygon outlines are free of loops (no incidences of self-crossing)
    • shapes in the same layer never overlap
    • polygon perimeters have 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. Nevertheless, some operations are strictly dependent on a layer relationship:

  • saving and reading is done on the layer level
  • a shape has no knowledge about the 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 permitted 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 a 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 ”\\”.
  • Python users should always use ”/” in a path.

Open map

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

That's all!

Change map mode to allow zooming/dragging

  • Let's extend the previous sample by adding 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 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.

Find a shape by clicking on the map

  • Let's extend the previous sample by adding a “select” button.
// 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 the 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 by adding a button called “Create Shape”.
// button "Create Shape" click event


//let's find out 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 by adding 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, the loop only through shapes with field labels 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. 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:

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 the locations on an application canvas, is implemented in “TGIS_GpsNmea”.

Data set connector

Non visual Data set connector, used to connect a 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”.

2023/03/15 10:08

Page Tools

©2023 TatukGIS. All Rights Reserved.
Send feedback Translate