MapLink Pro 11.1.1.0.
Envitia MapLink Pro: The Ultimate Mapping Application Toolkit
Loading...
Searching...
No Matches
TSLViewShedDataLayer Class Reference
Inheritance diagram for TSLViewShedDataLayer:

Detailed Description

This data layer provides a simple interface to the terrain viewshed API and the ability to visualise a viewshed within a drawing surface.

The results of the viewshed calculation will be displayed as a single raster. This raster will have the feature name 'ViewShed', and may be manipulated in the same fashion as any other MapLink feature on the display.

This layer allows the use of custom input objects (TSLTerrainVSInput), allows access to the raw viewshed output, and allows all viewshed parameters to be set for the calculation.

To load data into this layer call the loadData method. This layer may load:

Multiple DTED files may be loaded into the layer using appendData.

By default this layer will perform all viewshed calculations asynchronously.

By default all viewshed calculations will use multiple threads to improve performance. This behaviour may be controlled using TSLTerrainVSAlgorithm::maxThreads.

Classes

struct  Observer
 
class  Visualisation
 This class specifies how the viewshed output should be visualised. More...
 
class  VisualisationVisibility
 

Public Member Functions

 TSLViewShedDataLayer ()
 
bool valid ()
 
bool appendData (const char *fileName)
 
unsigned int numObservers () const
 
unsigned int size () const
 
TSLViewShedDataLayer::ObserverobserverAt (unsigned int index)
 
TSLViewShedDataLayer::Observeroperator[] (unsigned int index)
 
void addObserver (const TSLViewShedDataLayer::Observer &observer)
 
bool updateObserver (unsigned int index, const TSLViewShedDataLayer::Observer &observer)
 
bool removeObserver (unsigned int index)
 
void removeAllObservers ()
 Remove all Observers from the layer.
 
void visualisation (const TSLViewShedDataLayer::Visualisation *vis)
 
bool setDisplayParameters (const TSLMUExtent &displayExtent, unsigned int displayWidth, unsigned int displayHeight)
 
bool getSynchronousLoading () const
 
void setSynchronousLoading (bool synchronous)
 
void setCallbacks (TSLViewShedDataLayerCallbacks *callbacks)
 
bool calculateViewShed ()
 
TSLTerrainVSAlgorithmRFVS::LOSResult calculateLineOfSight (double startX, double startY, double startZ, double endX, double endY, double endZ, double &blockedX, double &blockedY, double &blockedZ, bool ignoreNull=true)
 
TSLTerrainDatabaseterrainDatabase () const
 
void viewShedInputCacheLimit (unsigned int limit)
 
TSLTerrainVSInputviewShedInput () const
 
bool viewShedInput (TSLTerrainVSInput *input)
 
void enableRawOutput (bool enable)
 
TSLTerrainVSOutputArrayrawViewShedOutput ()
 
bool earthCurvatureCorrectionEnabled () const
 
void earthCurvatureCorrectionEnabled (bool enable)
 
TSLTerrainVSInputEarthCurvature::LOSType earthCurvatureCorrectionType () const
 
void earthCurvatureCorrectionType (TSLTerrainVSInputEarthCurvature::LOSType correctionType)
 
unsigned int maxOutputSize () const
 
void maxOutputSize (unsigned int maxSize)
 
const TSLRenderingAttributesborderRendering () const
 Get the rendering attributes for viewshed borders.
 
const TSLRenderingAttributesobserverLocationRendering () const
 Get the rendering attributes for observer locations.
 
void borderRendering (const TSLRenderingAttributes &renderingAttributes)
 
void observerLocationRendering (const TSLRenderingAttributes &renderingAttributes)
 
bool showBorders () const
 Returns true if the viewshed borders are drawn.
 
bool showObserverLocations () const
 Returns true if the viewshed observer locations are drawn.
 
void showBorders (bool show)
 
void showObserverLocations (bool show)
 
void * operator new (size_t size) TSL_NO_THROW
 Allocation override for API redirection.
 
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)
 
TSLDataHandlercreateDataHandler (const char *config_file=0)
 
TSLHistoryVersion currentVersion () const
 
TSLDataHandlerdataHandler ()
 
const TSLDataHandlerdataHandler () const
 
void destroy ()
 
bool entityIsVisible (const TSLEntity *entity, const TSLDrawingSurface *drawingSurface) const
 
const TSLFeatureClassListfeatureList () const
 
const TSLFeatureClassListfeatureList (const char *detailLayerName) const
 
bool fileModificationTime (const char *filename, TSLTimeType &lastModificationTime)
 
TSLEntityfindEntity (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
 
TSLEntityIteratorgetEntityIterator (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
 
TSLFileLoadergetLoader ()
 
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)
 
TSLMapQueryquery (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int depth=-1, const char *featureName=NULL, int drawingSurfaceID=-1) const
 
TSLMapQueryquery (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, TSLSelector *selector, int drawingSurfaceID=-1) const
 
const TSLCoordinateSystemgetCoordinateSystem () 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 TSLVersionHistorySetversionHistory () const
 

Constructor & Destructor Documentation

◆ TSLViewShedDataLayer()

TSLViewShedDataLayer::TSLViewShedDataLayer ( )

Constructor

Before viewshed calculations can be performed the application must call loadData with a terrain database/dted file or call viewShedInput to use a custom data source for viewshed calculations.

Member Function Documentation

◆ addObserver()

void TSLViewShedDataLayer::addObserver ( const TSLViewShedDataLayer::Observer & observer)

Add an Observer to the layer.

Parameters
observerThe Observer object to add.

◆ appendData()

bool TSLViewShedDataLayer::appendData ( const char * fileName)

Load data into the layer without removing any existing input data.

This method may be used to load multiple DMED/DTED files into the data layer when using a TSLDTEDTerrainDatabase as the input.

See also
TSLDTEDTerrainDatabase::append.

If a custom TSLTerrainVSInput object has been provided to the layer or if a MapLink Terrain Database (.tdf) file has been loaded this method will return false.

Parameters
fileNameThe DTED or DMED file to add.
Returns
true if the file was added, false otherwise.

◆ borderRendering() [1/2]

const TSLRenderingAttributes & TSLViewShedDataLayer::borderRendering ( ) const

Get the rendering attributes for viewshed borders.

◆ borderRendering() [2/2]

void TSLViewShedDataLayer::borderRendering ( const TSLRenderingAttributes & renderingAttributes)

Set the rendering attributes for viewshed borders.

The border is drawn as an ellipse, so it's rendering rules are the same as TSLEllipse rendering rules. showBorders(true) must be called for these rendering attributes to have any effect. Default rendering is applied if this method is not called.

Parameters
renderingAttributesThe rendering attributes for the viewshed borders.

◆ calculateLineOfSight()

TSLTerrainVSAlgorithmRFVS::LOSResult TSLViewShedDataLayer::calculateLineOfSight ( double startX,
double startY,
double startZ,
double endX,
double endY,
double endZ,
double & blockedX,
double & blockedY,
double & blockedZ,
bool ignoreNull = true )

Perform a line of sight calculation, between 2 points. If the end point is not visible from the start point then the 'blocked' point will be calculated. This is the point on the terrain which blocks the line of sight between the start and end points.

Parameters
startXThe X coordinate of the start point, in map units.
startYThe Y coordinate of the start point, in map units.
startZThe height of the start point. This height value is absolute, and not relative to the ground.
endXThe X coordinate of the end point, in map units.
endYThe Y coordinate of the end point, in map units.
endZThe height of the end point. This height value is absolute, and not relative to the ground.
blockedXPopulated with the X coordinate of the 'blocked' point.
blockedYPopulated with the Y coordinate of the 'blocked' point.
blockedZPopulated with the height of the 'blocked' point.
ignoreNullIf true, the algorithm will ignore nulls in the input data. If false, the calculation will terminate if a null is encountered.
Returns
The following may be returned:

◆ calculateViewShed()

bool TSLViewShedDataLayer::calculateViewShed ( )

Perform the viewshed calculation(s)

This method must be called in order for the layer to display any data:

  • The application must have added at least one Observer to the layer via addObserver
  • The application should have called setDisplayParameters in order to select an appropriate level of detail from the input data
  • If the layer has been set to perform asynchronous calculations (default), the viewshed will be performed in a background thread and this method will return (true) immediately. TSLViewShedDataLayerCallbacks::onViewShedComplete will be called to alert the application when this has happened
  • If the layer has been set to perform synchronous calculations, the viewshed will be calculated immediately in the current thread

The resulting viewshed will be displayed by the layer when the drawing surface is redrawn, and is affected by:

  • The number of Observers in the layer
  • The parameters of each Observer
  • The output specification of the layer. By default the viewshed will be visualised based on which points are visible/not visible from the Observer(s)
Returns
true if the viewshed operation was performed or sheduled, false if the viewshed parameters were invalid or the calculation could not be performed.

◆ earthCurvatureCorrectionEnabled() [1/2]

bool TSLViewShedDataLayer::earthCurvatureCorrectionEnabled ( ) const

Query whether earth curvature correction is enabled.

Returns
true if curvature corrections are enabled, false otherwise.

◆ earthCurvatureCorrectionEnabled() [2/2]

void TSLViewShedDataLayer::earthCurvatureCorrectionEnabled ( bool enable)

Set whether earth curvature correction is enabled.

Enabling earth curvature corrections can have a large impact on the performance of viewshed calculations.

The correction type may be set via earthCurvatureCorrectionType.

Parameters
enableIf true earth curvature corrections will be performed.

◆ earthCurvatureCorrectionType() [1/2]

TSLTerrainVSInputEarthCurvature::LOSType TSLViewShedDataLayer::earthCurvatureCorrectionType ( ) const

Query the type of earth curvature correction used by the layer.

Returns
The type of earth curvature correction used for viewshed calculations.

◆ earthCurvatureCorrectionType() [2/2]

void TSLViewShedDataLayer::earthCurvatureCorrectionType ( TSLTerrainVSInputEarthCurvature::LOSType correctionType)

Set the type of earth curvature correction to use.

The application must call earthCurvatureCorrectionEnabled to enable curvature corrections.

The default correction type is TSLTerrainVSInputEarthCurvature::LOSTypeVisual.

Parameters
correctionTypeThe type of correction to apply.

◆ enableRawOutput()

void TSLViewShedDataLayer::enableRawOutput ( bool enable)

Enable access to the raw viewshed output.

By default raw output is disabled to improve viewshed performance.

Parameters
enableIf true the application may query the raw output of future viewshed operations using rawViewShedOutput().

◆ getSynchronousLoading()

bool TSLViewShedDataLayer::getSynchronousLoading ( ) const

Query whether the layer will perform calculations synchronously.

Returns
true if calculations will be performed synchronously, false otherwise.

◆ maxOutputSize() [1/2]

unsigned int TSLViewShedDataLayer::maxOutputSize ( ) const

Query the maximum calculation width/height in pixels.

The default value is 16,384.

Returns
The maximum width or height for the viewshed calculation.

◆ maxOutputSize() [2/2]

void TSLViewShedDataLayer::maxOutputSize ( unsigned int maxSize)

Set the maximum calculation width/height in pixels.

The default value is 16,384.

Increasing this limit will have a large effect on viewshed performance and on the display performance of the data layer.

Parameters
maxSizeThe maximum width or height for the viewshed calculation.

◆ numObservers()

unsigned int TSLViewShedDataLayer::numObservers ( ) const

Get the number of Observers in the layer.

Returns
The number of observers added to the layer.

◆ observerAt()

TSLViewShedDataLayer::Observer & TSLViewShedDataLayer::observerAt ( unsigned int index)

Get an Observer from the layer.

Parameters
indexThe index of the Observer to query.
Returns
The Observer at index.

◆ observerLocationRendering() [1/2]

const TSLRenderingAttributes & TSLViewShedDataLayer::observerLocationRendering ( ) const

Get the rendering attributes for observer locations.

◆ observerLocationRendering() [2/2]

void TSLViewShedDataLayer::observerLocationRendering ( const TSLRenderingAttributes & renderingAttributes)

Set the rendering attributes for viewshed observer locations.

The location is drawn as a symbol, so it's rendering rules are the same as TSLSymbol rendering rules. showObserverLocations(true) must be called for these rendering attributes to have any effect. Default rendering is applied if this method is not called.

Parameters
renderingAttributesThe rendering attributes for the viewshed observer locations.

◆ operator new() [1/2]

void * TSLViewShedDataLayer::operator new ( size_t size)

Allocation override for API redirection.

◆ operator new() [2/2]

void * TSLViewShedDataLayer::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[]()

TSLViewShedDataLayer::Observer & TSLViewShedDataLayer::operator[] ( unsigned int index)

Get an Observer from the layer.

Parameters
indexThe index of the Observer to query.
Returns
The Observer at index.

◆ rawViewShedOutput()

TSLTerrainVSOutputArray * TSLViewShedDataLayer::rawViewShedOutput ( )

Access the raw output information from the last viewshed operation.

  • Before performing the viewshed the application must call TSLViewShedDataLayer::enableRawOutput( true ). Raw output is disabled by default to improve viewshed performance.
  • If an asynchronous operation is currently being performed this method will return NULL.
  • The application may retain this object after a second viewshed has been performed.

The returned object is reference counted. The application must call TSLTerrainVSOutput::dec() in order to delete it. As such this object may be retained by the application, even after performing another viewshed calculation.

◆ removeAllObservers()

void TSLViewShedDataLayer::removeAllObservers ( )

Remove all Observers from the layer.

◆ removeObserver()

bool TSLViewShedDataLayer::removeObserver ( unsigned int index)

Remove an Observer from the layer.

Parameters
indexThe index of the Observer to remove.
Returns
true if the Observer was removed, false otherwise.

◆ setCallbacks()

void TSLViewShedDataLayer::setCallbacks ( TSLViewShedDataLayerCallbacks * callbacks)

Set the callback object for viewshed calculations.

This callback will be called to inform the application of viewshed progress. This callback is optional. This callback must not be deleted before the datalayer, or before calling setCallbacks(NULL).

Parameters
callbacksThe callback object to use. NULL will clear the callback object.

◆ setDisplayParameters()

bool TSLViewShedDataLayer::setDisplayParameters ( const TSLMUExtent & displayExtent,
unsigned int displayWidth,
unsigned int displayHeight )

This information affects which resolution of data is selected from the terrain database. The input object (by default a terrain database) may use this information to select an appropriate level of detail to perform an efficient viewshed calculation at all zoom levels.

This method should be called before each viewshed calculation.

This method will return false if a viewshed calculation is currently being performed.

Parameters
displayExtentdrawing surface extent in Map Units.
displayWidthwidth of the display in pixels.
displayHeightheight of the display in pixels.
Returns
true if the display parameters were set, false otherwise.

◆ setSynchronousLoading()

void TSLViewShedDataLayer::setSynchronousLoading ( bool synchronous)

Set whether viewshed calculations should be performed synchronously.

By default all calculations will be performed in a background thread. The application will be notified via TSLViewShedDataLayerCallbacks::onViewShedComplete when a calculation has been performed.

If true is passed to this method calculateViewShed will block the calling thread until the calculation has completed. If false is passed to this method calcualteViewShed will return immediately. The application should call pass an implementation of TSLViewShedDataLayerCallbacks to setCallbacks in order to receive notifications from the datalayer.

Parameters
synchronoustrue if calculations should be synchronous, false otherwise.

◆ showBorders() [1/2]

bool TSLViewShedDataLayer::showBorders ( ) const

Returns true if the viewshed borders are drawn.

◆ showBorders() [2/2]

void TSLViewShedDataLayer::showBorders ( bool show)

Control whether the viewshed borders are drawn.

If show is true, an ellipse will be drawn encircling each observer's viewshed. The rendering of these ellipses is specified with the borderRendering() method.

Parameters
showThe viewshed borders will be shown if show is true.

◆ showObserverLocations() [1/2]

bool TSLViewShedDataLayer::showObserverLocations ( ) const

Returns true if the viewshed observer locations are drawn.

◆ showObserverLocations() [2/2]

void TSLViewShedDataLayer::showObserverLocations ( bool show)

Control whether the viewshed obsrever locations are drawn.

If show is true, points will be drawn at each observer's location. The rendering of these points is specified with the observerLocationRendering() method.

Parameters
showThe viewshed observer locations will be shown if show is true.

◆ size()

unsigned int TSLViewShedDataLayer::size ( ) const

Get the number of Observers in the layer.

Returns
The number of observers added to the layer.

◆ terrainDatabase()

TSLTerrainDatabase * TSLViewShedDataLayer::terrainDatabase ( ) const

Query the terrain database used by the layer.

If a custom input object has been provided to the layer this method will return NULL.

Returns
The terrain database loaded by the layer, or NULL if a database isn't loaded.

◆ updateObserver()

bool TSLViewShedDataLayer::updateObserver ( unsigned int index,
const TSLViewShedDataLayer::Observer & observer )

Update an Observer within the layer.

Applications may also modify an Observer using observerAt or operator[].

Parameters
indexThe index of the Observer to update.
observerThe Observer object to replace the existing Object at index.
Returns
true if the Observer was updated, false otherwise.

◆ valid()

bool TSLViewShedDataLayer::valid ( )

Query whether the layer is valid.

The layer is considered valid if data has been loaded, and at least one Observer has been added.

Returns
true if the layer is valid, false otherwise.

◆ viewShedInput() [1/2]

TSLTerrainVSInput * TSLViewShedDataLayer::viewShedInput ( ) const

Query the viewshed input object.

If a terrain database has been loaded by the layer this will return a TSLTerrainVSInputTerrainDatabase instance.

Returns
The viewshed input object used by the layer.

◆ viewShedInput() [2/2]

bool TSLViewShedDataLayer::viewShedInput ( TSLTerrainVSInput * input)

Set the viewshed input object.

This will replace any existing input object or loaded terrain database. This method will fail if a calculation is currently being performed.

See also
setSynchronousLoading. The application must call TSLTerrainVSInput::dec() on the provided object when it is no longer needed. The datalayer will take a reference to this object when this method is called.
Parameters
inputThe input object to use.
Returns
true if the input object was set, false otherwise.

◆ viewShedInputCacheLimit()

void TSLViewShedDataLayer::viewShedInputCacheLimit ( unsigned int limit)

Set the cache size limit for viewshed calculations.

This cache size will be set on TSLTerrainVSInputTerrainDatabase during calculations. If a custom input object has been provided to the layer this setting will be ignored.

The default value is 64MB.

Parameters
limitThe cache size limit in MB.

◆ visualisation()

void TSLViewShedDataLayer::visualisation ( const TSLViewShedDataLayer::Visualisation * vis)

Set the visualisation specification for viewshed calculations.

This object specifies:

  • How the output of the viewshed calculation should be visualised
  • Any parameters specific to this visualisation, such as colour settings

The default visualisation is TSLViewShedDataLayer::VisualisationVisibility which will display whether or not each point in the calculation is visible from one or more Observers.

Parameters
visThe Visualisation to use for viewshed calculations.