Describes the coordinate systems used in instant3Dhub products and the transformations between them.
Webvis (our JavaScript API powering all browser apps) uses OpenGL (right-handed coordinate system) for rendering.
The model orientation can be configured in the viewer settings and is applied via an additional rotation matrix that gets multiplied into the view matrix. The default orientation is as follows (i.e. -Y-right and +Z-up):
The Unreal plugin transforms all coordinates to match the Unreal Engine conventions. This involves switching from a right-handed to a left-handed coordinate system and scaling the units by a factor of 100.
- Webvis coordinates are in meters
- Unreal coordinates are in centimeters
Furthermore, there is an additional level of indirection, as the transformation of the HubConnector is applied to all geometry. The HubConnector transformation can be used to configure the model orientation.
- Note
- The model orientation matrix from Webvis is not taken into account in this coordinate transformation. This means that by default the model will have a different orientation in Unreal compared to Webvis. The
HubConnector transform can be used to set the desired model orientation in Unreal. For example, if the model is oriented I3DH-Z-up, the HubConnector must be rotated Unreal-X-down to compensate.
All public functions of the plugin that return coordinates or transforms use the Unreal Engine conventions. The following utility functions can be used to convert coordinates back into the original coordinate system.
- Attention
- The
HubConnector transform only exists in Unreal, therefore, if the coordinates are in world space, they should be first made relative to the HubConnector before conversion (see AI3DHConnector::GetWorldToOriginTransform).
- Note
- We use FMatrix instead of FTransform for transformations to save us some trouble. An FTransform is always a scaling, rotation and translation in that order. When a transform can't be properly represented in that form, the behaviour is unintuitive. This happens for example when inverting transforms with non-uniform scaling. See also: https://1danielcoelho.github.io/unreal-non-uniform-scaling-gotcha/
Examples
Converting Points:
FVector3 UEVertex = [... ];
FVector3 OGVertex = UEToOG.TransformPosition(UEVertex);
static const FMatrix & GetUnrealToOriginalMatrix()
Returns the conversion matrix between the Unreal and Original coordinate systems.
Converting Transforms:
FMatrix UEObjToWorld = [ ... a world transform from the engine ... ];
FMatrix UEObjToOrigin = UEObjToWorld * HubConnector->GetWorldToOriginTransform();
static FMatrix ConvertTransformUnrealToOriginal(const FMatrix &UnrealTransform)
Converts a transformation matrix to the Original coordinate system.
Querying the transform from the HubConnector:
int NodeId = 123;
[ ... ]
});
@ GlobalTransform
Transform relative to Hub Connector.
EI3DHErrorCode
Enumeration of Error Codes returned from various instant3Dhub API Calls.
Definition I3DHError.h:15
◆ ConvertTransformOriginalToUnreal()
| static FMatrix UI3DHUtilities::ConvertTransformOriginalToUnreal |
( |
const FMatrix & | OriginalTransform | ) |
|
|
static |
Converts a transformation matrix to the Unreal coordinate system.
- Parameters
-
| OriginalTransform | The Original transform. |
- Returns
- The corresponding transform in the Unreal coordinate system.
◆ ConvertTransformOriginalToUnrealPure()
| static FMatrix UI3DHUtilities::ConvertTransformOriginalToUnrealPure |
( |
const FMatrix & | OriginalTransform | ) |
|
|
static |
Converts a transformation matrix to the Unreal coordinate system.
- Note
- This function is identical to ConvertTransformOriginalToUnreal except that it is a pure function in Blueprint. There is no need to use this function in C++.
- Parameters
-
| OriginalTransform | The Original transform. |
- Returns
- The corresponding transform in the Unreal coordinate system.
◆ ConvertTransformUnrealToOriginal()
| static FMatrix UI3DHUtilities::ConvertTransformUnrealToOriginal |
( |
const FMatrix & | UnrealTransform | ) |
|
|
static |
Converts a transformation matrix to the Original coordinate system.
- Parameters
-
| UnrealTransform | The Unreal transform. |
- Returns
- The corresponding transform in the Original coordinate system.
◆ ConvertTransformUnrealToOriginalPure()
| static FMatrix UI3DHUtilities::ConvertTransformUnrealToOriginalPure |
( |
const FMatrix & | UnrealTransform | ) |
|
|
static |
Converts a transformation matrix to the Original coordinate system.
- Note
- This function is identical to ConvertTransformUnrealToOriginal except that it is a pure function in Blueprint. There is no need to use this function in C++.
- Parameters
-
| UnrealTransform | The Unreal transform. |
- Returns
- The corresponding transform in the Original coordinate system.
◆ ConvertVolumeOriginalToUnreal()
| static FBox UI3DHUtilities::ConvertVolumeOriginalToUnreal |
( |
const FBox & | OriginalVolume | ) |
|
|
static |
Converts a volume to the Unreal coordinate system.
- Parameters
-
| OriginalVolume | The Original volume. |
- Returns
- The corresponding volume in the Unreal coordinate system.
◆ ConvertVolumeOriginalToUnrealPure()
| static FBox UI3DHUtilities::ConvertVolumeOriginalToUnrealPure |
( |
const FBox & | OriginalVolume | ) |
|
|
static |
Converts a volume to the Unreal coordinate system.
- Note
- This function is identical to ConvertVolumeOriginalToUnreal except that it is a pure function in Blueprint. There is no need to use this function in C++.
- Parameters
-
| OriginalVolume | The Original volume. |
- Returns
- The corresponding volume in the Unreal coordinate system.
◆ ConvertVolumeUnrealToOriginal()
| static FBox UI3DHUtilities::ConvertVolumeUnrealToOriginal |
( |
const FBox & | UnrealVolume | ) |
|
|
static |
Converts a volume to the Original coordinate system.
- Parameters
-
| UnrealVolume | The Unreal volume. |
- Returns
- The corresponding volume in the Original coordinate system.
◆ ConvertVolumeUnrealToOriginalPure()
| static FBox UI3DHUtilities::ConvertVolumeUnrealToOriginalPure |
( |
const FBox & | UnrealVolume | ) |
|
|
static |
Converts a volume to the Original coordinate system.
- Note
- This function is identical to ConvertVolumeUnrealToOriginal except that it is a pure function in Blueprint. There is no need to use this function in C++.
- Parameters
-
| UnrealVolume | The Unreal volume. |
- Returns
- The corresponding volume in the Original coordinate system.
◆ GetOriginalToUnrealMatrix()
| static const FMatrix & UI3DHUtilities::GetOriginalToUnrealMatrix |
( |
| ) |
|
|
static |
Returns the conversion matrix between the Original and Unreal coordinate systems.
- Returns
- The conversion matrix.
◆ GetOriginalToUnrealNormalMatrix()
| static const FMatrix & UI3DHUtilities::GetOriginalToUnrealNormalMatrix |
( |
| ) |
|
|
static |
Gets original to unreal normal matrix.
The matrix for transforming directions (use TransformVector, not TransformPosition).
- Note
- For uniform scaling the ordinary transformation matrix is sufficient.
-
If transforming normals, don't forget to normalize afterwards.
- Returns
- The original to unreal normal matrix.
◆ GetOriginalToUnrealScale()
| static float UI3DHUtilities::GetOriginalToUnrealScale |
( |
| ) |
|
|
static |
Returns the scale factor between Original and Unreal coordinates.
This is useful for converting a linear dimension (e.g. the distance between two points). For converting coordinates use one of the conversion matrices, which has the scale factor already baked in.
- Returns
- The scale factor.
◆ GetUnrealToOriginalMatrix()
| static const FMatrix & UI3DHUtilities::GetUnrealToOriginalMatrix |
( |
| ) |
|
|
static |
Returns the conversion matrix between the Unreal and Original coordinate systems.
- Returns
- The conversion matrix.
◆ GetUnrealToOriginalNormalMatrix()
| static const FMatrix & UI3DHUtilities::GetUnrealToOriginalNormalMatrix |
( |
| ) |
|
|
static |
Gets unreal to original normal matrix.
The matrix for transforming directions (use TransformVector, not TransformPosition).
- Note
- For uniform scaling the ordinary transformation matrix is sufficient.
-
If transforming normals, don't forget to normalize afterwards.
- Returns
- The unreal to original normal matrix.
1.12.0