Inheritance diagram for TSLRasterDataLayer:

Detailed Description

Specialist data layer for the handling of rasters.

Raster files may be added and removed from the data layer. These will be displayed when they are attached to a TSLDrawingSurface.

Note: The TSLRasterDataLayer can be used to load Raster Pyramids, but if so, a valid TSLPathList must be added to the TSLDataLayer. The path list must contain the parent directory of the Raster Pyramid.

Instances of this class should be destroyed using the destroy method.

Public Member Functions
	TSLRasterDataLayer ()

bool	addMask (const char rasterName, const char maskName)

bool	addRaster (const char *rasterName, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, bool preload=true)

bool	addRasterWithWorldFile (const char *rasterName, bool preload, double xscale, double yscale, double xoffset, double yoffset)

bool	appendData (const char *fileName)

void	cacheFlushLimit (int flush_limit)

int	cacheFlushLimit () const

void	cacheSize (int new_size)

int	cacheSize () const

bool	changeRasterHue (int hue)

bool	clearCache ()

bool	configurePersistentCache (const TSLPersistentCacheData settings, TSLTileValidationFn validationFn=NULL, void arg=NULL)

void	deleteBufferData (unsigned char *buffer) const

bool	deleteMask (const char *rasterName)

bool	getMask (const char *rasterName, TSLSimpleString &maskName) const

bool	getRasterTMCExtent (const char raster_name, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC *y2) const

bool	loadDataFromBuffer (unsigned char *data_stream, TSLSize data_len)

const char *	operator[] (int index) const

bool	removeRaster (const char *raster_name)

bool	saveData (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION, const bool saveRasters=false, const TSLRasterType format=TSLRasterTypeTiff, const int compressionFactor=2, const bool saveAsCombinedImageMask=true) const

unsigned char *	saveDataToBuffer (TSLTMC *data_len, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION) const

bool	setOverrideCol (const char *raster_name, TSLTMC override_colour=0)

bool	setRasterTMCExtent (const char *raster_name, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2)

bool	setTransparent (const char *raster_name, bool trans_mode=false, TSLStyleID trans_colour=0)

bool	setVisible (const char *raster_name, bool visibility=true)

int	size () const

bool	validateCache ()

void *	operator new (size_t size) TSL_NO_THROW

void *	operator new (size_t size, char *filename, int line)

Public Member Functions inherited from TSLDataLayer
void	addDrawingCallback (TSLDataLayerDrawingCallback *drawingCallback)

bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)

bool	addLoader (TSLFileLoader loader, TSLLoaderAppCallback callback, void arg, TSLAllLoadedCallback allLoadedCallback=0, void *arg2=0)

bool	addPathList (const TSLPathList *path_list)

void	cancelFlashback ()

bool	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)

TSLDataHandler *	createDataHandler (const char *config_file=0)

TSLHistoryVersion	currentVersion () const

TSLDataHandler *	dataHandler ()

const TSLDataHandler *	dataHandler () const

void	destroy ()

bool	entityIsVisible (const TSLEntity entity, const TSLDrawingSurface drawingSurface) const

const TSLFeatureClassList *	featureList () const

const TSLFeatureClassList *	featureList (const char *detailLayerName) const

bool	fileModificationTime (const char *filename, TSLTimeType &lastModificationTime)

TSLEntity *	findEntity (TSLTMC x, TSLTMC y, TSLTMC aperture, int depth, const char *featureName=0, int drawingSurfaceID=-1)

bool	findFile (const char *filename, TSLSimpleString &foundPath) const

void	flashbackToTimestamp (TSLHistoryTimestamp timestamp, TSLLayerArchiveCallback archiveCallback, void *arg=0)

void	flashbackToTimestamp (TSLHistoryTimestamp timestamp, TSLLayerArchiveTileCallback archiveTileCallback, void *arg=0)

void	flashbackToVersion (TSLHistoryVersion version, TSLLayerArchiveCallback archiveCallback, void *arg=0)

void	flashbackToVersion (TSLHistoryVersion version, TSLLayerArchiveTileCallback archiveTileCallback, void *arg=0)

bool	getActiveLayerName (const TSLEnvelope &extent, double screenResolution, TSLSimpleString &activeLayerName) const

TSLEntityIterator *	getEntityIterator (const char detailLayer, TSLSelector selector=NULL, TSLEnvelope *extent=NULL, bool splitOptimisedPrimitives=true)

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributes result) const

TSLFileLoader *	getLoader ()

bool	getMUExtent (double x1, double y1, double x2, double y2, int drawingSurfaceID=-1) const

bool	getTMCExtent (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int drawingSurfaceID=-1) const

bool	getUUExtent (double x1, double y1, double x2, double y2, const TSLDrawingSurface *drawingSurface) const

bool	importHistory (TSLHistoryVersion mapVersion, TSLHistoryTimestamp timestamp, TSLHistoryImportSet *historySet)

bool	latLongToTMC (double latitude, double longitude, TSLTMC x, TSLTMC y, bool local=false) const

bool	latLongToTMC (int num, double latitudes, double longitudes, TSLTMC xs, TSLTMC ys, bool local=false) const

TSLDataLayerTypeEnum	layerType () const

bool	loadData (const char *filename)

bool	loadRendering (const char *filename)

void	notifyChanged (bool changed=true)

TSLMapQuery *	query (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int depth=-1, const char *featureName=NULL, int drawingSurfaceID=-1) const

TSLMapQuery *	query (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, TSLSelector *selector, int drawingSurfaceID=-1) const

const TSLCoordinateSystem *	getCoordinateSystem () const

bool	queryVersionHistory (const TSLEnvelope &extent, TSLVersionHistorySet &history)

void	refreshFlashback ()

bool	removeData ()

void	releaseResources (int surfaceID)

bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)

bool	setCoordinateSystem (const TSLCoordinateSystem *coordinateSystem)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int value)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double value)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool value)

bool	setFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributes value)

bool	TMCToLatLong (TSLTMC x, TSLTMC y, double latitude, double longitude, bool local=false, bool boundCheck=true) const

bool	TMCToLatLong (int num, TSLTMC xs, TSLTMC ys, double latitudes, double longitudes, bool local=false) const

const TSLVersionHistorySet *	versionHistory () const

Protected Member Functions
	~TSLRasterDataLayer ()

Constructor & Destructor Documentation

◆ TSLRasterDataLayer()

TSLRasterDataLayer::TSLRasterDataLayer ( )

Default constructor.

◆ ~TSLRasterDataLayer()

TSLRasterDataLayer::~TSLRasterDataLayer ( )

inlineprotected

Obsolete deprecated function - map to documented version Protected destructor to stop being instantiated on the stack Forces user to use new operator and destroy method.

Member Function Documentation

◆ addMask()

bool TSLRasterDataLayer::addMask	(	const char *	rasterName,
		const char *	maskName )

Add a mask to the raster.

Select the 1-bit raster to use as a mask. The 1-bit mask should be the same size as the raster. Pixels set in the mask will allow the equivalent raster pixel to be drawn. Pixels clear in the mask will prevent the equivalent pixel being drawn.

This will replace any mask currently in use.

Parameters

rasterName	the name of the raster to attach the mask to.
maskName	the name of the mask file.

Returns: true if ok.

◆ addRaster()

bool TSLRasterDataLayer::addRaster	(	const char *	rasterName,
		TSLTMC	x1,
		TSLTMC	y1,
		TSLTMC	x2,
		TSLTMC	y2,
		bool	preload = true )

Add a raster image to data layer.

This method allows the user to add a raster image to the TSLRasterDataLayer. The visibility of the raster is defaulted to true.

Note, this method can be used to load Raster Pyramids, but if so, a valid TSLPathList must be added to the TSLDataLayer. The path list must contain the parent directory of the Raster Pyramid.

Parameters

rasterName	Name of the raster file.
(x1,y1)	Bottom left corner of the raster image in internal co-ordinate (TMC).
(x2,y2)	Top right corner of the raster image in internal co-ordinate (TMC).
preload	If true, the raster image is loaded in memory when calling this function. If false, the image is loaded in memory later on at drawing time. Default value is true. If not preloaded, then the image is destroyed after it is used. This keeps memory usage to a minimum but has an impact on display performance.

Returns: true on success, false otherwise.

◆ addRasterWithWorldFile()

bool TSLRasterDataLayer::addRasterWithWorldFile	(	const char *	rasterName,
		bool	preload,
		double	xscale,
		double	yscale,
		double	xoffset,
		double	yoffset )

Given a raster filename, searches for a world file of the expected name in the same directory, and if one is found, loads the raster into the layer and uses the world file to set its extents.

If a user has a map data layer/coordinate system that was created/defined to have the same MUs as the world file, the values passed for the xscale/yscale and xoffset/yoffset can be queried from the map data layer's coordinate system or standalone coordinate system via calls to getLinearScaling and getMapOffsets respectively. Otherwise the user will need to specify scalings and offsets to allow the raster to be located correctly in relation to other geo-located data present in the drawing surface.

The format of a World File is very well described by the following Wikipedia article:

http://en.wikipedia.org/wiki/World_file

The following summarizes the contents of the world file:

line 1: x-dimension of a pixel in map units
line 2: rotation parameter
line 3: rotation parameter
line 4: NEGATIVE of y-dimension of a pixel in map units
line 5: x-coordinate of center of upper left pixel
line 6: y-coordinate of center of upper left pixel

MapLink only handles images where the rotation values are zero. An error will be logged if either line 2 or 3 has a non-zero value.

The minX, maxX and minY, maxY are computed:

minX = line5 - 0.5 * line1
maxX = minX + (double)width  * line1
maxY = line6 - 0.5 * line4
minY = maxY + (double)height * line4

Notes:

If minY is not less than maxY then the values are swapped.
The width and height are the raster size in pixels.

Parameters

rasterName	full path of the raster to load
preload	true if the raster is to be loaded into memory now, false if it should be loaded when drawn
xscale,yscale	number of TMCs per map unit
xoffset,yoffset	offsets to the map origin in TMCs.

Returns: true if successful, false if no data is loaded.

◆ appendData()

bool TSLRasterDataLayer::appendData ( const char * fileName )

This method appends the meta-data to this TSLRasterDataLayer (the meta-data was originally created by a call to saveData being called on an instance of a TSLRasterDataLayer).

Note: this method only loads positioning information and configuration options for each raster in the layer. The original rasters will be required when reloading.

Parameters

fileName The fileName to load.

Returns: true on success, false on error.

◆ cacheFlushLimit() [1/2]

int TSLRasterDataLayer::cacheFlushLimit ( ) const

Query the current flush limit.

When the cache is full the system will remove the least recently used files to make room for the new data to load. The cache flush limit indicates the number of most recently used data files that the system will try keep in memory while flushing the cache. If the system cannot free enough memory and keep the flush limit number of files it will temporarily halve the flush limit until the cache memory usage is below 90% of the allowable cache size.

The tile cache is used for the reduced raster tiles.

Returns the current flush limit.

◆ cacheFlushLimit() [2/2]

void TSLRasterDataLayer::cacheFlushLimit ( int flush_limit )

Sets cache flush limit.

This method allows the user to set the cache flush limit for the TSLRasterDataLayer. When the cache is full the system will remove the least recently used files to make room for the new data to load. The cache flush limit indicates the number of most recently used data files that the system will try keep in memory while flushing the cache. If the system cannot free enough memory and keep the flush limit number of files it will temporarily halve the flush limit until the cache memory usage is below 90% of the allowable cache size.

The tile cache is used for the reduced raster tiles.

Parameters

flush_limit Number of most recently used data files that the system will try to keep in memory while flushing the cache.

◆ cacheSize() [1/2]

int TSLRasterDataLayer::cacheSize ( ) const

Query the amount of memory that the cache may currently use, in Kilobytes.

◆ cacheSize() [2/2]

void TSLRasterDataLayer::cacheSize ( int new_size )

Set maximum size of the tile cache.

This method allows the user to set the amount of memory that the tile cache can use. To operate more efficiently the TSLRasterDatalayer holds data in memory so that it does not need to reload data from disk every time a draw request is made. The larger the cache size the more data can be held in memory and draw requests are handled much more efficiently. However the client application must find a compromise between a large cache size and the memory requirements of the application itself.

The default tile cache is 32MB (32768 KB)

The tile cache is used for the reduced raster tiles.

Parameters

new_size Size of the cache in kilobytes.

◆ changeRasterHue()

bool TSLRasterDataLayer::changeRasterHue ( int hue )

Modifies the hue for rasters in the data layer. Note that this method modifies the in-memory raster. Valid values are in degrees from -180 to

Calling this method with a value of 0 will return the raster to its original hue.

Note that this operation is not supported on Unix.

Parameters

hue	Number of degrees to offset the raster's hue from its original value.

Returns: true on success, or false if there was an error.

◆ clearCache()

bool TSLRasterDataLayer::clearCache ( )

Clear the tile cache for this TSLRasterDataLayer.

This method requests the TSLRasterDataLayer to clear all cached data from memory and delete the files from the persistent cache (if used). After a call to clearCache any draw operation involving the TSLRasterDataLayer will re-load all required map data from its original location.

The tile cache is used for the reduced raster tiles.

Returns true on success, false otherwise.

◆ configurePersistentCache()

bool TSLRasterDataLayer::configurePersistentCache	(	const TSLPersistentCacheData *	settings,
		TSLTileValidationFn	validationFn = NULL,
		void *	arg = NULL )

Adds and configures a persistent tile cache.

A persistent tile cache may be used to speed up the loading of tiles which have been downloaded via a slow connection, eg. web-based.

A persistent tile cache works in parallel to the memory tile cache. If a tile is not found in memory, then the persistent tile cache is searched. If it is found in the persistent tile cache, then the (optional) tile validation function is called to verify that the file is up-to-date. If so, then the tile is loaded and added to the memory tile cache. If the tile is not found in the persistent tile cache, then if configured, a local search may be performed using the TSLPathList added to the TSLDataLayer. If the tile is found locally or is invalid, it is added to the memory cache and optionally to the persistent cache. If the tile is not found locally, then it may be returned in the failure list of the draw function, if specified.

In releases of MapLink later than 4.6 SP1, the persistent cache will also store relevant configuration files for the map - e.g. the .map, .pal, .dtl and .pth files.

Parameters

settings	A TSLPersistentCacheData object containing the settings to use for the persistent cache.
validationFn	This is an optional function that may be used to validate any tiles that are in the cache, prior to them being used. If not specified, then all tiles in the cache are deemed to be valid.
arg	An optional argument that will be passed to the user's validation function.

◆ deleteBufferData()

void TSLRasterDataLayer::deleteBufferData ( unsigned char * buffer ) const

Delete buffer returned from saveDataToBuffer.

This method must be used to delete the buffer after a call to 'saveDataToBuffer'. If this does not happen then memory will be leaked.

Parameters

buffer Buffer to be deleted, returned from saveDataToBuffer.

◆ deleteMask()

bool TSLRasterDataLayer::deleteMask ( const char * rasterName )

Removes a mask from the raster.

Parameters

rasterName the name of the raster to remove the mask from.

Returns: true if ok.

◆ getMask()

bool TSLRasterDataLayer::getMask	(	const char *	rasterName,
		TSLSimpleString &	maskName ) const

This method queries the mask file name associated with the raster

Parameters

rasterName	raster filename
maskName	mask filename (returned).

Returns: true if the method succeeds, false otherwise.

◆ getRasterTMCExtent()

bool TSLRasterDataLayer::getRasterTMCExtent	(	const char *	raster_name,
		TSLTMC *	x1,
		TSLTMC *	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Query extent of raster tile in internal TMC co-ordinates.

Parameters

raster_name	Name of raster to get extent of.
(x1,y1)	Storage for bottom left co-ordinate.
(x2,y2)	Storage for top right co-ordinate.

◆ loadDataFromBuffer()

bool TSLRasterDataLayer::loadDataFromBuffer	(	unsigned char *	data_stream,
		TSLSize	data_len )

Load meta-data from a data buffer.

This method allows the user to load the meta-data into this TSLRasterDataLayer from the given buffer. Any data which is currently in the layer will be deleted. The management of the buffer is the user's responsibility.

Note: this method only loads positioning information and configuration options for each raster in the layer. The original rasters will be required when reloading.

Parameters

data_stream	Address of the first byte of the buffer to be loaded onto the Data Layer.
data_len	Size of the buffer to be loaded.

Returns: true on success, false on error.

◆ operator new() [1/2]

void * TSLRasterDataLayer::operator new ( size_t size )

Allocation override for API redirection.

◆ operator new() [2/2]

void * TSLRasterDataLayer::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

◆ operator[]()

const char * TSLRasterDataLayer::operator[] ( int index ) const

Queries read-only raster name at specified index.

Parameters

index Index into set to return

Returns: read-only entity pointer, NULL on error.

◆ removeRaster()

bool TSLRasterDataLayer::removeRaster ( const char * raster_name )

Remove existing raster from TSLRasterDataLayer.

This method allows the user to remove a raster image from the TSLRasterDataLayer.

Parameters

raster_name Name of the raster file.

Returns: true on success, false otherwise.

◆ saveData()

bool TSLRasterDataLayer::saveData	(	const char *	filename,
		TSLMapLinkVersion	ver = TSL_CURRENT_MAPLINK_VERSION,
		const bool	saveRasters = false,
		const TSLRasterType	format = TSLRasterTypeTiff,
		const int	compressionFactor = 2,
		const bool	saveAsCombinedImageMask = true ) const

Saves meta-data to specified file.

This method allows the user to save the meta-data of the TSLRasterDataLayer to the given filename.

Note:

If saveRasters is false then this method only stores positioning information and configuration options for each raster in the layer. The original rasters will be required when reloading.
If saveRasters is true, then the rasters will be copied, if a filename exists, to the same directory as the meta-data file. If a filename does not exist, the raster is saved in the specified format as long as the raster has not been created as a raster pyramid. This functionality is related to the TSLFilterLayer.

Parameters

filename	Save data file name.
ver	the MapLink version to save as
saveRasters	If set to true saves/copies the rasters loaded into the layer to the same directory as the meta-data file is saved to.
format	Specifies the format to save the rasters in.
compressionFactor	Specifies the compression factor for JPEG and JPEG 2000 (range 2..255)
saveAsCombinedImageMask	This affects the saving of rasters which are not pyramid rasters. The default is to save the mask and raster as one file. Setting this option to false causes the image and mask to be saved as two files.

Returns: true on success, or false on error.

◆ saveDataToBuffer()

unsigned char * TSLRasterDataLayer::saveDataToBuffer	(	TSLTMC *	data_len,
		TSLMapLinkVersion	ver = TSL_CURRENT_MAPLINK_VERSION ) const

Create a buffer and save meta-data to it.

This method allows the user to save meta-data from this TSLRasterDataLayer to a buffer. A buffer is created, whose size is returned. It is the user's responsibility to free the buffer using the 'deleteBufferData' call.

Note: this method only stores positioning information and configuration options for each raster in the layer. The original rasters will be required when reloading.

Parameters

data_len	Storage for size of the data to be saved.
ver	the MapLink version to save as

Returns: the address of the buffer where the data has been saved.

◆ setOverrideCol()

bool TSLRasterDataLayer::setOverrideCol	(	const char *	raster_name,
		TSLTMC	override_colour = 0 )

Set the colour of a monochrome raster image.

raster_image: File name of the raster image attached to the TSLRasterDataLayer.

override_colour: Colour to be used when drawing the set bits of the monochrome raster. This value is either an index in the colour table used by the TSLDrawingSurface or a composed RGB value. See tslcolourhelper.h for information on how to create this value.

Returns true on success, false otherwise.

◆ setRasterTMCExtent()

bool TSLRasterDataLayer::setRasterTMCExtent	(	const char *	raster_name,
		TSLTMC	x1,
		TSLTMC	y1,
		TSLTMC	x2,
		TSLTMC	y2 )

Resets the extent of raster tile in internal TMC co-ordinates.

Parameters

raster_name	Name of raster to get extent of.
(x1,y1)	Storage for bottom left co-ordinate.
(x2,y2)	Storage for top right co-ordinate.

◆ setTransparent()

bool TSLRasterDataLayer::setTransparent	(	const char *	raster_name,
		bool	trans_mode = false,
		TSLStyleID	trans_colour = 0 )

Set transparency mode for raster - Windows platforms only.

This method allows the user to set the transparency mode for the given raster image attached to the TSLRasterDataLayer. The transparency mode defaults to false when a raster is added to the TSLRasterDataLayer.

Parameters

raster_name	File name of the raster image attached to the TSLRasterDataLayer.
trans_mode	True for the raster image to be transparent. Default value is false.
trans_colour	Colour of the raster image to be transparent. This value is a colour index in the colour table used by the TSLDrawingSurface. Default value is 0, for no colour to be transparent.

Returns true on success, false otherwise.

◆ setVisible()

bool TSLRasterDataLayer::setVisible	(	const char *	raster_name,
		bool	visibility = true )

Set visibility of raster.

This method allows the user to set the visibility of the raster image attached to the TSLRasterDataLayer. The visibility of a raster defaults to true.

Parameters

raster_name	Name of the raster attached to the TSLRasterDataLayer.
visibility	True for visible, false if this raster tile not to be visible in the TSLRasterDataLayer.

Returns: true on success, false otherwise.

◆ size()

int TSLRasterDataLayer::size ( ) const

Returns the number of raster items in the data layer.

◆ validateCache()

bool TSLRasterDataLayer::validateCache ( )

Validate the tiles in the persistent tile cache for this TSLRasterDataLayer.

Returns true on success, false otherwise.

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ TSLRasterDataLayer()

◆ ~TSLRasterDataLayer()

Member Function Documentation

◆ addMask()

◆ addRaster()

◆ addRasterWithWorldFile()

◆ appendData()

◆ cacheFlushLimit() [1/2]

◆ cacheFlushLimit() [2/2]

◆ cacheSize() [1/2]

◆ cacheSize() [2/2]

◆ changeRasterHue()

◆ clearCache()

◆ configurePersistentCache()

◆ deleteBufferData()

◆ deleteMask()

◆ getMask()

◆ getRasterTMCExtent()

◆ loadDataFromBuffer()

◆ operator new() [1/2]

◆ operator new() [2/2]

◆ operator[]()

◆ removeRaster()

◆ saveData()

◆ saveDataToBuffer()

◆ setOverrideCol()

◆ setRasterTMCExtent()

◆ setTransparent()

◆ setVisible()

◆ size()

◆ validateCache()