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 InputFilter
{
    /// Use this type by default
    InputFilter_UseTextureKeyFrames = 0,                ///< Algorithm considers only frames, which have texture key frame attribute
    /// Other types
    InputFilter_UseAllTextures,                         ///< Algorithm considers all frames, which have not empty textures
};

//////////////////////////////////////////////////////////////////////////
struct FastFusionSettings
{
    base::ScannerType   scannerType;                    ///< Scanner type
    float               resolution;                     ///< Mesh resolution (step size)
    int                 radius;                         ///< Averaging radius (in steps) 
    bool                generateNormals;                ///< Calculate normals for created mesh
};

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

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

enum FillHolesType
{
    FillHolesType_All,
    FillHolesType_ByRadius,

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

struct PoissonFusionSettings
{
    base::ScannerType       scannerType;                ///< Scanner type
    PoissonFusionType       fusionType;                 ///< Fusion type
    FillHolesType           fillType;                   ///< Fill holes method type
    float                   resolution;                 ///< Mesh resolution in millimeters
    float                   maxHoleRadius;              ///< Maximum hole radius in millimeters
    bool                    removeTargets;              ///< Remove targets from geometry
    float                   targetInnerSize;            ///< Round type target - black circle diameter
    float                   targetOuterSize;            ///< Round type target - white circle diameter
    bool                    generateNormals;            ///< Calculate normals for created mesh
    InputFilter             inputFilterType;            ///< Type of frames, which should be used by the algorithm
};

//////////////////////////////////////////////////////////////////////////
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
{
    base::ScannerType       scannerType;                ///< Scanner type
    SerialRegistrationType  registrationType;           ///< Serial registration type
};

//////////////////////////////////////////////////////////////////////////
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
{
    base::ScannerType       scannerType;                ///< Scanner type
    GlobalRegistrationType  registrationType;           ///< Global registration type
};

//////////////////////////////////////////////////////////////////////////
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,
    
    TexturizeType_Simple,                               ///< Right angle triangle texture mapping 
    TexturizeType_Atlas,                                ///< Unfold mesh to UV plane, then gather the texture image
    TexturizeType_KeepAtlas,                            ///< Keep UV coordinates set, just re-gather the texture image

    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
{
    base::ScannerType   scannerType;                        ///< Scanner type
    TexturizeType       texturizeType;                      ///< Texturize type to use
    TexturizeResolution texturizeResolution;                ///< Texturize output resolution
    bool                enableBackgroundSegmentation;       ///< Enables background segmentation for input texture frames
    bool                enableAmbientLightingCompensation;  ///< Enable compensation of ambient light
    int                 atlasUnfoldingPolygonLimit;         ///< 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
    bool                enableTextureInpainting;            ///< Interpolate colors for empty texture areas
    bool                useTextureNormalization;            ///< Correct texture brightness for Artec scanners 
    InputFilter         inputFilterType;                    ///< Type of frames, which should be used by the algorithm
};

//////////////////////////////////////////////////////////////////////////
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
{
    base::ScannerType       scannerType;                ///< Scanner type
    SmallObjectsFilterType  filterType;                 ///< Filter type
    int                     filterThreshold;            ///< Threshold - number of triangles 
};

//////////////////////////////////////////////////////////////////////////
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
{
    base::ScannerType   scannerType;                    ///< Scanner type
    SimplifyType        simplifyType;                   ///< Simplify type
    SimplifyMetric      simplifyMetrics;                ///< Simplify metrics. Not supported for fast simplification.
    int                 triangleNumber;                 ///< Triangles number after simplification
    bool                keepBoundary;                   ///< Algorithms won't modify boundary of given surface if true
    float               angleThreshold;                 ///< Maximal angle between neighbor normals (in degrees). Not supported for fast simplification.
    float               remeshEdgeThreshold;            ///< Minimal edge length after remesh. Not supported for fast simplification.
    float               error;                          ///< Max error. Not supported for fast simplification.
};

struct FastMeshSimplificationSettings
{
    base::ScannerType   scannerType;                    ///< Scanner type
    int                 triangleNumber;                 ///< Triangles number after simplification
    bool                keepBoundary;                   ///< Algorithms won't modify boundary of given surface if true

    bool                enableAdditionalCriteria;       ///< Simplification stops if one of the thresholding criteras below are not satisfied
    bool                enableDistanceThreshold;        ///< Limit maximal distance between original and simplified meshes
    float               distanceThreshold;              ///< Max error(in units^2)
    bool                enableAngleThreshold;           ///< Limit maximal normals deviation
    float               angleThreshold;                 ///< Maximal angle between neighbor faces normals (in degrees)
    bool                enableAspectRatioThreshold;     ///< Limit edges length ratio
    float               aspectRatioThreshold;           ///< Maximal available ratio of edges in triangle
};

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

//////////////////////////////////////////////////////////////////////////
struct OutliersRemovalSettings
{
    base::ScannerType   scannerType;                    ///< Scanner type
    float               standardDeviationMultiplier;    ///< Standard deviation multiplier.
    float               resolution;                     ///< Marching cube resolution in mm.
};

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

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 fusion algorithm descriptor with scanner related defaults
    ErrorCode AALGORITHMSDK_LINK_SPEC
        initializeFastFusionSettings( FastFusionSettings* desc, base::ScannerType scannerType );

    /// Initializes 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_