Detailed Description

A data source driver for the Direct Import SDK

On startup, plugins will be loaded from:

Windows: MapLink Installation/bin(64)/plugins/directimport
Non-windows: MapLink Installation/lib(64)/plugins/directimport

A driver plugin library must include a class which inherits from TSLDirectImportDriver, and must implement TSLDirectImportDriver::DriverCreationFunc.

Classes
class	CancelCallback

class	Configuration

struct	LayerInformation

Public Types
enum	DataType { DataTypeNone = 0x00 , DataTypeVector = 0x01 , DataTypeRaster = 0x02 , DataTypeTerrain = 0x04 }

enum	OverviewType { OverviewTypeNone = 0x00 , OverviewTypeNative = 0x01 , OverviewTypeGenerated = 0x02 , OverviewTypeAny = 0xFF }

typedef TSLDirectImportDriver (	DriverCreationFunc) ()

Public Member Functions
TSLDirectImportDriver::Configuration &	configuration ()

virtual bool	supportsThreadedProcessing ()

virtual TSLDirectImportDriver *	clone ()

void	inc ()
	Increment the driver's reference count.

void	dec ()

void	lock ()

void	unlock ()
	Unlock the drivers mutex.

virtual TSLDirectImportDriver::DataType	getSupportedDataTypes ()=0

virtual bool	supportsData (const char *data)=0

virtual const char *	supportedExtensions () const

virtual bool	supportsOverviews () const

virtual bool	usesTMFVector () const

virtual bool	usesEntityRendering () const

virtual bool	analyseData (const char *data)=0

virtual TSLDirectImportDriver::DataType	getTypeOfData ()=0

virtual unsigned int	numLayers ()=0

virtual TSLDirectImportDriver::LayerInformation *	layerInformation (unsigned int index)=0

virtual bool	createOverviewLayer (unsigned int baseLayerIndex, unsigned int overviewFactor, unsigned int insertAtIndex)

virtual bool	updateLayerExtent (unsigned int index, TSLDirectImportDriver::LayerInformation *layerInfo, const TSLMUExtent &extent)

virtual bool	updateLayerCoordinateSystem (unsigned int index, TSLDirectImportDriver::LayerInformation layerInfo, const TSLCoordinateSystem coordinateSystem)

virtual bool	updateLayerScale (unsigned int index, TSLDirectImportDriver::LayerInformation *layerInfo, double scale)

virtual bool	getFeatures (TSLFeatureList &featureList, unsigned int startLayer, unsigned int endLayer)=0

virtual bool	getRasterChannelStatistics (unsigned int layerIndex, unsigned int channelIndex, TSLDirectImportRasterSettings::ChannelStatistics &statistics)

virtual void	setFeatureConfig (const TSLFeatureClassConfig *featureConfig)

virtual const TSLAttributeValues *	getAttributeValues (const char featureName, const char attributeName, unsigned int startLayer, unsigned int endLayer)=0

virtual bool	preprocess ()

virtual TSLMUGeometrySet *	getVector (const TSLMUExtent &boundingBox, unsigned int startLayer, unsigned int endLayer)

virtual TSLEntitySet *	getVectorTMF (const TSLMUExtent &boundingBox, unsigned int startLayer, unsigned int endLayer)

virtual TSLDirectImportRaster *	getRaster (const TSLMUExtent &boundingBox, unsigned int layerIndex)

virtual void	setConfig (const TSLDirectImportDriver::Configuration &config)
	Set The configuration object for this driver instance.

virtual const char *	name () const =0

virtual const char *	description () const =0
	The human-readable description of the driver.

void	setCancelCallback (TSLDirectImportDriver::CancelCallback *callback)

Protected Member Functions
	TSLDirectImportDriver ()
	Constructor.

	TSLDirectImportDriver (const TSLDirectImportDriver &other)
	Copy constructor.

virtual	~TSLDirectImportDriver ()

Protected Attributes
TSLDirectImportDriver::Configuration	m_configuration

TSLDirectImportDriver::CancelCallback *	m_cancelCallback

Member Typedef Documentation

◆ DriverCreationFunc

typedef TSLDirectImportDriver *(* TSLDirectImportDriver::DriverCreationFunc) ()

Each plugin must provide a function with this signature, which creates an instance of the direct import driver class.

This function must be exported from the shared library, and be called 'createTSLDirectImportDriver'.

extern "C"
{
  TSLEXAMPLEDRIVERDLL_ TSLDirectImportDriver* createTSLDirectImportDriver()
  {
    return new ExampleDirectImportDriver();
  }
}

Member Enumeration Documentation

◆ DataType

enum TSLDirectImportDriver::DataType

The type of a data set

Applications should treat these values as a bitmask. Unless otherwise specified, functions may return a combination of data types.

A given data path may contain multiple types of data
A TSLDirectImportDriver may support multiple types of data
A TSLDirectImportDataSet will contain one type of data. Multiple data sets will be created if data contains multiple data types.

If a driver supports more than one type, the values should be combined with a bitwise OR.

DataType supportedTypes =

(DataType) (DataTypeVector | DataTypeRaster );

TSLDirectImportDriver::DataType

DataType

Definition tsldirectimportdriver.h:172

TSLDirectImportDriver::DataTypeRaster

@ DataTypeRaster

Raster data.

Definition tsldirectimportdriver.h:178

TSLDirectImportDriver::DataTypeVector

@ DataTypeVector

Vector data.

Definition tsldirectimportdriver.h:176

Enumerator
DataTypeNone	None.
DataTypeVector	Vector data.
DataTypeRaster	Raster data.
DataTypeTerrain	Terrain data.

◆ OverviewType

enum TSLDirectImportDriver::OverviewType

This enum specifies the type of a raster overview, and is used with TSLDirectImportDataLayer::createDataSets to specify which overview types should be created.

This enum may be used as a bitmask to specify multiple overview types.

Overview data sets contain the same data as their parent data set, however will be processed and displayed at a lower resolution.

Enumerator
OverviewTypeNone	No type/Not an overview data set When creating data sets used to specify that no overviews should be created
OverviewTypeNative	A Native overview, as found in the source data.
OverviewTypeGenerated	A Generated overview, created by the TSLDirectImportDataLayer based on the source data.
OverviewTypeAny	Any overview type. This is a helper bitmask used to request any type of overview from TSLDirectImportDataLayer::createDataSets

Constructor & Destructor Documentation

◆ TSLDirectImportDriver() [1/2]

TSLDirectImportDriver::TSLDirectImportDriver ( )

protected

Constructor.

◆ TSLDirectImportDriver() [2/2]

TSLDirectImportDriver::TSLDirectImportDriver ( const TSLDirectImportDriver & other )

protected

Copy constructor.

◆ ~TSLDirectImportDriver()

virtual TSLDirectImportDriver::~TSLDirectImportDriver ( )

protectedvirtual

Destructor

This class is reference counted. To delete it call TSLDirectImportDriver::dec().

Member Function Documentation

◆ analyseData()

virtual bool TSLDirectImportDriver::analyseData ( const char * data )

pure virtual

Open the provided data and perform basic analysis.

In this function the driver should determine and store a reference to

The coordinate system of the data
The extent of the data
The scale of the data

If the driver cannot determine these parameters the TSLDirectImportDataLayer will ask the application to provide them via TSLDirectImportDataLayerCallbacks. As such if this method returns false the datalayer will not immediately abort loading the data.

This should be a fast analysis. The driver should not read any geometry from the data, or perform any analysis on the features/attributes contained within the data. This should instead be done in getFeatures, getVector or getRaster.

The driver should store a copy of the 'data' parameter Unless specified otherwise all future function calls to the driver will relate to this data path.

Parameters

data	The data to analyse.

Returns: false if no analysis could be performed, true otherwise.

◆ clone()

virtual TSLDirectImportDriver * TSLDirectImportDriver::clone ( )

virtual

Clone the driver

If a driver supports processing of data in multiple threads, this method must be implemented. It will be used to clone the driver before calling getVector/getRaster from multiple threads.

The created driver must be in the same state as the original. If any load/analyse methods need to be called to setup the state the driver must do so at this point.

If this method is not implemented a single driver instance will be used for each data path. This will greatly increase loading and processing times.

lock() must be called before cloning a driver.

◆ configuration()

TSLDirectImportDriver::Configuration & TSLDirectImportDriver::configuration ( )

Query the driver's configuration data

This data may be modified in order to set driver-specific options

Returns: A reference to the driver's configuration data

◆ createOverviewLayer()

virtual bool TSLDirectImportDriver::createOverviewLayer	(	unsigned int	baseLayerIndex,
		unsigned int	overviewFactor,
		unsigned int	insertAtIndex )

virtual

Create a definition for an overview layer

This function will be called by TSLDirectImportDataLayer during basic data analysis if:

Overview datasets have been requested by the application
TSLDirectImportDriver::supportsOverviews returned true
No overview layers have been defined by the driver

If the driver is able to return data for the given overview settings it should create an additional layer definition. Layer definitions remain up to the driver to define. Future references to this layer will be made by layer index.

If the driver is not able to return data for the given overview settings it must return false.

This function will be called repeatedly until the driver returns false, or the minimum overview size is reached.

Example set of function calls:

Base layer is at index 1. A raster of 1000 x 1000 pixels
createOverviewLayer( 1, 2, 2 ); // Create an overview layer of 500 x 500 pixels, and insert at index 2
createOverviewLayer( 1, 4, 3 ); // Create an overview layer of 250 x 250 pixels, and insert at index 3

The driver should not perform any heavy processing in this function. If an overview cannot be defined without processing data at this point the driver cannot support overviews. In this case TSLDirectImportDriver::supportsOverviews must return false, leaving overview creation to the TSLDirectImportDataLayer.

Parameters

baseLayerIndex	The index of the base layer. The created overview layer will be a reduced resolution of this layer.
overviewFactor	The amount the base layer should be reduced by. This is a power of 2, starting at 2.
insertAtIndex	The index to insert the overview layer at. Overview layers are always placed largest first, immediately after the base layer definition.

Returns: true if the overview definition was created, false otherwise.

◆ dec()

void TSLDirectImportDriver::dec ( )

Decrement the driver's reference count

If the reference count reaches zero the driver will be deleted

◆ description()

virtual const char * TSLDirectImportDriver::description ( ) const

pure virtual

The human-readable description of the driver.

◆ getAttributeValues()

virtual const TSLAttributeValues * TSLDirectImportDriver::getAttributeValues	(	const char *	featureName,
		const char *	attributeName,
		unsigned int	startLayer,
		unsigned int	endLayer )

pure virtual

Query the values of an attribute

This function will be called during the import process, in order to perform feature classification.

The results should contain each different value of the specified feature, and the number of times it occurs within the data.

Parameters

featureName	The feature to query attributes for.
attributeName	The attribute to query values for.

Returns: The attribute information, including the different values and the number of times each occurs in the data.

◆ getFeatures()

virtual bool TSLDirectImportDriver::getFeatures	(	TSLFeatureList &	featureList,
		unsigned int	startLayer,
		unsigned int	endLayer )

pure virtual

Query the list of features and attributes in the data

This function will be called during TSLDirectImportDataLayer::analyseData. This function will not be called during TSLDirectImportDataLayer::loadData.

The driver must add any features from the data to the provided TSLFeatureList. Each feature in the list must contain a list of attribute names. Attribute values are not required from this function.

This function will be called repeatedly if the data contains multiple sub-layers (TSLDirectImportDataSets).

Parameters

featureList	The feature list to add new features to.
startLayer	The first layer index to process (inclusive).
endLayer	The last layer index to process (inclusive).

Returns: true if any features were added, false otherwise.

◆ getRaster()

virtual TSLDirectImportRaster * TSLDirectImportDriver::getRaster	(	const TSLMUExtent &	boundingBox,
		unsigned int	layerIndex )

virtual

Will be called to read raster data from the driver

The driver should return all raster data which overlaps the boundingBox

In most situations the driver should not perform any processing on the data, however it may perform simple operations such as a rough cull/clip if it will speed up the reading of data.

Parameters

boundingBox	The extent to return data for.
layerIndex	The layer index to query data from.

Returns: The requested raster data. Ownership of this object is transferred to the caller.

◆ getRasterChannelStatistics()

virtual bool TSLDirectImportDriver::getRasterChannelStatistics	(	unsigned int	layerIndex,
		unsigned int	channelIndex,
		TSLDirectImportRasterSettings::ChannelStatistics &	statistics )

virtual

Query the minimum and maximum values for a raster channel

This function will be called by TSLDirectImportRasterSettings::calculateChannelStatistics This function will be called after analyseRaster.

The driver does not need to implement this function, or calculate all values supported by TSLDirectImportRasterSettings::ChannelStatistics. The behaviour of this calculation will always depend on the driver implementation and data format/product.

If a value is set by the driver it must also set the corresponding validity flag to true.

Parameters

layerIndex	The index of the raster layer
channelIndex	The channel index within the raster
statistics	Storage for the calculates statistics

Returns: true if the values were calculated, false otherwise

◆ getSupportedDataTypes()

virtual TSLDirectImportDriver::DataType TSLDirectImportDriver::getSupportedDataTypes ( )

pure virtual

Query which data types this driver can read

If a driver is able to read multiple data types, the values should be combined with a bitwise OR.

◆ getTypeOfData()

virtual TSLDirectImportDriver::DataType TSLDirectImportDriver::getTypeOfData ( )

pure virtual

Query the type of the analysed data.

As with getSupportedDataTypes the driver may return a bitmask of data types.

Returns: The type(s) of the analysed data

◆ getVector()

virtual TSLMUGeometrySet * TSLDirectImportDriver::getVector	(	const TSLMUExtent &	boundingBox,
		unsigned int	startLayer,
		unsigned int	endLayer )

virtual

Will be called to read vector data from the driver

The driver should process all vector layers between startLayer and endLayer (inclusive). The driver may return vector data from the entire data extent, however should use the provided boundingBox to perform a basic clip operation.

The driver does not need to perform any styling. The driver just needs to extract geometry, feature names, and attribute values. It may use the feature configuration object to mask features/attributes but this is not required.

Parameters

boundingBox	The extent to return data for.
startLayer	The first layer index to query data from.
endLayer	The last layer index to query data from.

Returns: The requested vector data. Ownership of this object is transferred to the caller.

◆ getVectorTMF()

virtual TSLEntitySet * TSLDirectImportDriver::getVectorTMF	(	const TSLMUExtent &	boundingBox,
		unsigned int	startLayer,
		unsigned int	endLayer )

virtual

Will be called to read vector data from the driver, if usesTMFVector() == true

The driver should process all vector layers between startLayer and endLayer (inclusive). The driver may return vector data from the entire data extent, however should use the provided boundingBox to perform a basic clip operation.

The driver does not need to perform any styling, however may return preset entity rendering on the returned entity set.

Parameters

boundingBox	The extent to return data for.
startLayer	The first layer index to query data from.
endLayer	The last layer index to query data from.

Returns: The requested vector data. Ownership of this object is transferred to the caller.

◆ inc()

void TSLDirectImportDriver::inc ( )

Increment the driver's reference count.

◆ layerInformation()

virtual TSLDirectImportDriver::LayerInformation * TSLDirectImportDriver::layerInformation ( unsigned int index )

pure virtual

Query information about a layer in the analysed data

This function will be called by TSLDirectImportDataLayer during basic data analysis.

For driver-specific data a child class of LayerInfomation should be declared. If the TSLDirectImportDataLayer has to make callbacks in order to determine information about the data the returned LayerInfomation* will be modified.

If the driver uses a separate mechanism for layer management it must preserve the returned object and use its setting during data loading.

Parameters

index The index of the layer to query

Returns: Information about the layer, or NULL on error

◆ lock()

void TSLDirectImportDriver::lock ( )

Lock the driver's mutex

The driver must be locked before cloning.

◆ name()

virtual const char * TSLDirectImportDriver::name ( ) const

pure virtual

The name of the driver

The returned name will be used to uniquely identify the driver for registration and data processing. As such this function must always return the same value.

◆ numLayers()

virtual unsigned int TSLDirectImportDriver::numLayers ( )

pure virtual

Query the number of layers in the analysed data

Layers will be processed as separate TSLDirectImportDataSets where needed, however a collection of vector layers without raster between them will be processed as a single data set.

◆ preprocess()

virtual bool TSLDirectImportDriver::preprocess ( )

virtual

Perform any preprocessing operations on the data before it is read from the driver.

This function will be called during TSLDirectImportDataLayer::loadData.

This function may be overridden in derived classes to perform any preprocessing tasks before the data is read from the driver for processing.

This function will be called on the root driver instance in a single-threaded manner.

Returns: true if the preprocessing was successful, false otherwise.

◆ setCancelCallback()

void TSLDirectImportDriver::setCancelCallback ( TSLDirectImportDriver::CancelCallback * callback )

Provides a mechanism to allow a job to be cancelled.

The driver should store the value passed and use the value to determine if the current processing should be cancelled.

Parameters

callback class instance that implements the cancel() method.

◆ setConfig()

virtual void TSLDirectImportDriver::setConfig ( const TSLDirectImportDriver::Configuration & config )

virtual

Set The configuration object for this driver instance.

◆ setFeatureConfig()

virtual void TSLDirectImportDriver::setFeatureConfig ( const TSLFeatureClassConfig * featureConfig )

virtual

Set the feature/attribute configuration to use when loading data.

This function will be called during TSLDirectImportDataLayer::loadData.

The driver may use this information while loading data, however it is not required to.

◆ supportedExtensions()

virtual const char * TSLDirectImportDriver::supportedExtensions ( ) const

virtual

Query the file extension(s) supported by this driver

If multiple file extensions are supported, they should be separated with a semi-colon.

If no extensions are returned, the direct import datalayer will try to use this driver for any extension, and call supportsData for every loaded file.

return "tif;jpg;jpeg"

Returns: The file extensions supported by the driver.

◆ supportsData()

virtual bool TSLDirectImportDriver::supportsData ( const char * data )

pure virtual

Query whether a driver supports a data file

The driver should not process the data when this method is called. It should only perform the checks required to test whether the data is supported by the driver.

Parameters

data	Path to the data. This may be a file, folder or any other identifier if supportedExtensions returned NULL.

Returns: true if the driver supports the data, false otherwise

◆ supportsOverviews()

virtual bool TSLDirectImportDriver::supportsOverviews ( ) const

virtual

Query whether the driver supports overview layers

If overview data sets are supported by the driver it is expected to provide an implementation of TSLDirectImportDriver::createOverviewLayer. The driver will also be expected to handle definitions of overview layers in getRaster.

If overview data sets are not supported by the driver they may still be exposed by TSLDirectImportDataLayer however will be handled by down-sampling the base data set accordingly. In this situation the driver doesn't need any handling of overview data sets in getRaster.

Returns: true if the driver supports overview layers, false otherwise. Default false.

◆ supportsThreadedProcessing()

virtual bool TSLDirectImportDriver::supportsThreadedProcessing ( )

virtual

Query whether a driver supports threaded processing

If this function returns true the driver must be thread safe and must implement TSLDirectImportDriver::clone.

A single driver instance will not be accessed from multiple threads at once, however multiple threads may access a single driver instance sequentially.

Returns: true if the driver supports threaded processing, false otherwise.

◆ unlock()

void TSLDirectImportDriver::unlock ( )

Unlock the drivers mutex.

◆ updateLayerCoordinateSystem()

virtual bool TSLDirectImportDriver::updateLayerCoordinateSystem	(	unsigned int	index,
		TSLDirectImportDriver::LayerInformation *	layerInfo,
		const TSLCoordinateSystem *	coordinateSystem )

virtual

Update layer information with information provided by the application

This function will be called during TSLDirectImportDataLayer::createDataSets, if a coordinate system was specified by the application

For most drivers the default implementation will suffice, and will simply update the following

LayerInformation.m_coordinateSystem

If this method is overridden the child driver must set this variable, or call back to the base implementation to do so.

Parameters

index	The index of the layer to update.
layerInfo	The LayerInformation to update, as queried from TSLDirectImportDriver::layerInformation.
coordinateSystem	The coordinate system as provided by the application.

Returns: true if the coordinate system was set, false otherwise. Returning false will cause this dataset to be discarded.

◆ updateLayerExtent()

virtual bool TSLDirectImportDriver::updateLayerExtent	(	unsigned int	index,
		TSLDirectImportDriver::LayerInformation *	layerInfo,
		const TSLMUExtent &	extent )

virtual

Update layer information with information provided by the application

This function will be called during TSLDirectImportDataLayer::createDataSets, if an extent was specified by the application

For most drivers the default implementation will suffice, and will simply update the following

LayerInformation.m_extent

If this method is overridden the child driver must set this variable, or call back to the base implementation to do so.

Parameters

index	The index of the layer to update.
layerInfo	The LayerInformation to update, as queried from TSLDirectImportDriver::layerInformation.
extent	The extent as provided by the application.

Returns: true if the extent was set, false otherwise. Returning false will cause this dataset to be discarded.

◆ updateLayerScale()

virtual bool TSLDirectImportDriver::updateLayerScale	(	unsigned int	index,
		TSLDirectImportDriver::LayerInformation *	layerInfo,
		double	scale )

virtual

Update layer information with information provided by the application

This function will be called during TSLDirectImportDataLayer::createDataSets, if a scale was calculated by the data layer

For most drivers the default implementation will suffice, and will simply update the following

LayerInformation.m_scale

If this method is overridden the child driver must set this variable, or call back to the base implementation to do so.

Parameters

index	The index of the layer to update.
layerInfo	The LayerInformation to update, as queried from TSLDirectImportDriver::layerInformation.
scale	The scale as calculated by the data layer.

Returns: true if the scale was set, false otherwise. Returning false will cause this dataset to be discarded.

◆ usesEntityRendering()

virtual bool TSLDirectImportDriver::usesEntityRendering ( ) const

virtual

Query whether the driver returns vector data with pre-set entity rendering

This capability should only be used for compatibility with legacy import mechanisms, or where the driver is unable to support feature rendering. If this capability is used the driver must return vector data as TMF.

Returns: true if the driver uses entity rendering, false otherwise. Default false.

◆ usesTMFVector()

virtual bool TSLDirectImportDriver::usesTMFVector ( ) const

virtual

Query whether the driver returns vector data as TMF/TSLEntity based classes

This capability should only be used for compatibility with legacy import mechanisms. Wherever possible the driver should return vector data using the default TSLMUGeometry hierarchy, which provides a more flexible interface to the TSLDirectImportDataLayer.

If this method returns true the datalayer will call getVectorTMF instead of getVector.

Returns: true if the driver returns data as TMF, false otherwise. Default false.

Member Data Documentation

◆ m_cancelCallback

TSLDirectImportDriver::CancelCallback* TSLDirectImportDriver::m_cancelCallback

protected

◆ m_configuration

TSLDirectImportDriver::Configuration TSLDirectImportDriver::m_configuration

protected

Detailed Description

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ DriverCreationFunc

Member Enumeration Documentation

◆ DataType

◆ OverviewType

Constructor & Destructor Documentation

◆ TSLDirectImportDriver() [1/2]

◆ TSLDirectImportDriver() [2/2]

◆ ~TSLDirectImportDriver()

Member Function Documentation

◆ analyseData()

◆ clone()

◆ configuration()

◆ createOverviewLayer()

◆ dec()

◆ description()

◆ getAttributeValues()

◆ getFeatures()

◆ getRaster()

◆ getRasterChannelStatistics()

◆ getSupportedDataTypes()

◆ getTypeOfData()

◆ getVector()

◆ getVectorTMF()

◆ inc()

◆ layerInformation()

◆ lock()

◆ name()

◆ numLayers()

◆ preprocess()

◆ setCancelCallback()

◆ setConfig()

◆ setFeatureConfig()

◆ supportedExtensions()

◆ supportsData()

◆ supportsOverviews()

◆ supportsThreadedProcessing()

◆ unlock()

◆ updateLayerCoordinateSystem()

◆ updateLayerExtent()

◆ updateLayerScale()

◆ usesEntityRendering()

◆ usesTMFVector()

Member Data Documentation

◆ m_cancelCallback

◆ m_configuration