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

Class CAAMModel

java.lang.Object
gov.nih.mipav.view.renderer.WildMagic.AAM.CAAMObject
gov.nih.mipav.view.renderer.WildMagic.AAM.CAAMModel
Direct Known Subclasses:
C_AAMMODEL, CAAMModelMS, CAAMModelSeq
public class CAAMModel 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 $ The core Active Appearance Model object that hold all eigenmodels, prediction matrices etc. Build by a CAAMBuilder.
Author:
Ruida Cheng

  • Field Details

    • m_pAnalyzeSynthesize

      protected CAAMAnalyzeSynthesize m_pAnalyzeSynthesize
      AAM synthesize analysis.

    • m_pReferenceFrame

      protected CAAMReferenceFrame m_pReferenceFrame
      AAM reference frame.

    • m_pShapeBasis

      protected CAAMDeform m_pShapeBasis
      The shape basis.

    • m_pTextureBasis

      protected CAAMDeform m_pTextureBasis
      The texture basis.

    • m_ShapePCA

      protected CAAMDeformPCA m_ShapePCA
      The shape PCA.

    • m_TexturePCA

      protected CAAMDeformPCA m_TexturePCA
      The texture PCA.

    • m_CombinedPCA

      protected CAAMDeformPCA m_CombinedPCA
      The combined PCA.

    • m_mShape2PixelWeights

      protected CDMatrix m_mShape2PixelWeights
      The shape-to-pixel weights.

    • m_dAMFVersion

      protected double m_dAMFVersion
      The AMF format version.

    • m_mQsEV

      protected CDMatrix m_mQsEV
      The shape part of the combined eigenvectors.

    • m_mQgEV

      protected CDMatrix m_mQgEV
      The texture part of the combined eigenvectors.

    • m_vMeanTexture

      protected CDVector m_vMeanTexture
      The mean texture.

    • m_vMeanTextureOrg

      protected CDVector m_vMeanTextureOrg
      the mean texture original.

    • m_sMeanAShape

      protected CAAMShape m_sMeanAShape
      Cached mean shape.

    • m_mShapeInstance

      protected CDMatrix m_mShapeInstance
      Cache shape matrix.

    • m_mTextureInstance

      protected CDMatrix m_mTextureInstance
      Cache texture matrix.

    • m_vTextureVar

      protected CDVector m_vTextureVar
      The variance of each normalized pixel in the texture model.

    • m_iTextureSamples

      protected int m_iTextureSamples
      The number of texture samples in the model.

    • m_iNShapes

      protected int m_iNShapes
      the number of shapes.

    • m_dMeanShapeSize

      protected double m_dMeanShapeSize
      mean shape size.

    • m_R_c

      protected CDMatrix m_R_c
      The parameter prediction matrix

    • m_R_t

      protected CDMatrix m_R_t

    • m_pTextureTF

      protected CAAMTransferFunction m_pTextureTF
      The texture transfer function.

    • m_iModelReduction

      protected int m_iModelReduction
      flag for model reduction.

    • m_dAddExtents

      protected double m_dAddExtents
      flag to add extents.

    • m_bUseConvexHull

      protected boolean m_bUseConvexHull
      flag to use convexhull.

    • m_bUseTangentSpace

      protected boolean m_bUseTangentSpace
      flag to use targent space.

    • m_iLearningMethod

      protected int m_iLearningMethod
      which learning method to use.

    • m_iShapeTrunc

      protected int m_iShapeTrunc
      shape truncation.

    • m_iTextureTrunc

      protected int m_iTextureTrunc
      texture truncation.

    • m_iCombinedTrunc

      protected int m_iCombinedTrunc
      combined truncation.

    • m_sCurrentAnalyzeId

      protected String m_sCurrentAnalyzeId
      Current analyzer name.

    • m_dBuildTime

      protected double m_dBuildTime
      model build time.

    • m_vPoseParameterUpdateConstraints

      protected CDVector m_vPoseParameterUpdateConstraints
      pose parameters update.

    • m_vShapeParameterConstraintsMean

      protected CDVector m_vShapeParameterConstraintsMean
      shape parameters upate.

    • m_vShapeParameterConstraintsSD

      protected CDVector m_vShapeParameterConstraintsSD

    • m_DisplacementPCA

      protected CAAMDeformPCA m_DisplacementPCA
      deform displacement PCA.

  • Constructor Details

    • CAAMModel

      public CAAMModel()
      Constructor. Set up the default settings.

    • CAAMModel

      public CAAMModel(CAAMModel m)
      Copy constructor.
      Parameters:
      m - Object to copy from.

  • Method Details

    • Rc

      public CDMatrix Rc()
      Texture parameter update prediction matrix.
      Returns:
      texture prediction matrix

    • Rt

      public CDMatrix Rt()
      Pose parameter update prediction matrix.
      Returns:
      pose prediction matrix

    • Qg

      public CDMatrix Qg()
      The texture part of the combined PCA eigenvectors.
      Returns:
      combined texture PCA

    • Qs

      public CDMatrix Qs()
      The shape part of the combined PCA eigenvectors.
      Returns:
      combined shape PCA

    • ReferenceFrame

      public CAAMReferenceFrame ReferenceFrame()
      Returns the reference frame of the model.
      Returns:
      refrence frame

    • NBands

      public int NBands()
      Returns the number of bands in the model
      Returns:
      single channel to represent the gray scal intensity.

    • TextureTF

      public CAAMTransferFunction TextureTF()
      Return texture transfer function.
      Returns:
      return texture transfer function

    • NTextureSamples

      public int NTextureSamples()
      Returns the number of samples in the texture model.
      Returns:
      sample numbers

    • IsConvexHullUsed

      public boolean IsConvexHullUsed()
      Returns true if the texture model is based on the convex hull.
      Returns:
      ture convex hull, false not

    • AddExtents

      public double AddExtents()
      Returns the amount shape extents added (warning: shape extents will be remove in later versions).
      Returns:
      shape extents

    • MeanShape

      public CAAMShape MeanShape()
      Returns the mean shape.
      Returns:
      mean shape

    • MeanTexture

      public CDVector MeanTexture()
      Returns the mean texture.
      Returns:
      mean texture

    • Shape2PixelWeights

      public CDMatrix Shape2PixelWeights()
      Return shape to pixel weight.
      Returns:
      weight

    • ShapePCA

      public final CAAMDeformPCA ShapePCA()
      Returns the shape PCA.
      Returns:
      shape PCA

    • TexturePCA

      public final CAAMDeformPCA TexturePCA()
      Returns the texture PCA.
      Returns:
      texture PCA

    • ShapeBasis

      public CAAMDeform ShapeBasis()
      Returns the shape PCA.
      Returns:
      shape PCA.

    • TextureBasis

      public CAAMDeform TextureBasis()
      Returns the texture PCA.
      Returns:
      texture PCA.

    • CombinedPCA

      public CAAMDeformPCA CombinedPCA()
      Returns the combined PCA.
      Returns:
      combined PCA.

    • ModelReduction

      public int ModelReduction()
      Return model reduction.
      Returns:
      flag for model reduction.

    • MeanShapeSize

      public double MeanShapeSize()
      Returns the mean shape size, i.e. the size of the reference shape.
      Returns:
      mean shape size.

    • dispose

      public void dispose()
      dispose memory

    • ApproxExample

      public boolean ApproxExample(String filename, ModelSimpleImage outImg)
      Doing model approximation of an (unseen) example. Synthesizes an unseen example by projecting the shape and (normalized) texture into c-parameter space, generating a model instance and assigning it the appropriate pose (incl. denormalization).
      Parameters:
      filename - The base filename of an annotation. Ex. "scan.asf"
      outImg - The output image where the model approximation has been overlaid.
      Returns:
      true on success, false if the image and/or annotation could not be read.

    • SetPoseParameterUpdateConstraints

      public void SetPoseParameterUpdateConstraints(CDVector pc)
      Sets constraints on the pose parameter updates. NOTICE: Currently, these are *not* saved along with the model and thus must be set each time a model is loaded.
      Parameters:
      pc - Parameter constraints (in absolute numbers).

    • SetShapeParameterUpdateConstraints

      public void SetShapeParameterUpdateConstraints(CDVector mean, CDVector sd)
      Sets user-specified shape parameter update constraints. NOTICE: These are currently not saved with the model.
      Parameters:
      mean - Some shape parameter configuration.
      sd - The standard diviations of the 'mean'.

    • ConstrainSearchParameters

      public void ConstrainSearchParameters(CDVector c, CDVector pose)
      Constrain the pose and model parameters to be within some reasonable limits.
      Parameters:
      c - The model parameters.
      pose - The pose parameters.

    • EstimatePose

      public boolean EstimatePose(ModelSimpleImage image, CAAMShape shape, CDVector pose)
      Estimate the pose of a shape using the pose regression matrix.
      Parameters:
      image - The image to search in.
      shape - The shape to determine the pose from.
      pose - The output pose vector.
      Returns:
      True is ok, false if the shape is outside the image.

    • ModelImage

      public void ModelImage(CDVector c, ModelSimpleImage outImg, CAAMShape matchPose)
      Generate model instance (match pose to 'shape') and render the instance into the image 'img'.
      Parameters:
      c - combined model parameters
      outImg - result image
      matchPose - matched shape

    • ModelImage

      public void ModelImage(CDVector c, ModelSimpleImage outImg, CAAMShape matchPose, boolean fitTexture)
      Generates a model image based on the parameters in 'c' with various options.
      Parameters:
      c - A set of model parameters.
      outImg - The output imge.
      matchPose - A pointer to a shape. If not NULL the model generated by the set of c-parameters will be aligned wrt. pose to this shape.
      fitTexture - If matchPose is not NULL, the de-mapped and de-normalized texture will be fitted in a least squares sense to the texture in outImg given by the shape. Default true.

    • ModelImageEx

      public void ModelImageEx(CAAMShape shape, CDVector texture, ModelSimpleImage outImg, boolean renderImage, boolean fitTexture)
      Generates a synthetic image from the AAM using the model parameters in 'c'.
      Parameters:
      shape - The shape the texture vector should be mapped to.
      outImg - The output image (sized correctly inside this method, if renderInImage is false).
      renderImage - If true: 1) outImg is expected to be allocated. 2) the model is rendered with it's pose unchanged, thus the shape is expected to lie within the outImg This option is used for drawing the final optimization into the image or to draw a model approximation into the image 'outImg'. Default false.
      fitTexture - If renderImage is true, the de-mapped and de-normalized texture will be fitted in a least squares sense to the texture in outImg given by the shape. Default true.
      textureSamples - The texture vector to be warped into an image. Will be de-mapped and de-normalized.

    • ShapeFreeImage

      public ModelSimpleImage ShapeFreeImage(CDVector textureSamples, ModelSimpleImage outImg)
      Wrapper to generates a shape free image using a vector of texture samples.
      Parameters:
      textureSamples - texture samples
      outImg - result image
      Returns:
      shape free image

    • ShapeFreeImage

      public ModelSimpleImage ShapeFreeImage(CDVector textureSamples, ModelSimpleImage outImg, boolean deMap)
      Generates a shape free image (that is; a mean shape image) using a vector of texture samples.
      Parameters:
      textureSamples - The texture vector to be warped into an image. De-normalizes (and demaps) inside this method.
      outImg - A reference to an output image. Resize of the image is done inside this method.
      Returns:
      shape free image.

    • ShapeFreeImage

      public void ShapeFreeImage(CDVector textureSamples, CDMatrix m, boolean deMap, boolean normalize)
      Generates a shape free image (that is; a mean shape image) using a vector of texture samples.
      Parameters:
      textureSamples - The texture vector to be warped into an image. De-normalizes (and demaps) inside this method.
      m - A reference to an output image on matrix form. Resize of the matrix is done inside this method.
      deMap -

    • ModelEstimateTexDiff

      public double ModelEstimateTexDiff(ModelSimpleImage image, CDVector c, CAAMShape estimate, CDVector diff, int similaritym)
      Wrapper to calculate the pixel difference from a model instance and an image.
      Parameters:
      image - model image
      c - parameter vector
      estimate - estimaed shape
      diff - difference vector
      similaritym - similarity measure type
      Returns:
      similarity measure

    • ModelEstimateTexDiff

      public double ModelEstimateTexDiff(ModelSimpleImage image, CDVector c, CAAMShape estimate, CDVector diff, int similaritym, boolean useInterpolation)
      Calculates the pixel difference from a model instance and an image.
      Parameters:
      image - The image (input)
      c - Model parameters (in/output).
      estimate - The shape estimate (in/output).
      diff - The pixel difference vector (output) Resized inside.
      similaritym - Set the used similarity measure: 0 Non-normalised L_2 norm (default) 1 The "Mahalanobis" distance (texture samples are regarded independent to increase performance). 2 The Lorentzian error norm. 3 Absolute auto correlation of the residuals.
      Returns:
      The similarity measure.

    • NormalizeTexture

      public void NormalizeTexture(CDVector texture)
      Normalizes a texture vector.
      Parameters:
      texture - Texture to be normalized.

    • OptimizeModel

      public CAAMOptRes OptimizeModel(ModelSimpleImage image, CAAMShape s, CDVector c)
      Wrapper for model optimization.
      Parameters:
      image - search image
      s - init shape
      c - init model parameters
      Returns:
      optimization result

    • OptimizeModel

      public CAAMOptRes OptimizeModel(ModelSimpleImage image, CAAMShape s, CDVector c, int maxIterations, Vector<CAAMOptState> pOptStates)
      Wrapper for model optimization
      Parameters:
      image - search image
      s - init shape
      c - init parameters
      maxIterations - max iterations
      pOptStates - optimization state
      Returns:
      optimization result

    • OptimizeModel

      public CAAMOptRes OptimizeModel(ModelSimpleImage image, CAAMShape s, CDVector c, int maxIterations, Vector<CAAMOptState> pOptStates, boolean disableDamping)
      Performs AAM optimization of a shape containing initial pose and a set of model parameters (c).
      Parameters:
      image - The image to search in.
      s - The initial shape (also containing the inital pose, thus; not a normalized shape). Actually only the pose of 's' is used (to align the reference shape as the initial shape). NOTE: The optimal shape is returned in 's' after execution.
      c - The initial model parameters. If this vector is empty, it is resized correctly and set equal to zero, thus the mean model. NOTE: The optimal model parameters are returned in 'c' after execution.
      maxIterations - The maximum iterations allowed.
      pOptStates - Optional parameter all convergence info can be returned in. See CAAMOptState.
      disableDamping - Disables the damping steps (default false).
      Returns:
      The results of the optimization in the form of a 'CAAMOptRes' instance.

    • OptimizeModelByFineTuning

      public CAAMOptRes OptimizeModelByFineTuning(ModelSimpleImage image, CAAMShape s, CDVector c, int maxIterations, int similaritym, int optimizer)
      Perform general-purpose optimization of the AAM using simulated annealing, conjugate gradient, steepest descent, BGFS or pattern search.
      Parameters:
      image - The image beeing searched in.
      s - The inital shape pose.
      c - The initial model parameters.
      maxIterations - The maximum allowed number of iterations.
      similaritym - The used similarity measure for the optimization: 0 Non-normalized L_2 norm (default). 1 The "Mahalanobis" distance (texture samples are regarded independent to increase performance). 2 The Lorentzian error norm.
      optimizer - Sets the optimer to use: 1 Steepest Descent (default) 2 Conjugate Gradient 3 Quasi-Newton, BFGS 4 Pattern search 5 Simulated annealing
      Returns:
      The final fit.

    • ReadModel

      public boolean ReadModel(String filename)
      Reads the complete AAMModel from disk.
      Parameters:
      filename - Input filename without any extension. E.g. if the files on disk are 'model.txt' invalid input: '&' 'model.amf' -> filename = 'model'
      Returns:
      true on success, false on file errors.

    • ReductionFactor

      public int ReductionFactor()
      Returns the reduction factor of the training set that this model was
      Returns:
      model reduction

    • SampleShape

      public int SampleShape(ModelSimpleImage image, CAAMShape shape, CDVector textureSamples)
      Wrapper to build a texture vector from an image and a shape.
      Parameters:
      image - model image
      shape - voi
      textureSamples - texture samples
      Returns:
      shape inside or outside the image

    • SampleShape

      public int SampleShape(ModelSimpleImage image, CAAMShape shape, CDVector textureSamples, boolean normalize)
      Wrapper to build a texture vector from an image and a shape.
      Parameters:
      image - model image
      shape - VIO
      textureSamples - texture samples
      normalize - normalization
      Returns:
      shape inside or outside the image

    • SampleShape

      public int SampleShape(ModelSimpleImage image, CAAMShape shape, CDVector textureSamples, boolean normalize, boolean useInterpolation)
      Wrapper to build a texture vector from an image and a shape.
      Parameters:
      image - model image
      shape - VIO
      textureSamples - texture samples
      normalize - normalization
      useInterpolation - interpolation or not.
      Returns:
      shape inside or outside the image

    • SampleShape

      public int SampleShape(ModelSimpleImage image, CAAMShape shape, CDVector textureSamples, boolean normalize, boolean useInterpolation, boolean map)
      Builds a texture vector from an image and a shape.
      Parameters:
      image - The image to sample in.
      shape - The shape to sample from (in image coordinates).
      textureSamples - The normalized destination texture vector.
      normalize - Perform normalization after sampling. Default true.
      map - Perform mapping after sampling. Default true.
      Returns:
      The number of samples done (zero if the shape is outside the image).

    • ShapeInstance

      public void ShapeInstance(CDVector c, CAAMShape outShape)
      Generates a shape based on a set of model parameters.
      Parameters:
      c - Input model parameters.
      outShape - The generated shape (resizing are done inside this method).

    • TextureInstance

      public void TextureInstance(CDVector c, CDVector outTexture)
      Generates a texture based on a set of model parameters.
      Parameters:
      c - Input model parameters.
      outShape - The generated texture (resizing are done inside this method).

    • ShapePCAInstance

      public void ShapePCAInstance(CDVector b_s, CAAMShape outShape)
      Generates a shape based on a set of shape b-parameters.
      Parameters:
      b_s - Shape parameters
      outShape - Output shape (resized inside method).

    • ShapeTex2Combined

      public void ShapeTex2Combined(CAAMShape shape, CDVector texture, CDVector c)
      Projects the shape and texture into c-space i.e. the combined model parameters.
      Parameters:
      shape - The input shape aligned to the (aligned) mean shape.
      texture - The corresponding normalized texture.
      c - The resulting model parameters.

    • ShapeTex2Param

      public void ShapeTex2Param(CAAMShape shape, CDVector texture, CDVector b)
      Extract the b-parameters from a shape and corresponding texture by inverting the shape and texture pca projection. Assumes that the shape and texture PCA are done beforehand.
      Parameters:
      shape - The input shape aligned to the (aligned) mean shape.
      texture - The corresponding normalized texture.
      b - The resulting concatenated b vector.

    • ShapeTexParam2Combined

      public void ShapeTexParam2Combined(CDVector b, CDVector c)
      Transforms the concatenated b-parameters into combined model parameters.
      Parameters:
      b - Concatenated shape (weighted) and texture parameters
      c - Combined model parameters (resized inside function).
      See Also:

    • WriteModel

      public boolean WriteModel(String filename)
      Write the AAM model to text file or binary file.
      Parameters:
      filename - file name
      Returns:
      success or not

    • WriteModel

      public boolean WriteModel(String filename, boolean txt_only)
      Writes the complete AAMModel to disk as a .txt and an .amf file.
      Parameters:
      filename - Output filename without any extension.
      txt_only - If true binary model data is not written.
      Returns:
      true on success, false on file errors.

    • getNumberShapeParameters

      public int getNumberShapeParameters()
      Get the the number of eigen values in PCA.
      Returns:
      number of eigen values in PCA

    • WriteVarianceMap

      public void WriteVarianceMap(String filename)
      Plots the variance of each pixel in the model over the training set into the mean shape and saves the image.
      Parameters:
      filename - Output image filename.

    • ReferenceShape

      public final CAAMShape ReferenceShape()
      Returns the reference shape where all texture sampling and comparison should be done. The reference shape is defined as the mean shape size to mean size and moved to the fourth quadrant.
      Returns:
      The reference shape.

    • ShapeTexParam2Combined

      public void ShapeTexParam2Combined(Vector<CDVector> bVectors, Vector<CDVector> cVectors)
      Converts a set of b-vectors to combined model parameters (c-vectors).
      Parameters:
      bVectors - The input b-vectors.
      cVectors - The output c-vectors.

    • assign

      public CAAMModel assign(CAAMModel m)
      Assignment operator.
      Parameters:
      m - Object to copy from.
      Returns:
      This;

    • Shape2Combined

      public void Shape2Combined(CAAMShape shape, ModelSimpleImage image, CDVector c)
      Projects a shape into a set of c parameters.
      Parameters:
      shape - The input shape (assumed to be in abs coordinates).
      image - The image where the shape is placed.
      c - The output combined model parameters.

    • Shape2Param

      public void Shape2Param(CAAMShape shape, CDVector b_s)
      Projects a shape into a set of shape parameters,
      Parameters:
      shape - The input shape (assumed to be in abs parameters).
      b - The output shape model parameters.

    • Combined2ShapeParam

      public void Combined2ShapeParam(CDVector c, CDVector b_s)
      Converts combined model parameters to shape parameters.
      Parameters:
      c - Combined model parameters.
      b_s - Output non-weighted shape parameters.

    • Combined2TexParam

      public void Combined2TexParam(CDVector c, CDVector b_g)
      Converts combined model parameters to texture parameters.
      Parameters:
      c - Combined model parameters.
      b_g - Output texture parameters.

    • ShapeTexParam2Combined

      public void ShapeTexParam2Combined(CDVector b_s, CDVector b_g, CDVector c)
      Projects shape and texture parameters into the combined eigenspace.
      Parameters:
      b_s - Input shape parameters.
      b_g - Input texture parameters.
      c - Resulting combined model parameters.