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

Class 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 & 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 Detail

      • m_vTexture

        protected java.util.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 Detail

      • CAAMBuilder

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

    • Method Detail

      • BuildFromFiles

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

      • BuildFromFiles

        public void BuildFromFiles​(CAAMModel model,
                           java.lang.String inDir,
                           java.lang.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,
                          java.util.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,
                           java.lang.String inDir,
                           java.lang.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,
                          java.util.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,
                           java.util.Vector<java.lang.String> asfFiles,
                           java.lang.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​(java.util.Vector<java.lang.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,
                          java.util.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​(java.util.Vector<CDVector> bVectors)
        Write additional documentation output.
        Parameters:
        bVectors - Concatenated and weighted shape and texture vectors over the training set.

      • EstRegressionMatrices

        public void EstRegressionMatrices​(java.util.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​(java.util.Vector<CDVector> vPoseDisps,
                                 java.util.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.
        Y - Output matrix containing the model parameter displacements carried out.
        ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
        Returns:
        Nothing.

      • DoCParamExperiments

        public boolean DoCParamExperiments​(java.util.Vector<CDVector> vCDisps,
                                   java.util.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.
        Y - Output matrix containing the model parameter displacements carried out.
        ts_subsampling - Subsampling factor, i.e. ts_subsampling==n will carry out displacements on every n-th example in the training set.
        Returns:
        Nothing.

      • DisplacementSets

        public void DisplacementSets​(java.util.Vector<CDVector> vCDisps,
                             java.util.Vector<CDVector> vPoseDisps,
                             java.util.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 java.util.Vector<CDVector> CParamDispVectors​(CDVector vStdDisp,
                                                    java.util.Vector<CDVector> cVectors)
        Wrapper to generate damp displacement vectors
        Parameters:
        vStdDisp - displacement vector
        cVectors - c parameters
        Returns:
        displacement vector

      • CParamDispVectors

        public java.util.Vector<CDVector> CParamDispVectors​(CDVector vStdDisp,
                                                    java.util.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 java.util.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​(java.util.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​(java.lang.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 java.util.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​(java.util.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​(java.util.Vector<CDVector> vPoseDisps,
                                     java.util.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​(java.util.Vector<CDVector> vCDisps,
                                       java.util.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.