Algorithms.h

Go to the documentation of this file.

/********************************************************************
*
*   Project     Artec 3D Scanning SDK
*
*   Purpose:    Algorithms creators declarations
*
*   Copyright:  Artec Group
*
********************************************************************/

#ifndef _ALGORITHMS_H_
#define _ALGORITHMS_H_

#include <artec/sdk/algorithms/AlgorithmSdkDefines.h>
#include <artec/sdk/base/Errors.h>
#include <artec/sdk/base/IProgressInfo.h>
#include <artec/sdk/base/Point.h>
#include <artec/sdk/base/ScannerType.h>

namespace artec { namespace sdk { namespace base
{
    class  ICompositeMesh;
    class  IScan;
    class  ICompositeContainer;
    class  IModel;
    class  ICancellationToken;
    class  IProgressInfo;
    struct AlgorithmWorkset;
} } }

namespace artec { namespace sdk { namespace algorithms
{
using namespace artec::sdk::base::errors;

class IAlgorithm;

/// Enum for Poisson Fusion and Texturization algorithms.
enum InputFilter
{
    /// The only frames with texture key frame attribute set will be used by an algorithm.
    /// This type is used by default.
    InputFilter_UseTextureKeyFrames = 0,

    /// Algorithm considers all frames, which have not empty textures.
    InputFilter_UseAllTextures,
};

//////////////////////////////////////////////////////////////////////////
/// Parameters for fast fusion algorithm.
struct FastFusionSettings
{
    /// Scanner type
    base::ScannerType   scannerType;

    /// Mesh resolution (in millimeters) - step of grid which is used to reconstruct a polygonal model.
    /// Parameter defines the minimal space unit where the polygon of the model will be built in.
    /// EVA resolution should be no less than 0.4
    /// Spider resolution should be no less than 0.1
    /// L2 resolution should be no less than 0.5
    float               resolution;
    
    /// Radius( for Fast Fusion only ) - a factor to define vicinity
    /// that algorithm takes into consideration when adding each new minimal space unit.
    int                 radius;

    /// If true then calculate normals for created mesh
    bool                generateNormals;
};

//////////////////////////////////////////////////////////////////////////
enum PoissonFusionType
{
    PoissonFusionType_Sharp,
    PoissonFusionType_Smooth,

    PoissonFusionType_ForceDword = 0x7fffffff           ///< Force 32-bit size enum 
};

/// Fill_holes (for PoissonFusion) settles the algorithm to fill holes in the mesh being reconstructed.
enum FillHolesType
{
    /// Automatically fills in all holes in the mesh
    FillHolesType_All,

    /// All holes having radius no greater than the specified in "maxHoleRadius" value will be filled in;
    FillHolesType_ByRadius,

    FillHolesType_ForceDword = 0x7fffffff               ///< Force 32-bit size enum 
};

struct PoissonFusionSettings
{
    /// Scanner type
    base::ScannerType       scannerType;

    /// Fusion type
    PoissonFusionType       fusionType;

    /// Fill holes method type: All or by radius
    FillHolesType           fillType;

    /// Mesh resolution (in millimeters) - step of grid which is used to reconstruct a polygonal model.
    /// Parameter defines the minimal space unit where the polygon of the model will be built in.
    float                   resolution;

    /// Maximum hole radius in millimeters
    float                   maxHoleRadius;

    /// If true than erase small embossings from the surface, where targets were stuck on.
    bool                    removeTargets;

    /// Round type target - black circle diameter (in millimeters)
    float                   targetInnerSize;

    /// Round type target - white circle diameter (in millimeters)
    float                   targetOuterSize;

    /// If true then calculate normals for created mesh
    bool                    generateNormals;

    /// Type of frames, which should be used by the algorithm.
    InputFilter             inputFilterType;
};

//////////////////////////////////////////////////////////////////////////
enum SerialRegistrationType
{
    SerialRegistrationType_Rough,                       ///< Use this registration type for any data. Fast but less accuracy.
    SerialRegistrationType_RoughTextured,               ///< Use this registration type only if all frames have texture. Fast but less accuracy.
    SerialRegistrationType_Fine,                        ///< Use this registration type for any data 
    SerialRegistrationType_FineTextured,                ///< Use this registration type only if all frames have texture.

    SerialRegistrationType_ForceDword = 0x7fffffff      ///< Force 32-bit size enum 
};

struct SerialRegistrationSettings
{
    /// Scanner type
    base::ScannerType       scannerType;

    /// Serial registration type
    SerialRegistrationType  registrationType;
};

//////////////////////////////////////////////////////////////////////////
enum GlobalRegistrationType
{
    GlobalRegistrationType_Geometry,                    ///< Use this registration type for any data 
    GlobalRegistrationType_GeometryAndTexture,          ///< Use this registration type only if all frames have texture

    GlobalRegistrationType_ForceDword = 0x7fffffff      ///< Force 32-bit size enum 
};

struct GlobalRegistrationSettings
{
    /// Scanner type
    base::ScannerType       scannerType;

    /// Global registration type
    GlobalRegistrationType  registrationType;
};

//////////////////////////////////////////////////////////////////////////
enum TexturizeType
{   
    /// Each vertex gets multiple coordinates for each of adjacent triangles, 
    /// final texture coordinates are continuous only for a given triangle area
    TexturizeType_Advanced = 0,
    
    /// Obsolete. Now works the same way as TexturizeType_Advanced.
    TexturizeType_Simple,

    /// Unfold mesh to UV plane, then gather the texture image
    TexturizeType_Atlas,

    /// Keep UV coordinates set, just re-gather the texture image
    TexturizeType_KeepAtlas,

    TexturizeType_ForceDword = 0x7fffffff               ///< Force 32-bit size enum 
};

enum TexturizeResolution
{
    TexturizeResolution_512x512 = 0,
    TexturizeResolution_1024x1024,
    TexturizeResolution_2048x2048,
    TexturizeResolution_4096x4096,
    TexturizeResolution_8192x8192,
    TexturizeResolution_16384x16384,

    TexturizeResolution_ForceDword = 0x7fffffff         ///< Force 32-bit size enum 
};


struct TexturizationSettings
{
    /// Scanner type
    base::ScannerType   scannerType;

    /// Texturize type to use
    TexturizeType       texturizeType;

    /// Texturize output resolution (in pixel)
    TexturizeResolution texturizeResolution;

    /// If true than enable background segmentation for input texture frames
    bool                enableBackgroundSegmentation;

    /// If true then enable compensation of ambient light
    bool                enableAmbientLightingCompensation;
    
    /// Set the limit for number of polygons for mesh unfolding:
    /// 0 - disable simplification (unfold original mesh)
    /// N - reduce number of polygons to N, then make unfolding and re-project atlas to the original mesh
    int                 atlasUnfoldingPolygonLimit;

    /// Interpolate colors for empty texture areas
    bool                enableTextureInpainting;

    /// Correct texture brightness for Artec scanners 
    bool                useTextureNormalization;
    
    /// Type of frames, which should be used by the algorithm
    InputFilter         inputFilterType;
};

//////////////////////////////////////////////////////////////////////////
enum SmallObjectsFilterType
{
    SmallObjectsFilterType_LeaveBiggestObject = 0,      ///< Leave only biggest object
    SmallObjectsFilterType_FilterByThreshold  = 1,      ///< Remove objects that contain the number of 
                                                        ///< triangles is less than the specified
                                                    
    SmallObjectsFilterType_ForceDword = 0x7fffffff      ///< Force 32-bit size enum 
};

struct SmallObjectsFilterSettings
{
    /// Scanner type
    base::ScannerType       scannerType;

    /// Filter type
    SmallObjectsFilterType  filterType;

    /// Threshold - number of triangles 
    int                     filterThreshold;
};

//////////////////////////////////////////////////////////////////////////
enum SimplifyType
{
    SimplifyType_TriangleQuantity,                      ///< Reduce triangle quantity to given number
    SimplifyType_Accuracy,                              ///< Keep simplified mesh accuracy
    SimplifyType_Remesh,                                ///< Minimal acceptable edge length 
    SimplifyType_TriangleQuantityFast,                  ///< Reduce triangle quantity to given number. Very fast but less accuracy.

    SimplifyType_ForceDword = 0x7fffffff                ///< Force 32-bit size enum 
};

enum SimplifyMetric
{
    SimplifyMetric_EdgeLength,                          ///< Reduce triangle quantity to given number
    SimplifyMetric_EdgeLengthAndAngle,                  ///< Keep simplified mesh accuracy
    SimplifyMetric_DistanceToSurface,                   ///< Minimal acceptable edge length 
    SimplifyMetric_DistanceToSurfaceIterative,          ///< Minimal acceptable edge length 

    SimplifyMetric_ForceDword = 0x7fffffff              ///< Force 32-bit size enum 
};

struct MeshSimplificationSettings
{
    /// Scanner type
    base::ScannerType   scannerType;

    /// Simplify type: TriangleQuantity, Accuracy, Remesh, TriangleQuantityFast
    SimplifyType        simplifyType;

    /// Simplify metrics: EdgeLength, DistanceToSurface etc. Not supported for fast simplification.
    SimplifyMetric      simplifyMetrics;

    /// Triangles number after simplification
    int                 triangleNumber;

    /// If true then algorithms won't modify boundary of given surface
    bool                keepBoundary;

    /// Maximal angle between neighbor normals (in degrees). Not supported for fast simplification.
    float               angleThreshold;

    /// Minimal edge length after remesh. Not supported for fast simplification.
    float               remeshEdgeThreshold;

    /// Max error. Not supported for fast simplification.
    float               error;
};

struct FastMeshSimplificationSettings
{
    /// Scanner type
    base::ScannerType   scannerType;

    /// Triangles number after simplification.
    int                 triangleNumber;

    /// If true then Algorithms won't modify boundary of given surface.
    bool                keepBoundary;

    /// Simplification stops if one of the thresholding criteras below are not satisfied.
    bool                enableAdditionalCriteria;

    /// Limit maximal distance between original and simplified meshes.
    bool                enableDistanceThreshold;

    /// Max error (in units^2).
    float               distanceThreshold;

    /// If true then Limit maximal normals deviation.
    bool                enableAngleThreshold;

    /// Maximal angle between neighbor faces normals (in degrees).
    float               angleThreshold;

    /// If true then limit edges length ratio.
    bool                enableAspectRatioThreshold;

    /// Maximal available ratio of edges in triangle.
    float               aspectRatioThreshold;
};

//////////////////////////////////////////////////////////////////////////
struct LoopClosureSettings
{
    /// Scanner type
    base::ScannerType   scannerType;
};

//////////////////////////////////////////////////////////////////////////
struct OutliersRemovalSettings
{
    /// Scanner type
    base::ScannerType   scannerType;

    /// Standard deviation multiplier.
    float               standardDeviationMultiplier;

    /// Marching cube resolution (in millimeters).
    float               resolution;
};

//////////////////////////////////////////////////////////////////////////

extern "C"
{
    /// Check whether the algorithms are available on this machine
    ///  
    /// @retval true if algorithms can be created
    /// @retval false if algorithms creation denied
    bool AALGORITHMSDK_LINK_SPEC
        checkAlgorithmsPermission();

    /// Initializes Fast Fusion algorithm descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeFastFusionSettings( FastFusionSettings* desc, base::ScannerType scannerType );

    /// Initializes Poisson Fusion algorithm descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializePoissonFusionSettings( PoissonFusionSettings* desc, base::ScannerType scannerType );

    /// Initialize texturize algorithm descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeTexturizationSettings( TexturizationSettings* desc, base::ScannerType scannerType );

    /// Initializes small object filter descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeSmallObjectsFilterSettings( SmallObjectsFilterSettings* desc, base::ScannerType scannerType );

    /// Initializes mesh simplification descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeMeshSimplificationSettings( MeshSimplificationSettings* desc, base::ScannerType scannerType, SimplifyType simplifyType );

    /// Initializes fast mesh simplification descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeFastMeshSimplificationSettings( FastMeshSimplificationSettings* desc, base::ScannerType scannerType);

    /// Initializes outliers removal descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeOutliersRemovalSettings( OutliersRemovalSettings* desc, base::ScannerType scannerType );
    

    /// Creates basic fusion algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createFastFusionAlgorithm( IAlgorithm** fusion, const FastFusionSettings* desc );

    /// Creates poisson fusion algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createPoissonFusionAlgorithm( IAlgorithm** fusion, const PoissonFusionSettings* desc );

    /// Creates serial registration algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createSerialRegistrationAlgorithm( IAlgorithm** serialRegistration, const SerialRegistrationSettings* desc );

    /// Creates global registration algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createGlobalRegistrationAlgorithm( IAlgorithm** globalRegistration, const GlobalRegistrationSettings* desc );

    /// Create texturize algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createTexturizationAlgorithm( IAlgorithm** texturizer, const TexturizationSettings* desc);

    /// Creates small objects filter algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createSmallObjectsFilterAlgorithm( IAlgorithm** smallObjectsFilter, const SmallObjectsFilterSettings* desc );

    /// Creates mesh simplification algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createMeshSimplificationAlgorithm( IAlgorithm** meshSimplification, const MeshSimplificationSettings* desc );

    /// Creates fast mesh simplification algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createFastMeshSimplificationAlgorithm( IAlgorithm** meshSimplification, const FastMeshSimplificationSettings* desc );

    /// Creates loop closure algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createLoopClosureAlgorithm( IAlgorithm** loopClosure, const LoopClosureSettings* desc );

    /// Creates outliers removal algorithm
    ErrorCode AALGORITHMSDK_LINK_SPEC
        createOutliersRemovalAlgorithm( IAlgorithm** outliesRemoval, const OutliersRemovalSettings* desc );
}

} } } // namespace artec::sdk::algorithms

#endif // _ALGORITHMS_H_