module Projected Points

These functions all operate on the optional m_ProjectedPointData RadDataBlock in the InputWorkspace class.

It allows you to store multiple versions of the duster pointers, generated offline. The data is stored per-instance, per-version as a set of patches you can extract and apply to the original positions.

General points:

• All calls other than DoesInputWorkspaceHaveProjectionData() will fail and report and error if the projection data is not valid.

• The instance GUID is the same as the GUID on PrecompInputInstances given to the precompute for this system.

• Unrecognised instance GUIDs are not considered failures, but return negative counts to signify they were not recognised.

• Unrecognised version IDs are not considered failures, but return zero counts (i.e. an empty patch). It is possible for an instance to have no points associated with it (e.g. too small or hidden) so zero points does not imply an unrecognised version ID.

• You can extract the points and the versions IDs with the API. In each case you need to allocate the output memory in advance, and can allocate a single buffer for all calls by using the GetInputWorkspaceMax*() functions.

Functions

bool GEO_CALL Enlighten::DoesInputWorkspaceHaveProjectionData

---

public: bool GEO_CALL DoesInputWorkspaceHaveProjectionData
(
    const InputWorkspace * inputWorkspace
)

---

Simple test to see if projection data is available.

Returns true if the inputWorkspace has data in its point projection RadDataBlock, otherwise false. This does quick and simple checks only and assumes that if the data exists it is well formed. Note that it can still have a valid RadDataBlock, but that block can be empty. You can test whether GetInputWorkspaceMaxProjectedPointsInAnyInstance() == 0 to check if the block is empty.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceInstanceGuids

---

public: bool GEO_CALL GetInputWorkspaceInstanceGuids
(
    const InputWorkspace * inputWorkspace,
    Geo::GeoGuid * instanceIdsOut
)

---

Get all the instance GUIDs in this system.

This reports all the instance GUIDs this system saw and recorded during the precompute. You must pass an array that is at least as large as the number reported by GetInputWorkspaceInstanceGuids(). Note that it can succeed not have written anything out if there is a valid projection block, but it's empty. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceMaxProjectedPointsInAnyInstance

---

public: bool GEO_CALL GetInputWorkspaceMaxProjectedPointsInAnyInstance
(
    const InputWorkspace * inputWorkspace,
    Geo::s32 * maxPointsOut
)

---

Get the maximum number of projected points associated with any instance.

This is effectively the largest number that can be returned by GetInputWorkspaceNumProjectedPointsInInstance() Useful if you want to allocate one buffer up front that will always be large enough to accept results. Note that it can succeed and return 0 if there is a valid projection block, but it's empty. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceMaxVersionsInAnyInstance

---

public: bool GEO_CALL GetInputWorkspaceMaxVersionsInAnyInstance
(
    const InputWorkspace * inputWorkspace,
    Geo::s32 * maxVersionsOut
)

---

Get the maximum number of versions of projected points associated with any instance.

This is effectively the largest number that can be returned by GetInputWorkspaceNumVersionsInInstance() Useful if you want to allocate one buffer up front that will always be large enough to accept results. Note that it can succeed and return 0 if there is a valid projection block, but it's empty. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceNumInstanceGuids

---

public: bool GEO_CALL GetInputWorkspaceNumInstanceGuids
(
    const InputWorkspace * inputWorkspace,
    Geo::s32 * numInstanceGuidsOut
)

---

Get the number of instance GUIDs in this system.

This is a record of all the instance GUIDs this system saw and recorded during the precompute. It's also the length of the array required by GetInputWorkspaceInstanceGuids() Note that it can succeed and set numInstanceGuidsOut to 0 if there is a valid projection block, but it's empty. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceNumProjectedPointsInInstance

---

public: bool GEO_CALL GetInputWorkspaceNumProjectedPointsInInstance
(
    const InputWorkspace * inputWorkspace,
    Geo::GeoGuid instanceGuid,
    Geo::s32 * numPointsOut
)

---

Get the number of points associated with the specified instance.

If the instanceGuid is recognised (i.e. it was seen by the precompute), and versions exist for it, then numPointsOut will be set to the number of points associated with this instance. Note numPointsOut can be zero if there were no associated points. If the instanceGuid is recognised, but no versions exist for it, then numPointsOut will be set to 0. If the instanceGuid is not recognised or invalid, then numPointsOut will be set to -1, but the function still returns true. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceNumVersionsInInstance

---

public: bool GEO_CALL GetInputWorkspaceNumVersionsInInstance
(
    const InputWorkspace * inputWorkspace,
    Geo::GeoGuid instanceGuid,
    Geo::s32 * numVersionsOut
)

---

Get the number of versions associated with the specified instance.

If the instanceGuid is recognised (i.e. it was seen by the precompute), then numVersionsOut will be the number of versions associated with this instance. Note that it is valid for an instance to have no versions associated with it, in which case numVersionsOut will be 0. If the instanceGuid is not recognised or invalid, then numVersionsOut will be set to -1, but the function still returns true. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceProjectedPointVersion

---

public: bool GEO_CALL GetInputWorkspaceProjectedPointVersion
(
    const InputWorkspace * inputWorkspace,
    Geo::GeoGuid instanceGuid,
    Geo::s32 versionId,
    Geo::s32 * pointIdxArrayOut,
    Geo::v128 * pointPosArrayOut,
    Geo::s32 * numProjectedPointsOut
)

---

Get the projected points for a specified version and instance.

pointIdxArrayOut and pointPosArrayOut should each point to arrays and will be filled with corresponding pairs of indices and positions associated with the specified instance and version. The values of pointIdxArrayOut are the indices into the duster point position array. The values of pointPosArrayOut are the corresponding projected positions of the point at that index.

numProjectedPointsOut should point to a single s32 and will be set to the same value as returned through GetInputWorkspaceNumProjectedPointsInInstance() if both the instanceId and versionId are recognised.

If both the instanceGuid and versionId are recognised, then numProjectedPointsOut will be the number of items written to each array. If the instanceGuid is not recognised or is invalid, numProjectedPointsOut will be -1, and no values will be written to the arrays. If the instanceGuid is recognised by versionId is not, numProjectedPointsOut will be 0, and no values will be written to the arrays.

The arrays should be at least as large as the maximum value that may be written, which can be found by calling GetInputWorkspaceNumProjectedPointsInInstance() in advance, or by using the system-wide num points maximum returned by GetInputWorkspaceMaxProjectedPointsInAnyInstance(). The system wide maximum may be helpful if you wish to allocate a single block of memory and re-use it for other instances. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters

bool GEO_CALL Enlighten::GetInputWorkspaceVersionsInInstance

---

public: bool GEO_CALL GetInputWorkspaceVersionsInInstance
(
    const InputWorkspace * inputWorkspace,
    Geo::GeoGuid instanceId,
    Geo::s32 * versionIdsOut,
    Geo::s32 * numVersionsOut
)

---

Get the list of version ids stored for a specified instance.

numVersionsOut should point to a single s32 and will be set to the same value as returned through GetInputWorkspaceNumVersionsInInstance(). versionIdsOut should point to an array of s32s and will be filled with the version ids associated with instanceGuid.

If the instanceGuid is recognised, then numVersionsOut will be the number of items written to versionIdsOut. If the instanceGuid is not recognised or is invalid, numVersionsOut will be -1, and no values will be written to versionIdsOut. The versionIdsOut array should be at least as large as the maximum value that may be written, which can be found by calling GetInputWorkspaceNumVersionsInInstance() in advance, or by using the system-wide num versions maximum returned by GetInputWorkspaceMaxVersionsInAnyInstance(). The system wide maximum may be helpful if you wish to allocate a single block of memory and re-use it for other instances. If there is no valid data (the block or input workspace is missing or corrupt) this call will return false, otherwise true.

Parameters