Package gov.nih.mipav.model.algorithms.registration

Class BSplineRegistration3Df

  • public class BSplineRegistration3Df
extends BSplineRegistrationBasef
    This class is used to register a 3D source image to a 3D target image. The images do not have to have the same dimensions, but they must both contain single-channel data. The resulting registered source image has the same dimensions as the input target image. A 3D B-Spline is used to map the coordinates of the registered image to coordinates of the input source image. A separate B-Spline basis is setup for each axis given the number of control points and the degree of the basis functions to use. Each B-Spline is uniform open with control points spaced equally for each dimension. Trilinear interpolation is used to determine which input source image value(s) to assign to the resulting registered source image. The "error" measure between the input target image and the current registered source image is the sum of squared differences, where the root mean squared error is also computed. Control points are moved one at a time by means of gradient descent minimization in order to minimize the error. The gradient is approximated at each control point by means of finite differences. Control points are restricted from moving outside the polyhedron formed by its 26 neighboring control points.

    • Constructor Summary

      Constructors 
      Constructor Description
      BSplineRegistration3Df​(ModelSimpleImage kImageSrc, ModelSimpleImage kImageTrg, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisX, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisY, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisZ, RegistrationMeasure kRegMeasure)
      Create instance to be used for registration.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ModelSimpleImage createImageDeformation()
      Generate an image which contains the deformation value at each sample in the target image as it relates to how the source image is transformed as a result of the registration.
      ModelSimpleImage createImageDisplacement()
      Generate an image which contains the magnitude of the displacement vector at each sample in the target image as it relates to how the source image is transformed as a result of the registration.
      ModelSimpleImage[] createImageSourceMap()
      Generate an image the size of the target image in which each sample contains the 3D interpolated point coordinates in the source image which "maps" or is registered with the corresponding point in the target image.
      BSplineRegistration3Df createSameMapping​(ModelSimpleImage kImageTrg)
      Create a new registration with the same mapping as this one and which uses the same source image and the same BSpline basis degree and number of control points.
      BSplineRegistration3Df createSameMapping​(ModelSimpleImage kImageTrg, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisX, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisY, WildMagic.LibFoundation.Curves.BSplineBasisf kBasisZ)
      Create a new registration with the same mapping as this one and which uses the same source image and a possibly resampled target image, however, this time the BSpline basis degree and/or the number of control points may be different.
      void finalize()
      Cleanup memory.
      protected float getControlPointMaxMoveDist​(int iControlX, int iControlY, int iControlZ, WildMagic.LibFoundation.Mathematics.Vector3f kRayDirection, float fMaxDesiredDist)
      Compute the maximum distance the control point can be moved in the specified direction while keeping the control point relative to its 26 neighboring control points such that "folding" does not occur.
      protected void getErrorDeriv​(int iControlX, int iControlY, int iControlZ, WildMagic.LibFoundation.Mathematics.Vector3f kDeriv)
      Computes the derivative of the error function at a control point by approximating with finite differences where the control point is moved small amounts in each orthgonal direction.
      BSplineLattice3Df getLattice()
      Return access to the 3D discretized B-Spline internally created given the size of tbe input target image, and the specified number of control points and degree of basis function for each B-Spline basis axis.
      private static void initPolyhedronTrimeshConnectivity​(int iTriangleOffset, int iAxisA, int iAxisB, int iAxisC, int iOffsetAxisC)
      Called by the constructor to add the relative control point offset indices for triangle mesh representation of the bounding polyhedron formed by the neighboring 26 control points.
      void minimizeControlPoint​(int iControlX, int iControlY, int iControlZ, int iMaxSteps, float fStepSize)
      Move the specified control point using a gradient descent approach to minimize the error.
      float moveControlPoint​(int iControlX, int iControlY, int iControlZ, WildMagic.LibFoundation.Mathematics.Vector3f kPoint)
      Move the control point from its current location to the requested location.
      protected void update​(int iMinX, int iMaxX, int iMinY, int iMaxY, int iMinZ, int iMaxZ)  
      protected void updateControlPointSamples​(int iControlX, int iControlY, int iControlZ)
      Update the registered source image and the computed error as a result of making changes to a single control point.
      protected void updateSamplesMT​(int iMinX, int iMaxX, int iMinY, int iMaxY, int iMinZ, int iMaxZ)  
      protected void updateSamplesST​(int iMinX, int iMaxX, int iMinY, int iMaxY, int iMinZ, int iMaxZ)
      Update the registered source image and the computed error but only for the specified range of samples.

      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • ms_aaaiPolyhedronTriangleControlPointOffset

        protected static int[][][] ms_aaaiPolyhedronTriangleControlPointOffset
        Defines the relative offset in control point indices for the triangle mesh associated with the bounding polyhedron formed by the 26 neighboring control points. Triangle vertices are consistently counterclockwise ordered. First index: 0 for X axis, 1 for Y axis, 2 for Z axis; Second index: index of vertex within triangle; Third index: index for triangle (there are 48 -- 8 per face; see initPolyhedronTrimeshConnectivity method for description)

      • m_iNumSamplesSrcX

        protected int m_iNumSamplesSrcX
        DOCUMENT ME!

      • m_iNumSamplesSrcXY

        protected int m_iNumSamplesSrcXY
        DOCUMENT ME!

      • m_iNumSamplesSrcY

        protected int m_iNumSamplesSrcY
        DOCUMENT ME!

      • m_iNumSamplesSrcZ

        protected int m_iNumSamplesSrcZ
        DOCUMENT ME!

      • m_iNumSamplesTrgX

        protected int m_iNumSamplesTrgX
        Number of samples in source and target images.

      • m_iNumSamplesTrgXY

        protected int m_iNumSamplesTrgXY
        DOCUMENT ME!

      • m_kBSplineBasisX

        protected WildMagic.LibFoundation.Curves.BSplineBasisDiscretef m_kBSplineBasisX
        3D B-Spline basis definitions.

      • m_kBSplineBasisY

        protected WildMagic.LibFoundation.Curves.BSplineBasisDiscretef m_kBSplineBasisY
        DOCUMENT ME!

      • m_kBSplineBasisZ

        protected WildMagic.LibFoundation.Curves.BSplineBasisDiscretef m_kBSplineBasisZ
        DOCUMENT ME!

    • Constructor Detail

      • BSplineRegistration3Df

        public BSplineRegistration3Df​(ModelSimpleImage kImageSrc,
                              ModelSimpleImage kImageTrg,
                              WildMagic.LibFoundation.Curves.BSplineBasisf kBasisX,
                              WildMagic.LibFoundation.Curves.BSplineBasisf kBasisY,
                              WildMagic.LibFoundation.Curves.BSplineBasisf kBasisZ,
                              RegistrationMeasure kRegMeasure)
        Create instance to be used for registration. Upon construction, the initial state of the registered source image is computed along with the error in comparing it to the reference target image.
        Parameters:
        kImageSrc - ModelSimpleImage Input source image which contains properties and data values. Must have either 2 or 3 dimensions where the number of dimensions matches that of the target image.
        kImageTrg - ModelSimpleImage Input target image which contains properties and data values. Must have either 2 or 3 dimensions where the number of dimensions matches that of the source image.
        kBasisX - BSplineBasisf B-spline basis for X axis which contains the B-spline degree and number of control points.
        kBasisY - BSplineBasisf B-spline basis for Y axis which contains the B-spline degree and number of control points.
        kBasisZ - BSplineBasisf B-spline basis for Z axis which contains the B-spline degree and number of control points.
        kRegMeasure - RegistrationMeasure Defines the cost measure for comparing the target image with the registered source image.

    • Method Detail

      • createImageDeformation

        public ModelSimpleImage createImageDeformation()
        Generate an image which contains the deformation value at each sample in the target image as it relates to how the source image is transformed as a result of the registration. The image of interpolated source image coordinates for each target image sample is generated and from that the Jacobian is generated at each sample using finite differences. The deformation value is then the determinant of the Jacobian.
        Returns:
        ModelSimpleImage New instance which contains the properties and data for the deformation image. This image has the same dimensions as and corresponds to the sample in the target image.

      • createImageDisplacement

        public ModelSimpleImage createImageDisplacement()
        Generate an image which contains the magnitude of the displacement vector at each sample in the target image as it relates to how the source image is transformed as a result of the registration. The image of interpolated source image coordinates for each target image sample is generated and the displacement is computed from the source image coordinates for the identity registration transformation.
        Returns:
        ModelSimpleImage New instance which contains the properties and data for the deformation image. This image has the same dimensions as and corresponds to the sample in the target image.

      • createImageSourceMap

        public ModelSimpleImage[] createImageSourceMap()
        Generate an image the size of the target image in which each sample contains the 3D interpolated point coordinates in the source image which "maps" or is registered with the corresponding point in the target image.
        Returns:
        ModelSimpleImage[] Array of three ModelSimpleImage instances. The first one contains the x coordinate, the second contains the y coordinate for the map, and the third contains the z coordinate for the map. Each image has the same dimensions which are that of the target image.

      • createSameMapping

        public BSplineRegistration3Df createSameMapping​(ModelSimpleImage kImageTrg)
        Create a new registration with the same mapping as this one and which uses the same source image and the same BSpline basis degree and number of control points. The only thing that changes is that the discrete [0,1] interval is resampled.
        Parameters:
        kImageTrg - ModelSimpleImage Resampled target image.
        Returns:
        BSplineRegistration2Df New registration of the same source image referenced to the resampled target image.

      • createSameMapping

        public BSplineRegistration3Df createSameMapping​(ModelSimpleImage kImageTrg,
                                                WildMagic.LibFoundation.Curves.BSplineBasisf kBasisX,
                                                WildMagic.LibFoundation.Curves.BSplineBasisf kBasisY,
                                                WildMagic.LibFoundation.Curves.BSplineBasisf kBasisZ)
        Create a new registration with the same mapping as this one and which uses the same source image and a possibly resampled target image, however, this time the BSpline basis degree and/or the number of control points may be different.
        Parameters:
        kImageTrg - ModelSimpleImage Possibly resampled target image.
        kBasisX - BSplineBasisf B-spline basis for X axis which contains the B-spline degree and number of control points.
        kBasisY - BSplineBasisf B-spline basis for Y axis which contains the B-spline degree and number of control points.
        kBasisZ - BSplineBasisf B-spline basis for Z axis which contains the B-spline degree and number of control points.
        Returns:
        BSplineRegistration2Df New registration of the same source image referenced to the resampled target image.

      • finalize

        public void finalize()
              throws java.lang.Throwable
        Cleanup memory.
        Overrides:
        finalize in class BSplineRegistrationBasef
        Throws:
        java.lang.Throwable - DOCUMENT ME!

      • getLattice

        public BSplineLattice3Df getLattice()
        Return access to the 3D discretized B-Spline internally created given the size of tbe input target image, and the specified number of control points and degree of basis function for each B-Spline basis axis.
        Returns:
        BSplineLattice3Df Access to 3D discretized B-Spline.

      • minimizeControlPoint

        public void minimizeControlPoint​(int iControlX,
                                 int iControlY,
                                 int iControlZ,
                                 int iMaxSteps,
                                 float fStepSize)
        Move the specified control point using a gradient descent approach to minimize the error. The gradient descent minimization is performed by sampling the error function at specified intervals. A maximum number of samples is specified, but sampling always terminates when the bounding polyhedron formed by the 26 neighboring control points is reached.
        Parameters:
        iControlX - int Identifies the control point in the 3D lattice.
        iControlY - int Identifies the control point in the 3D lattice.
        iControlZ - int Identifies the control point in the 3D lattice.
        iMaxSteps - int Maximum number of samples of the error function by moving the control point in the direction of the negative gradient.
        fStepSize - float Spacing between the samples of the error function by moving the control point in the direction of the negative gradient.

      • moveControlPoint

        public float moveControlPoint​(int iControlX,
                              int iControlY,
                              int iControlZ,
                              WildMagic.LibFoundation.Mathematics.Vector3f kPoint)
        Move the control point from its current location to the requested location. The requested location must be inside the polyhedron formed by its 26 neighboring control points. If not, then a line segment is created between the current and requested locations and the point where this line segment intersects the bounding polyhedron is found. This point is offset a little along the line segment so that it is just inside the bounding polyhedron, and this point is taken as the new location for the specified control point.
        Parameters:
        iControlX - int Identifies the control point in the 3D lattice.
        iControlY - int Identifies the control point in the 3D lattice.
        iControlZ - int Identifies the control point in the 3D lattice.
        kPoint - Point3f Requested new coordinates for the specified control point.
        Returns:
        float The distance between the updated control point position and its position before being modified.

      • getControlPointMaxMoveDist

        protected float getControlPointMaxMoveDist​(int iControlX,
                                           int iControlY,
                                           int iControlZ,
                                           WildMagic.LibFoundation.Mathematics.Vector3f kRayDirection,
                                           float fMaxDesiredDist)
        Compute the maximum distance the control point can be moved in the specified direction while keeping the control point relative to its 26 neighboring control points such that "folding" does not occur.
        Parameters:
        iControlX - int Identifies the control point in the 3D lattice.
        iControlY - int Identifies the control point in the 3D lattice.
        iControlZ - int Identifies the control point in the 3D lattice.
        kRayDirection - Vector3f Direction from the current control point location for finding the distance to the bounding polyhedron.
        fMaxDesiredDist - float Maximum distance along the ray direction that should be considered. At most, the code would consider moving the control point.
        Returns:
        float Computed distance.

      • getErrorDeriv

        protected void getErrorDeriv​(int iControlX,
                             int iControlY,
                             int iControlZ,
                             WildMagic.LibFoundation.Mathematics.Vector3f kDeriv)
        Computes the derivative of the error function at a control point by approximating with finite differences where the control point is moved small amounts in each orthgonal direction.
        Parameters:
        iControlX - int Identifies the control point in the 3D lattice.
        iControlY - int Identifies the control point in the 3D lattice.
        iControlZ - int Identifies the control point in the 3D lattice.
        kDeriv - Vector3f Vector to be filled with the derivative computed along each axis.

      • updateControlPointSamples

        protected void updateControlPointSamples​(int iControlX,
                                         int iControlY,
                                         int iControlZ)
        Update the registered source image and the computed error as a result of making changes to a single control point. This is the local control aspect of the B-Spline which means only those image samples which are affected by the control point need to be updated.
        Parameters:
        iControlX - int Identifies the control point in the 3D lattice.
        iControlY - int Identifies the control point in the 3D lattice.
        iControlZ - int Identifies the control point in the 3D lattice.

      • updateSamplesST

        protected void updateSamplesST​(int iMinX,
                               int iMaxX,
                               int iMinY,
                               int iMaxY,
                               int iMinZ,
                               int iMaxZ)
        Update the registered source image and the computed error but only for the specified range of samples.
        Parameters:
        iMinX - int Minimum X axis sample index.
        iMaxX - int Maximum X axis sample index.
        iMinY - int Minimum Y axis sample index.
        iMaxY - int Maximum Y axis sample index.
        iMinZ - int Minimum Z axis sample index.
        iMaxZ - int Maximum Z axis sample index.

      • updateSamplesMT

        protected void updateSamplesMT​(int iMinX,
                               int iMaxX,
                               int iMinY,
                               int iMaxY,
                               int iMinZ,
                               int iMaxZ)

      • update

        protected void update​(int iMinX,
                      int iMaxX,
                      int iMinY,
                      int iMaxY,
                      int iMinZ,
                      int iMaxZ)

      • initPolyhedronTrimeshConnectivity

        private static void initPolyhedronTrimeshConnectivity​(int iTriangleOffset,
                                                      int iAxisA,
                                                      int iAxisB,
                                                      int iAxisC,
                                                      int iOffsetAxisC)
        Called by the constructor to add the relative control point offset indices for triangle mesh representation of the bounding polyhedron formed by the neighboring 26 control points. This method is only called for the 8 triangles on a "face" which result from holding one of the axes at a fixed offset of -1 or +1. Hence this method would need to be called once for each of the six "faces". All of the triangles go into a single table where order does not matter.
        Parameters:
        iTriangleOffset - int Offset into triangle array for current "face". Should be one the following values: {0,8,16,24,32,40}.
        iAxisA - int Index {0,1,2} for {X,Y,Z} axis to be assigned to "face" relative A (X) axis.
        iAxisB - int Index {0,1,2} for {X,Y,Z} axis to be assigned to "face" relative B (Y) axis.
        iAxisC - int Index {0,1,2} for {X,Y,Z} axis to be assigned to "face" relative C (Z) axis.
        iOffsetAxisC - int Fixed control point index relative offset value -1 or +1 to be assigned to "face" relative C (Z) axis.