GeoTrans_FromGlobalEnvelope Function

Applies To: Implementing a custom GeoTransformer

Transforms the envelope of a sensor definition, in the process chain starting from global ground (real world) coordinates, converting them into a virtual object’s coordinate system.

GeoTransCore component will forward this call to your implementation when the envelope of a raster must be obtained in image space.

[C / C++]

BOOL __stdcall GeoTrans_FromGlobalEnvelope(

HGeoTrans hInstance, // handle of GeoTransformer instance

const VERTEX3D inData[4// array of 4 input 3D points

VERTEX3D outData[4], // array of 4 output 3D points

);

Arguments

[in] hInstance

Custom GeoTransformer instance handle. This handle specifies which instance should be used when transforming an envelope. The given handle value may point to any type of GeoTransformer supported by your implementation. Refer to the documentation of Instance_Create function for details about a handle to a GeoTransformer instance.

HGeoTrans type is defined as a HANDLE in GeoTransCreation namespace.

Note: It is not required to test against NULL the value of the handle, since GeoTransCore component ensures its validity.

[in] inData

A read-only array of 4 input 3D points to be transformed. The custom GeoTransformer may decide to ignore any of the coordinates of this input points.

[in,out] outData

An array of 4 output 3D points that returns the transformed coordinates. Most GeoTransformers would simply forward the envelope transformation to GeoTrans_FromGlobalDirection, but some might enforce certain values to be returned. For example, a GeoTransformer may have defined an AverageZ property, thus setting the elevation of the envelope to that value.

Note: 2D GeoTransformers should copy Z from input to output, even they do not use it in the transformation.

Return Value

Return FALSE when outData array does not contain a valid transformed envelope. Setting an error code with SetLastError function will identify the reason(s) for failure. When the transformation was successful, but some warning(s) should be signaled, set an appropriate code but return TRUE.

Reporting errors and warnings: To learn how to provide descriptions for your custom error and warning codes, please see Error_FormatMessage function documentation. GTM_Errors_Warnings namespace enumerates some recommended codes and descriptions to be supported, from which the following would be set by this function:

Constant

Description

err_data_general

Cannot transform in this direction.

Remarks

There are quite a few considerations when implementing this function, but probably the most important of all is that both input and output arrays may point to the same memory address. Thus, it is essential that your implementation makes a copy of an input coordinate before writing the corresponding output coordinate in case that original value still needs to be used in the computation. Following sample code shows the undesired behavior of replacing the input data when shares the same memory with the output data:

[C / C++]

#include <windows.h>

#include <math.h>

#define M_PI 3.14159265358979323846

 

void Rotate2dPoints(double angleDegrees,const double * inPoints,double * outPoints,size_t noPoints) 

   {

double angleRadians = angleDegrees * M_PI / 180;

register int idx = noPoints;

while (idx) { --idx;

outPoints[2*idx] = cos(angleRadians) * inPoints[2*idx] - sin(angleRadians) * inPoints[2*idx+1];

/* at this point, value of inPoints[2*idx] is also changed */

outPoints[2*idx+1] = sin(angleRadians) * inPoints[2*idx] + cos(angleRadians) * inPoints[2*idx+1];

}

}

int main(int ,char ** ,char ** ) {

double points[4] = {0};

points[0] = points[3] = 1.0;

Rotate2dPoints(60.0,points,points,2);

return 0;

}

Multi-threading: Concurrent calls from different threads will expect this implementation to be thread safe.

Requirements

Platform

32 bit Windows OS

Environment

ANSI C / C++ Standard compliant

API

__stdcall calling convention; by name, undecorated "C" export

Unicode support

SBCS (ASCII) only

Dependency

kernel32.dll

Reference

kernel32.lib

Include

windows.h

Example

This sample shows how to simply forward the envelope transformation to GeoTrans_FromGlobalDirection:

[C++]

extern "C" BOOL __stdcall GeoTrans_FromGlobalEnvelope(

   HGeoTrans hInstance,

   const VERTEX3D inData[4]

   VERTEX3D outData[4],

   )}

      GeoTransData::GTD iData;

      GeoTransData iPak;

      iPak.dwType=geoData_Ground_MPoints3D;

      iPak.as = &iData;

      iData.MPoints3D.pntNo = 4;

      iData.MPoints3D.XYZs = (VERTEX3D*)inData;

      GeoTransData::GTD oData;

      GeoTransData oPak;

      oPak.dwType = geoData_Ground_MPoints3D;

      oPak.as = &oData;

      oData.MPoints3D.pntNo =4;

      oData.MPoints3D.XYZs =outData;

   return GeoTrans_FromGlobalDirection(iPak,oPak);

   }

For a detailed example on how to implement this function, please see Custom GeoTransformer VC++ Sample.

Related Topics

See also: Instance_Create, Instance_Discard, GeoTrans_FromGlobalDirection, GeoTrans_ToGlobalEnvelope, Error_FormatMessage, GeoTransCreation, GTM_Errors_Warnings, GeoTransDataTypes, GeoTransData