GeoTrans_ToGlobalEnvelope Function

Applies To: Implementing a custom GeoTransformer

Transforms the envelope of a sensor definition, in the process chain that computes global ground (real world) coordinates, in reference to a chosen coordinate system.

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

[C / C++]

BOOL __stdcall GeoTrans_ToGlobalEnvelope(

HGeoTrans hInstance, // handle of GeoTransformer instance

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

const VERTEX3D outData[4// array of 4 input 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,out] outData

An array of 4 output 3D points that returns the transformed coordinates. Most GeoTransformers would simply forward the envelope transformation to GeoTrans_ToGlobalDirection, 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.

[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.

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

When the transformation that you're implementing is invertible only under certain circumstances, then its reverse transformation may be quite an expensive process. Even when not supported, you must find other ways for returning the envelope, without transforming the given input coordinates. This is required when an aproximate footprint of a raster is computed.

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 <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 forward the envelope transformation to GeoTrans_ToGlobalDirection:

[C++]

extern "C" BOOL __stdcall GeoTrans_ToGlobalEnvelope(

   HGeoTrans hInstance,

   VERTEX3D outData[4],

   const VERTEX3D inData[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_ToGlobalDirection(oPak,iPak);

   }

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_ToGlobalDirection, GeoTrans_FromGlobalEnvelope, Error_FormatMessage, GeoTransCreation, GTM_Errors_Warnings, GeoTransDataTypes, GeoTransData