API Programming guide

This section provides comprehensive information on SpacEyes3D Plugin functions and their syntax and shows how to use them to create applications.

Licenses and requirements

API features depends on authorisations embedded in the loaded SpacEyes3D project, on SpacEyes3D project contents and use mode, and on available licenses on the end user system.

For more information, see SpacEyes3D Plugin Overview

1) SpacEyes3D project requirement to use in SpacEyes3D Plugin

SpacEyes3D projects can be loaded in SpacEyes3D Plugin only if they have been created with SpacEyes3D Builder under the SpacEyes3D SDK license, and targeted for SpacEyes3D Plugin.

Project SpacEyes3D Plugin target is defined when exporting the project to the Viewer in SpacEyes3D Builder 3.4 or higher with SpacEyes3D SDK license.

2) Licenses and requirements to use API functions

The API functions are available only on projects targeted for SpacEyes3D Plugin.

Project API target (API Basic or API Pro) is defined when exporting the project in SpacEyes3D Builder with SpacEyes3D SDK.

API Pro functions are available on projects targeted for SpacEyes3D Plugin with API Pro, and according to the project use mode and available licenses (see SpacEyes3D Plugin Overview).

Use UtilityGetAvailableLicense() to get the available license on the end-user system.

Use SceneIsAPIAvailable (string sApiLevel) to know the targeted API level for the current project.

API Pro functions are marked in the API with the keyword [API Pro].

3) Capabilities

Some API functions are available only if special authorisations are given in the loaded project.

Capabilities are defined during the project creation in SpacEyes3D Builder with SpacEyes3D SDK.

API functions needing special capacities are marked in the API with the capability keyword [capability].

For instance:

bool    VectorLayerRefresh (string sLayerId)
        Refresh the layer content. [API Pro, refresh].
Before calling a function needing a special capability, capabilities can be tested with the following functions (according to the function):
        VectorLayerIsCapabilityAvailable (string sLayerId, string sCapacityName)
        MarkerLayerIsCapabilityAvailable (string sLayerId, string sCapacityName)

API overview

The API functions are organized as following:

Loading a 3D scene

The plugin 3D scene is initialized with a SpacEyes3D SPV file, previously created with SpacEyes3D Builder/SDK (GVW files are also allowed under SpacEyes3D SDK license).

         SceneLoadProject('c:/data/project.spv')

User interface customisation

The API offers various way to customize SpacEyes3D Plugin interface.

SpacEyes3D Plugin main interface is made of various panels:

Each panel can be partly customized or totally disabled in order to implement a custom interface.

A simple way to customize the interface is to define a user interface style sheet.

         UiSetStyleSheet(string sJsonStyleSheet)

See also UI Style Sheet Reference

To display simple information to the user or to create custom panels and dialogs, see the functions HtmlWindow and InfoBalloon.

See also User interface management

Camera control

Camera function allow to control the observer position in the 3D scene.

Observer position is set by :

camera.png

Camera functions offer various ways to get or to set these settings.

Most of setting functions support various transition modes: direct, progressive and fly:

Function with the keyword "relative" are dedicated to perform custom navigation buttons: they are based on a constant screen scale move quantity that provides natural movements relative to the scene, for any camera position.

See also Camera management

Interaction with the scene contents

This section explains SpacEyes3D Plugin interaction basics.

Interaction with layers

SpacEyes3D Plugin API proposes many functions that interacts with layers: through the layer manager or though specialized layer functions (GIS layers, marker layers).

Layer are accessed by an unique identification code: the layer Id. The layer Id is fixed for each layer of the project from SpacEyes3D Builder/SDK.

The following example shows the layer corresponding to the map (Id 'MAP'):

         LayerSetVisibility('MAP', true)

See also Layers management

Handling thematic views

Thematic views are embedded in SpacEyes3D project to define the end-user interface presentation of the 3D scene.

SpacEyes3D Plugin already proposes a default thematic view interface. However, through the views manager, the API also offers a direct access, and allows to develop a custom thematic views management.

See also Views management

Basic mouse management

SpacEyes3D Plugin propose low level events to catch mouse interactions.

        SceneMouseMovedEvent(int iWinX, int iWinY, int iState)
        SceneMousePressedEvent(int iWinX, int iWinY, int iState)
        SceneMouseReleasedEvent(int iWinX, int iWinY, int iState)

These events are called each time the mouse is pressed, moved or released on the 3D viewport.

These functions transmit the window coordinates in the viewport, with a state that inform about mouse button status and keyboard modifiers (Shift, Ctrl, etc.).

Catching cursor coordinates from the 3D view

SpacEyes3D Plugin provides function to pass from screen space to world space (cartographic coordinates).

        SceneGetIntersectionAtWinPos(int iX, int iY, string sMode)

Allows to pass from screen space to world space (ray tracing).

Linked to SceneMouseMoveEvent, this functions allow to catch the coordinates of the mouse cursor.

Selecting objects

Objects selection is made with the interactive selection tools: ToolInteractiveSelection(string sSelectionMode, string sLayerIdList)

Selection can be made on GIS objects in a vector layer, or on markers in a marker layer.

When the selection is done, use the following functions to get the result:

        ToolSelectionGetResultCount()
        ToolSelectionGetResult(int iIndex)

Easy developing interactions

Simple interactions with 3D objects can be defined thanks to the hyperlink macro 'sp3d_event(' SpacEyes3D Plugin can automatically reroute hyperlink events when they start with the keyword "sp3d_event(".

The macro "sp3d_event(" can be used on any hyperlink at project creation level, or on the fly on markers (style property "information.hyperlink") and info balloons.

When an hyperlink starting with the keyword "sp3d_event(" is activated, the hyperlink is automatically rerouted to the API through the following event:

        UiHyperlinkActivatedEvent(string sSource, string sTargetUrl)

For instance, if the project contains a sphere with an hyperlink 'sp3d_event("Sphere is clicked")' ; through UiHyperlinkActivatedEvent the corresponding event is emitted to the application as soon as the sphere is clicked.

Drawing objects and acquiring geometry with markers

Markers allow to add objects in a layer of the 3D model. Markers can be created directly from a given geometry and style, or created and edited interactively by the user. Interactive creation and edition functions make marker the base tool to interactively acquire or edit geometries in the 3D model.

Markers are defined by two properties:

Marker geometry is handled with a WKT string, whereas style is handled with a Json object.

Marker creation and destruction

Marker are created and destructed in a given marker layer.

   int LayerManagerCreateMarkerLayer( 
          string sParentFolderLayerId,
          string sName )

Marker creation with the API

A marker can be created inside a marker layer using the function:

   int MarkerLayerCreateMarker( 
          string sMarkerLayerId,
          string sGeometryWkt,
          string sStyleJson )

Example:

   iMarkerId = MarkerLayerCreateMarker(
          sMarkerLayerId,
          // here a red point marker is created 
          'POINT(25741 1955451)', 
          '{"pen":{"enabled":true,"width":2,"color":"#FF0000"}}' )

Marker destruction with the API:

A marker can be destroyed individualy using :

   bool MarkerLayerDestroyMarker( 
          string sLayerId,
          int iMarkerID ) 

It is possible to destroy all the markers of a marker layer at once using :

   bool MarkerLayerDestroyAllMarkers( string sLayerId )

Marker interactive creation and edition

SpacEyes3D Plugin API provides tools to interactive create and edit markers.

With interactive creation end edition tools, markers are the base to interactively acquire or edit geometries in the 3D model, and to implement custom tools.

Interactive creation:

Interactive creation allows to ask the user to create a new marker, acquiring the geometry interactively.

The two functions allowing to start the interactive marker creation are:

   int ToolInteractiveMarkerCreation( 
          string sLayerId, 
          string sGeometryType, 
          string sCreationMode, 
          string sMarkerStyle )

   int ToolInteractiveMarkerCreationStart( 
          string sLayerId, 
          string sGeometryType, 
          string sCreationMode, 
          string sMarkerStyle, 
          string sUserData )

Interactive creation accepts two parameters:

The interactive creation can be started in blocking mode using 'ToolInteractiveMarkerCreation' or in non-blocking mode via 'ToolInteractiveMarkerCreationStart'.

The blocking mode function returns when the creation is finished or cancelled.

In non-blocking mode the function returns immediately and the creation process can be followed by the application througth events which are emitted by the plugin.

In most cases the application will only listen to the following event :

     void ToolInteractiveMarkerCreationDoneEvent(
          string sLayerId, 
          int    iMarkerId, 
          bool   bOk, 
          string sUserData )

This event is emitted when the creation is finished or cancelled.

The non-blocking mode offers more controls during the creation steps thanks to the following event:

    void ToolInteractiveMarkerCreationEvent( 
          string sLayerId, 
          int    iMarkerId, 
          int    iEventType, 
          string sUserData )

This event is emitted whenever something happen in the creation process.

Event types:

Interactive edition:

Interactive creation allows to ask the user to edit interactively an existing marker.

The edition affects both geometry and style.

The two modes (blocking and non-blocking) described above for the creation are also available for the edition. The API functions are :

   bool ToolInteractiveMarkerEdition( 
         string sLayerId,
          int iMarkerId,
          string sEditionCapabilities )         

   bool ToolInteractiveMarkerEditionStart(
          string sLayerId,
          int iMarkerId,
          string sEditionCapabilities,
          string sUserData )    

And the events allowing to control the non-blocking mode are :

   void ToolInteractiveMarkerEditionDoneEvent( 
          string sLayerId, 
          int iMarkerId, 
          bool bOk, 
          string sUserData)

   void ToolInteractiveMarkerEditionEvent( 
          string qsLayerId, 
          int iMarkerId, 
          int iEventType, 
          string qsUserData)

Edition capabilities:

Capabilities are used to choose the allowed edition.

Capabilities are given in a Json object of bool values.

 - delete: bool 

Allows to delete the edited object with the 'Delete' key.

   - vertex_edit_xy: bool
   - vertex_delete: bool
   - vertex_add: bool

Vertex capabilities, edit marker geometry at vertex level. Vertex capabilities affect only geometry.

   - extrusion_edit_height: bool

Style capabilities, edit marker style.

   - bbox_resize_xyz: bool
   - bbox_edit_height: bool
   - bbox_rotate_xy: bool

BoundingBox capabilities.

Marker geometry

Geometry defines the base geometry of the marker. The geometry is a simple feature as specified in the OpenGIS Simple Feature specification. The geometry can be a point, a line, a polygon, or a collection. 2D and 2.5D (with Z) geometries are supported. Empty geometries are not supported.

The geometry is handled in the API with a WKT string.

Setting and getting geometry with the API:

   bool MarkerSetGeometry(
             string sLayerId, 
             int iMarkerID, 
             string sGeometry )

   string MarkerGetGeometry(
             string sLayerId, 
             int iMarkerID )

Here are some examples of WKT geometries:

   POINT(25668 1955765)
   POINT(25668 1955765 491)
   LINESTRING(25668 1955765,25641 1955814)
   POLYGON(25668 1955765,25641 1955814, 25660 2955785)

For Javascript applications, the API provides a class Sp3dWkt which allows to easily work with WKT objects. For more information, see Javascript WKT classes

Marker style

The style is a set of properties defining the way to draw the marker geometry.

Several API entries allow to get or set the style of a marker :

Set or get the whole style :

   bool MarkerSetStyle(
             string sLayerId, 
             int iMarkerID, 
             string sMarkerStyle )

   bool MarkerSetStyleFromSimpleDescription(
             string sLayerId, 
             int iMarkerID, 
             string sSimpleDescription )

   string MarkerGetStyle(
             string sLayerId, 
             int iMarkerID
)

Example:

   MarkerSetStyle( sMarkerLayerId,
                   iMarkerId,
                  '{"pen":{"enabled":true,"width":10,"color":"#FFFFFF"}}' )

Ser or get a single style property :

   bool MarkerSetStyleProperty( 
             string sLayerId, 
             int iMarkerID, 
             string sStyleProperty, 
             string sPropertyValue)

   string MarkerGetStyleProperty(
             string sLayerId, 
             int iMarkerID, 
             string sStyleProperty)

Example:

   MarkerSetStyleProperty( 
             sMarkerLayerId, 
             iMarkerId, 
             'pen.width', '3')

   MarkerSetStyleProperty(  
             sMarkerLayerId,  
             iMarkerId, 
             'pen.color', 
             '"#00FF00"')

   MarkerSetStyleProperty( 
             sMarkerLayerId,
             iMarkerId,
             'label.text.font',
             '{"family":"Arial","size":25}' )

The style is defined by a simple set of drawing tools:

For a full description of marker style, see the Markers style reference...

Working with vector layers and GIS data sources

SpacEyes3D Plugin introduces advanced GIS functions that allow to take control on vector layers defined in the project.

SpacEyes3D vector layers are layers based on a GIS vector data source with a style sheet that defines how to represent the GIS objects in 3D.

SpacEyes3D vector layers are powerful because they can handle very large database, and they build the 3D representation on the fly from GIS objects according to the defined style sheet.

GIS functions to control vector layers fall into 3 categories :

See also Working with GIS data sources and GIS objects

Browsing GIS data source contents

The vector layer must support the "get_gis" capability.

This function access to the GisDataSource linked to the vector layer:

        VectorLayerGetGisDataSource(string sLayerId)

This group of functions allows to read the data sources attached to the vector layer.

The API allows to get information about the data structure:

        GisDataSourceGetAttributesCount(int iDataSourceId)
        GisDataSourceGetAttributeName(int iDataSourceId, int iIndex)
        GisDataSourceGetAttributeType(int iDataSourceId, int iIndex)
        GisDataSourceGetAttributeJustify(int iDataSourceId, int iIndex)
        GisDataSourceGetAttributeWidth(int iDataSourceId, int iIndex)
        GisDataSourceGetAttributePrecision(int iDataSourceId, int iIndex)

The API allows to enumerate all objects:

        GisDataSourceGetFeatureCount(int iDataSourceId, bool bForce)
        GisDataSourceStartReading(int iDataSourceId)
        GisDataSourceStopReading(int iDataSourceId)
        GisDataSourceGetNextObject(int iDataSourceId)

The API allow access to each object geometry, attributes, and style:

        GisObjectGetGeometryAsWkt(int iDataSourceId, int iObjectId)
        GisObjectGetAttributesAsJson(int iDataSourceId, int iObjectId)
        GisObjectGetAttributeAsJson(int iDataSourceId, int iObjectId, int iIndex)
        GisObjectGetAsGeoJson(int iDataSourceId, int iObjectId)
        GisObjectGetStyle(int iDataSourceId, int iObjectId)

Synchronisation with the data source

The vector layer must support the "sync" capability.

The synchronisation rebuilds the GIS layer from the data source. This function takes advantage of the dynamic reading of the database:

        VectorLayerRefresh(string sLayerId)

If the data source is changed from the application, the synchronisation tool allows to update the 3D content in the Plugin.

All objects are updated according to their news geometry and attributes, new GIS objects are added, deleted GIS objects are removed.

Applying advanced filters

The vector layer must support the "sql" capability.

Filters are powerful because they allow to dynamically change the data source of a GIS layer.

SQL statements directly control the GIS data server and can takes advantage of the server request language: spatial operator, joint, etc.

Any change on the GIS data source must be applied on the vector layer with the synchronisation tool (Refresh).

Filters allow to perform advanced requests: A GIS layer can be prepared to store request results with a specific representation, then it's possible to change on the fly the SQL source, according to any user choice (object interactive selection, geometry acquisition with markers...) to make advanced spatial requests.

Handling errors

This paragraph explains how to properly handle SpacEyes3D Plugin errors.

Most of functions already proposes a basic handling of error with the result value: bool true or false, empty string, special value (-1...), empty object... in most of cases it can be enough.

However, to properly handling errors, the API propose a simple set of error functions:

        UtilityGetLastError()
        UtilityGetLastErrorMessage()

These functions return clearly the error that occurred during the last function call.

The error code allows to properly handle errors (according to the given errors codes in the function specifications).

The error message provides an human readable error, commonly used during debugging to understand clearly what's wrong.

For debugging convenience, all errors can be rerouted to an event handler thanks to the event:

        UtilityErrorEvent(int iErrorCode, const string qsErrorMessage)

SpacEyes3D Plugin SDK Documentation - generated on Tue Nov 5 11:39:14 2013 - SPACEYES