Package gov.nih.mipav.view.renderer.WildMagic.AAM

Class CAAMBuilder

java.lang.Object
gov.nih.mipav.view.renderer.WildMagic.AAM.CAAMObject
gov.nih.mipav.view.renderer.WildMagic.AAM.CAAMBuilder
Direct Known Subclasses:
C_AAMBUILDER
public class CAAMBuilder extends CAAMObject
This is the Java modified version of C++ active appearance model API (AAM_API). It is modified with a subset of required functions for automatic MRI prostate segmentation. AAM-API LICENSE - file: license.txt This software is freely available for non-commercial use such as research and education. Please see the full disclaimer below. All publications describing work using this software should cite the reference given below. Copyright (c) 2000-2003 Mikkel B. Stegmann, mbs@imm.dtu.dk IMM, Informatics invalid input: '&' Mathematical Modelling DTU, Technical University of Denmark Richard Petersens Plads, Building 321 DK-2800 Lyngby, Denmark http://www.imm.dtu.dk/~aam/ REFERENCES Please use the reference below, when writing articles, reports etc. where the AAM-API has been used. A draft version the article is available from the homepage. I will be happy to receive pre- or reprints of such articles. /Mikkel ------------- M. B. Stegmann, B. K. Ersboll, R. Larsen, "FAME -- A Flexible Appearance Modelling Environment", IEEE Transactions on Medical Imaging, IEEE, 2003 (to appear) ------------- 3RD PART SOFTWARE The software is partly based on the following libraries: - The Microsoft(tm) Vision Software Developers Kit, VisSDK - LAPACK DISCLAIMER This software is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any non-commercial purpose, and to alter it, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. -- No guarantees of performance accompany this software, nor is any responsibility assumed on the part of the author or IMM. This software is provided by Mikkel B. Stegmann and IMM ``as is'' and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall IMM or Mikkel B. Stegmann be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. $Revision: 1.4 $ $Date: 2003/04/23 14:49:15 $ Factory object that produces CAAMModel objects. Main tasks are the estimation of parameter update matrices and verbose dumping of model information. Most other tasks are simple calls into CAAMModel, CAAMShape etc.
Author:
Ruida Cheng

  • Field Details

    • m_Shapes

      protected CAAMShapeCollection m_Shapes
      The raw (unaligned) shapes.

    • m_AlignedShapes

      protected CAAMShapeCollection m_AlignedShapes
      The aligned shapes.

    • m_vTexture

      protected Vector<CDVector> m_vTexture
      The texture samples.

    • m_bVerbose

      protected boolean m_bVerbose
      current default to false, not used

    • m_bWriteRegMovie

      protected boolean m_bWriteRegMovie

    • m_bWriteVarImage

      protected boolean m_bWriteVarImage

    • m_bMakeDocumentation

      protected boolean m_bMakeDocumentation

    • m_iTSSubsampling

      protected int m_iTSSubsampling

    • m_iWarpMethod

      protected int m_iWarpMethod

    • m_pModel

      protected CAAMModel m_pModel
      the model we're building.

  • Constructor Details

    • CAAMBuilder

      public CAAMBuilder()
      Constructor. Sets up default values for the settings usally given by an acf file.

  • Method Details

    • BuildFromFiles

      public void BuildFromFiles(CAAMModel model, String inDir)
      Build the model from text based file
      Parameters:
      model - model to build
      inDir - file instream dir.

    • BuildFromFiles

      public void BuildFromFiles(CAAMModel model, String inDir, String acf)
      Build the model from text based file and AAM configuration file
      Parameters:
      model - model to build
      inDir - text file input dir
      acf - aam configuration file

    • BuildModel

      public boolean BuildModel(CAAMModel model, Vector<ModelImage> modelImageVector)
      Build the model from prostate images and VOIs
      Parameters:
      model - model to build
      modelImageVector - array of prostate image and VOIs
      Returns:
      build success or not

    • BuildFromFiles

      public void BuildFromFiles(CAAMModel model, String inDir, String acf, int modelReduction, int excludeShape)
      Diver method for model generation. This method automates the model generation as much as possible by using the various class methods for all the sequences in the task of producing a model.
      Parameters:
      model - The generated model.
      inDir - Input directory where annotations (.asf) resides.
      acf - Filename of an AAM configuration file. If omitted defaults are used.
      modelReduction - Model reduction multiplier. Default off == 1. Useful when building multi-scale AAMs.
      excludeShape - Excludes one shape number 'excludeShape' from the input directory. Default -1, i.e. no shapes are removed. Used to perform leave-one-out testing.

    • BuildModel

      public boolean BuildModel(CAAMModel model, Vector<ModelImage> modelImageVector, int modelReduction, int excludeShape)
      Build the model in supervised way, with given prostate images and VOIs.
      Parameters:
      model - The generated model.
      modelImageVector - vector for prostate images and VOIs
      modelReduction - Model reduction multiplier. Default off == 1. Useful when building multi-scale AAMs.
      excludeShape - Excludes one shape number 'excludeShape' from the input directory. Default -1, i.e. no shapes are removed. Used to perform leave-one-out testing.
      Returns:
      nothing

    • BuildFromFiles

      public void BuildFromFiles(CAAMModel model, Vector<String> asfFiles, String acf, int modelReduction, int excludeShape)
      Diver method for model generation. This method automates the model generation as much as possible by using the various class methods for all the sequences in the task of producing a model.
      Parameters:
      model - The generated model.
      asfFiles - Vector of asf filenames.
      acf - Filename of an AAM configuration file. If omitted defaults are used.
      modelReduction - Model reduction multiplier. Default off == 1. Useful when building multi-scale AAMs.
      excludeShape - Excludes one shape number 'excludeShape' from the input directory. Default -1, i.e. no shapes are removed. Used to perform leave-one-out testing.

    • pause

      public static void pause()
      Pauses the display until the user hits enter.

    • LoadShapes

      public boolean LoadShapes(Vector<String> asfFiles, CAAMShapeCollection destination, int modelReduction, boolean addCompleteImage, double addExtents, int excludeShape)
      Loads (and preprocess) all training shapes. Loads (and preprocess) all training shapes into a CAAMShapeCollection. This could as well be placed in CAAMUtil actually.
      Parameters:
      asfFiles - An array of asf filenames.
      destination - Output shape collection.
      modelReduction - Optional size reduction. Default 1, i.e. no reduction.
      addCompleteImage - Set this to true if you (for wird reasons) would like add the corners of the image to the shape. Default false.
      addExtents - Simple and somewhat hacked way to add a shape neighborhood (will be removed in later versions).
      excludeShape - If != -1 the the 'excludeShape'-th shape will be excluded. Zero is the first shape. Used for leave-one-out evaluation.
      Returns:
      Nothing.

    • LoadShapes

      public boolean LoadShapes(CAAMShapeCollection destination, Vector<ModelImage> modelImageVector, int modelReduction, boolean addCompleteImage, double addExtents, int excludeShape)
      Load all training shapes from prostate image vector VOIs.
      Parameters:
      destination - Output shape collection.
      modelImageVector - prostate image vector with VOIs
      modelReduction - Optional size reduction. Default 1, i.e. no reduction.
      addCompleteImage - Set this to true if you (for wird reasons) would like add the corners of the image to the shape. Default false.
      addExtents - Simple and somewhat hacked way to add a shape neighborhood (will be removed in later versions).
      excludeShape - If != -1 the the 'excludeShape'-th shape will be excluded. Zero is the first shape. Used for leave-one-out evaluation.
      Returns:
      nothing

    • MapTextures

      public void MapTextures()
      Performs a mapping of all textures in 'm_vTexture'. Performs a mapping of all textures in 'm_vTexture' using the texture transfer class of the model.

    • DumpModelDoc

      public void DumpModelDoc(Vector<CDVector> bVectors)
      Write additional documentation output.
      Parameters:
      bVectors - Concatenated and weighted shape and texture vectors over the training set.

    • EstRegressionMatrices

      public void EstRegressionMatrices(Vector<CDVector> bVectors, int ts_subsampling)
      Build the regression matrices for pose and parameter prediction. I.e. calculates the member variables 'regR_c', 'regR_t'. using principal component regression.
      Parameters:
      bVectors - The b-vectors for the training set the current AAM is built upon. [Can be optained from the DoCombinedPCA() call]
      ts_subsampling - Controls the sub sampling of the training set - i.e. to use every fifth shape to build the regression matrices upon, set shape_subsampling = 5; The motivation for doing this is reduction of model building time -- and perhaps most importantly -- conservation of memory resources.

    • DoPoseExperiments

      public boolean DoPoseExperiments(Vector<CDVector> vPoseDisps, Vector<CDVector> cVectors, CDMatrix X, CDMatrix C, int ts_subsampling)
      Performs a set of pose parameter displacement experiments on the training set given a set of displacment vectors.
      Parameters:
      vPoseDisps - A vector of displacement vectors as obtained from PoseDispVectors() or DisplacementSets().
      cVectors - The set of optimum c vectors for the training examples.
      X - Output matrix containing the texture difference vectors obtained from the displacements.
      ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
      Y - Output matrix containing the model parameter displacements carried out.
      Returns:
      Nothing.

    • DoCParamExperiments

      public boolean DoCParamExperiments(Vector<CDVector> vCDisps, Vector<CDVector> cVectors, CDMatrix X, CDMatrix C, int ts_subsampling)
      Performs a set of model parameter displacement experiments on the training set given a set of displacment vectors.
      Parameters:
      vCDisps - A vector of displacement vectors as obtained from CParamDispVectors() or DisplacementSets().
      cVectors - The set of optimum c vectors for the training examples.
      X - Output matrix containing the texture difference vectors obtained from the displacements.
      ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
      Y - Output matrix containing the model parameter displacements carried out.
      Returns:
      Nothing.

    • DisplacementSets

      public void DisplacementSets(Vector<CDVector> vCDisps, Vector<CDVector> vPoseDisps, Vector<CDVector> cVectors)
      Parameters:
      vCDisps - Resulting model parameter displacement set.
      vPoseDisps - Resulting pose parameter displacement set.
      cVectors - The set of c vectors over the training set.

    • CParamDispVectors

      public Vector<CDVector> CParamDispVectors(CDVector vStdDisp, Vector<CDVector> cVectors)
      Wrapper to generate damp displacement vectors
      Parameters:
      vStdDisp - displacement vector
      cVectors - c parameters
      Returns:
      displacement vector

    • CParamDispVectors

      public Vector<CDVector> CParamDispVectors(CDVector vStdDisp, Vector<CDVector> cVectors, int pStart, int pLen)
      Generates a set combined model parameter displacement vectors where each parameter is displaced at a time according to the values in vStdDisp.
      Parameters:
      vStdDisp - A vector of parameter displacements in standard deviations of the corresponding parameter.
      cVectors - The set of c vectors over the training set.
      pStart - The first parameter to displace. (default 0).
      pLen - The number of parameters to displace. (default 0, which means all parameters).
      Returns:
      A vector of displacement vectors.

    • PoseDispVectors

      public Vector<CDVector> PoseDispVectors(CDVector vXDisp, CDVector vYDisp, CDVector vScaleDisp, CDVector vRotDisp)
      Generates a set pose displacement vectors.
      Parameters:
      vXDisp - A vector of x displacements in pixels.
      vYDisp - A vector of y displacements in pixels.
      vScaleDisp - A vector of scale displacements (1.0=no scaling).
      vRotDisp - A vector of rotation displacements in degrees.
      Returns:
      A vector of displacement vectors.

    • BuildTextureVectors

      public void BuildTextureVectors()
      Samples all shapes in the training set and build the corresponding texture vectores. Initializes the private member: 'm_vTexture' by sampling all shapes using a warp function. Note that this method calculates the mean texture.

    • BuildTextureVectorsFromImage

      public void BuildTextureVectorsFromImage()
      Transform image to texture vector

    • dispose

      public void dispose()
      Dispose memory

    • CalcPixel2ShapeWeights

      public void CalcPixel2ShapeWeights()
      Calculates the pixel-to-shape weights used in the combined PCA. Currently the simple 'split even' strategy is employed, i.e. normalise shape and texture variance to be equal.

    • PoseDisplacement

      public boolean PoseDisplacement(ModelSimpleImage image, CAAMShape shape, CDVector c0, CDVector t, CDVector pixel_diff)
      Performs one pose regression experiment.
      Parameters:
      image - The image corresponding to the equibrilium shape.
      shape - The equibrilium shape.
      c0 - The equibrilium model parameters.
      t - The pose displacement parameters.
      pixel_diff - The normalized pixel differences resulting from the pose displacement.
      Returns:
      Nothing.

    • ModelDisplacement

      public boolean ModelDisplacement(ModelSimpleImage image, CAAMShape shape, CDVector c0, CDVector delta_c, CDVector pixel_diff)
      Performs one model parameter regression experiment.
      Parameters:
      image - The image corresponding to the equibrilium shape.
      shape - The equibrilium shape.
      c0 - The equibrilium model parameters.
      delta_c - The model parameter displacements.
      pixel_diff - The normalized pixel differences resulting from the pose displacement.
      Returns:
      Nothing.

    • DoShapeAlignment

      public void DoShapeAlignment(boolean fUseTangentSpace)
      Alignes shapes and calc mean- and reference-shape. I.e. initializes 'm_AlignedShapes', 'm_sMeanAShape' and 'm_sReferenceShape'.
      Parameters:
      fUseTangentSpace - Use the tangent space projection (bool).

    • DumpPCA

      public void DumpPCA(Vector<CDVector> bVectors)
      Dumps the PC scores of the shape, texture and combined PCA. These are written to the current directory in Matlab format as shape_pc.m, texture_pc.m and combined_pc, respectively. param bVectors The b-parameters for all training examples. As obtained from DoCombinedPCA().

    • NormalizeTextureVectors

      public void NormalizeTextureVectors()
      Iterative normalization of the texture samples. Performs normalization of the texture vectors as described by Cootes et al. in "Active Appearance Models" sec. 2. Recalculates the mean texture.

    • ReadACF

      public boolean ReadACF(String filename)
      Reads and parses an ACF file. In this way the AAM can be configured using different setting for model generation. Note that all parsing is very primitive and in no way robust :-( So be careful about the configuration files.
      Parameters:
      filename - The acf file to open.
      Returns:
      true on success, false on file errors.

    • setACF

      public boolean setACF()
      Reads and parses an ACF file. In this way the AAM can be configured using different setting for model generation. Note that all parsing is very primitive and in no way robust :-( So be careful about the configuration files.
      Parameters:
      filename - The acf file to open.
      Returns:
      true on success, false on file errors.

    • RecalcMeanTexture

      public void RecalcMeanTexture()
      Recalculates the mean texture vector 'm_vMeanTexture'.

    • DoCombinedPCA

      public Vector<CDVector> DoCombinedPCA()
      Performs principal component analysis on the shape and the texture data. Uses the Eckhart-Young theorem described in appendix A of "Statistical Models of Appearance of Computer Vision" by T.F. Cootes et al. if we have fewer samples than dimensions which is typically the case.
      Returns:
      The b-parameters for all training examples. The format is a vector of b-parameter vectors. This vector is used in the BuildRegressionMatrices() call.

    • EstPredictionMatrices

      public boolean EstPredictionMatrices(Vector<CDVector> bVectors, int ts_subsampling)
      Build the prediction matrices for pose and parameter prediction. I.e. calculates the member variables 'regR_c', 'regR_t'. using estimates of the gradient matrices.
      Parameters:
      bVectors - The b-vectors for the training set the current AAM is built upon. [Can be optained from the DoCombinedPCA() call]
      ts_subsampling - Controls the sub sampling of the training set - i.e. to use every fifth shape to build the regression matrices upon, set shape_subsampling = 5; The motivation for doing this is reduction of model building time.
      Returns:
      Nothing.

    • EstPoseGradientMatrix

      public boolean EstPoseGradientMatrix(Vector<CDVector> vPoseDisps, Vector<CDVector> cVectors, CDMatrix Gpose, int ts_subsampling)
      Estimates the Jacobian of the pose parameters given a set of displacement vectors and the optimum model parameters for the training set.
      Parameters:
      vPoseDisps - A vector of displacement vectors as obtained from PoseDispVectors() or DisplacementSets().
      cVectors - The set of optimum c vectors for the training examples.
      Gpose - The output Jacobian matrix (or gradient matrix if you like).
      ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
      Returns:
      Nothing.

    • EstCParamGradientMatrix

      public boolean EstCParamGradientMatrix(Vector<CDVector> vCDisps, Vector<CDVector> cVectors, CDMatrix Gparam, int ts_subsampling)
      Estimates the Jacobian of the model parameters given a set of displacement vectors and the optimum model parameters for the training set.
      Parameters:
      vCDisps - A vector of displacement vectors as obtained from CParamDispVectors() or DisplacementSets().
      cVectors - The set of optimum c vectors for the training examples.
      Gparam - The output Jacobian matrix (or gradient matrix if you like).
      ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
      Returns:
      Nothing.