Summary
When a volume dataset is loaded using the XStream® HDVR® SDK, it is mapped to the XStream HDVR coordinate system. This is a right-handed coordinate system with the +Z axis pointing forward, the +X axis pointing to the right, and the +Y axis pointing down. The origin is at the physical center of the volume. For medical scans, the +Z axis points from the center of the body towards the head, the +X axis points towards the subject's left side, and the +Y axis points from the center of the body towards the back. The position and orientation of the view can be set with a transformation matrix.
XStream HDVR coordinate system
It is important to understand that the volume is fixed in space, and only the view position can be manipulated. However, the position and orientation of polygon objects can be manipulated independently of the volume or viewpoint. See Positioning the Mesh for more information on manipulating polygon objects. The position and orientation of the viewpoint can be set using the RENDER_PARAMS::Transform member. This member variable is a 4x4 transformation matrix stored in a MATRIX44D class. This matrix is depicted below.
The viewpoint position is defined by setting the offset vector component of the matrix. Three matrix components (m14, m24, m34) represent the X, Y, and Z coordinates for the view position within the XStream HDVR coordinate system. These matrix components can be set directly with the MATRIX44D::setOffsetVector() method. This method takes three parameters, which are the X, Y, and Z coordinates of the view position. A translation matrix can be created with the MATRIX44D::createTranslateMatrix() method.
The orientation of the view is defined by setting the X vector (m11, m21, m31), Y vector (m12, m22, m32) and Z vector (m13, m23, m33) components of the matrix. When the matrix is first initialized to the identity matrix the X vector, Y vector, and Z vector components of the matrix point along their respective Cartesian axes. For example, X vector equals (1, 0, 0), Y vector equals (0, 1, 0), and Z vector equals (0, 0, 1). To set a different view orientation, these vectors can be set to different values that represent a new orientation for the view. As with any transformation matrix, the X vector, Y vector, and Z vector components must be normalized and orthogonal. They must also define a right-handed coordinate system. Use of the mouse to manipulate the view position and orientation can be enabled with the Visualization Mouse Adaptors. The source code for these adaptors is provided with the XStream HDVR distribution, and can be used as a reference for matrix manipulation.
A rotation matrix can be set directly by setting values for the X, Y, and Z rotation vectors with the MATRIX44D::setXVector(), MATRIX44D::setYVector(), and MATRIX44D::setZVector() methods. A rotation matrix can also be created using the MATRIX44D::createRotateMatrix() method. This method takes as input parameters a value that specifies the angle of rotation in radians, and X, Y, and Z values that define the axis of rotation.
MATRIX44D matrix;
// Sets a matrix with X, Y, Z position 5, 10, 20.
matrix.setOffsetVector(5, 10, 20);
// Sets a matrix with a 90 degree rotation about the Y axis.
matrix.createRotateMatrix(PI/2, 0, 1, 0);
It is important to understand that the volume is fixed in space, and only the view position can be manipulated. However, the position and orientation of polygon objects can be manipulated independently of the volume or viewpoint. See Positioning the Mesh for more information on manipulating polygon objects. The position and orientation of the viewpoint can be set using the RENDER_PARAMS::Transform member. This member variable is a 4x4 transformation matrix stored in a MATRIX44D class. This matrix is depicted below.
The viewpoint position is defined by setting the offset vector component of the matrix. Three matrix components (m14, m24, m34) represent the X, Y, and Z coordinates for the view position within the XStream HDVR coordinate system. These matrix components can be set directly with the MATRIX44D::setOffsetVector() method. This method takes three parameters, which are the X, Y, and Z coordinates of the view position. A translation matrix can be created with the MATRIX44D::createTranslateMatrix() method.
The orientation of the view is defined by setting the X vector (m11, m21, m31), Y vector (m12, m22, m32) and Z vector (m13, m23, m33) components of the matrix. When the matrix is first initialized to the identity matrix the X vector, Y vector, and Z vector components of the matrix point along their respective Cartesian axes. For example, X vector equals (1, 0, 0), Y vector equals (0, 1, 0), and Z vector equals (0, 0, 1). To set a different view orientation, these vectors can be set to different values that represent a new orientation for the view. As with any transformation matrix, the X vector, Y vector, and Z vector components must be normalized and orthogonal. They must also define a right-handed coordinate system. Use of the mouse to manipulate the view position and orientation can be enabled with the Visualization Mouse Adaptors. The source code for these adaptors is provided with the XStream HDVR distribution, and can be used as a reference for matrix manipulation.
A rotation matrix can be set directly by setting values for the X, Y, and Z rotation vectors with the MATRIX44D::setXVector(), MATRIX44D::setYVector(), and MATRIX44D::setZVector() methods. A rotation matrix can also be created using the MATRIX44D::createRotateMatrix() method. This method takes as input parameters a value that specifies the angle of rotation in radians, and X, Y, and Z values that define the axis of rotation.
MATRIX44D matrix = new MATRIX44D();
// Sets a matrix with X, Y, Z position 5, 10, 20.
matrix.setOffsetVector(5, 10, 20);
// Sets a matrix with a 90 degree rotation about the Y axis.
matrix.createRotateMatrix(PI/2, 0, 1, 0);
To select a basis view direction along coordinate axes, the appropriate matrix values for the six basis view axes and their anatomical terms of location are shown in the Basis Matrices tables below.
Identifying the View Basis Vector
Within some applications, it may useful to determine which of the six basis view vectors is closest to the current view direction. Utility methods are provided in the C3DHelpers class to identify the primary and secondary basis vectors proximal to the current view direction. These utility methods are shown in the table below.
This method takes the current view direction as an input vector. It returns an output vector with values from 0 to 1 that represent the percentage contribution of the X, Y, and Z components to the vector. |
|
This method takes the output vector from the C3DHelpers::GetContributions() method as an input value. It returns an enumerated value identifying which of the six basis vectors is the most significant axis. Return values are X_POS, X_NEG, Y_POS, Y_NEG, Z_POS, and Z_NEG. |
|
This method takes as input parameters the output from the C3DHelpers::GetContributions() and C3DHelpers::GetPrimaryBias() methods. It returns the second most significant axis. |
|
This takes as input parameters the output from the C3DHelpers::GetContributions() and C3DHelpers::GetPrimaryBias() methods, as well as a threshold value. It determines if a secondary bias should be displayed, based upon the supplied threshold. A higher threshold will make the secondary bias more likely. |
|
C3DHelpers::GetBiasNameMedical() |
This method takes as input the primary bias returned by the C3DHelpers::GetPrimaryBias() method. It returns a string representing the equivalent anatomical term of location. |
C3DHelpers helpers;
// Get contributions vector.
VECTOR3D contrib, vec;
vec = VECTOR3D(0.81, 0.32, 0.49);
helpers.GetContributions(&contrib, &vec);
// Get primary bias vector.
h_int32 primaryBias;
helpers.GetPrimaryBias(&primaryBias, &contrib);
// Get secondary bias vector.
h_int32 secondaryBias;
helpers.GetSecondaryBias(&secondaryBias, primaryBias, &contrib);
// Determine if a secondary bias is relevant.
h_boolean bHasSecondary;
helpers.GetHasSecondaryBias(&bHasSecondary, 0.5, primaryBias, &contrib);
// Get the anatomical term for the current primary and secondary view bias.
char medicalName[32];
helpers.GetBiasNameMedical(medicalName, &vec);
Within some applications, it may useful to determine which of the six basis view vectors is closest to the current view direction. Utility methods are provided in the hdrc3DHelpers class to identify the primary and secondary basis vectors proximal to the current view direction. These utility methods are shown in the table below.
This method takes the current view direction as an input vector. It returns an output vector with values from 0 to 1 that represent the percentage contribution of the X, Y, and Z components to the vector. |
|
This method takes the output vector from the hdrc3DHelpers.getContributions() method as an input value. It returns an enumerated value identifying which of the six basis vectors is the most significant axis. Return values are X_POS, X_NEG, Y_POS, Y_NEG, Z_POS, and Z_NEG. |
|
This method takes as input parameters the output from the hdrc3DHelpers::getContributions() and hdrc3DHelpers::getPrimaryBias() methods. It returns the second most significant axis. |
|
This takes as input parameters the output from the hdrc3DHelpers::getContributions() and hdrc3DHelpers::getPrimaryBias() methods, as well as a threshold value. It determines if a secondary bias should be displayed, based upon the supplied threshold. A higher threshold will make the secondary bias more likely. |
|
This method takes as input the primary bias returned by the hdrc3DHelpers::getPrimaryBias() method. It returns a string representing the equivalent anatomical term of location. |
// Get contributions vector.
VECTOR3D vec = new VECTOR3D(0.81, 0.32, 0.49);
VECTOR3D contrib = hdrc3DHelpers.getContributions(vec);
// Get primary bias vector.
int primaryBias = hdrc3DHelpers.getPrimaryBias(contrib);
// Get secondary bias vector.
int secondaryBias = hdrc3DHelpers.getSecondaryBias(primaryBias, contrib);
// Determine if a secondary bias is relevant.
boolean bHasSecondary = hdrc3DHelpers.getHasSecondaryBias(0.5, primaryBias, contrib);
// Get the anatomical term for the current primary and secondary view bias.
String medicalName = hdrc3DHelpers.getBiasNameMedical(vec);
These matrices will place the camera at the origin with the view direction as indicated.
Anterior
1 |
0 |
0 |
0 |
0 |
0 |
1 |
0 |
0 |
-1 |
0 |
0 |
0 |
0 |
0 |
1 |
Posterior
-1 |
0 |
0 |
0 |
0 |
0 |
-1 |
0 |
0 |
-1 |
0 |
0 |
0 |
0 |
0 |
1 |
Superior
-1 |
0 |
0 |
0 |
0 |
1 |
0 |
0 |
0 |
0 |
-1 |
0 |
0 |
0 |
0 |
1 |
Inferior
1 |
0 |
0 |
0 |
0 |
1 |
0 |
0 |
0 |
0 |
1 |
0 |
0 |
0 |
0 |
1 |
Right Lateral
0 |
0 |
1 |
0 |
-1 |
0 |
0 |
0 |
0 |
-1 |
0 |
0 |
0 |
0 |
0 |
1 |
Left Lateral
0 |
0 |
-1 |
0 |
1 |
0 |
0 |
0 |
0 |
-1 |
0 |
0 |
0 |
0 |
0 |
1 |
