IScanningProcedure.h

Go to the documentation of this file.

/********************************************************************
*
*   Project     Artec 3D Scanning SDK
*
*   Purpose:    Scanning procedure
*
*   Copyright:  Artec Group
*
********************************************************************/

#ifndef _ISCANNINGPROCEDURE_H_
#define _ISCANNINGPROCEDURE_H_

#include <artec/sdk/base/Errors.h>
#include <artec/sdk/base/IScan.h>
#include <artec/sdk/base/IJob.h>
#include <artec/sdk/base/Rect.h>
#include <artec/sdk/scanning/ScanningSdkDefines.h>

namespace artec { namespace sdk { namespace capturing {
    class IScanner;
} } }

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

class IScanningProcedureObserver;
class IScanningProcedure;

enum ScanningState
{
    ScanningState_Preview,
    ScanningState_Record,
    ScanningState_ContinueRecord,   
    ScanningState_Stop,

    ScanningState_ForceDword = 0x7fffffff /* force 32-bit size enum */
};

enum RegistrationAlgorithmType
{
    RegistrationAlgorithmType_ICP = 0x0,

    /// Texture will be captured automatically 
    RegistrationAlgorithmType_Hybrid = 0x1,
    RegistrationAlgorithmType_Texture = 0x2,

    RegistrationAlgorithmType_ForceDword = 0x7fffffff /* force 32-bit size enum */
};

enum ScanningPipeline
{
    /// Capture frames and reconstruct surfaces
    ScanningPipeline_CaptureOnly          = 0x0,
    
    /// Convert textures from raw to color format
    ScanningPipeline_ConvertTextures      = 0x1,

    /// Normals will be calculated if CaclulateNormals of RegisterFrame flags set
    ScanningPipeline_CalculateNormals     = 0x2,

    /// Map Raw, Half-size or Full-size texture on the mesh
    /// If no texture captured this action is skipped
    ScanningPipeline_MapTexture           = 0x4,

    /// Make frame registration. When enabled, only unsuccessfully registered frames added to scan.
    /// Otherwise all frames added to scan.
    /// Normals will be calculated automatically for this case.
    /// In case of texture or hybrid tracking type texture will be mapped also.
    ScanningPipeline_RegisterFrame        = 0x8,

    /// Detect is captured frame is geometry key frame (skeleton frame). 
    /// If registration unsuccessful or ScanningPipeline_RegisterFrame not set this action is skipped
    ScanningPipeline_FindGeometryKeyFrame = 0x10,

    /// Make only capture while scanning and execute all post-processing later.
    /// Very suitable for scanning with bundle 
    ScanningPipeline_FastCapture          = 0x20,

    ScanningPipelene_ForceDword = 0x7fffffff /* force 32-bit size enum */
};

/// Note. This setting define condition for full-size texture capturing
enum CaptureTextureMethod
{   
    /// Don't capture textures at all
    CaptureTextureMethod_NoTextures,

    /// Capture textures each N-th frame
    CaptureTextureMethod_EveryNFrame,
    
    /// Capture textures only if frame detected as key frame for texturing algorithm
    /// If registration unsuccessful or ScanningPipeline_FindGeometryKeyFrame not set this action is skipped
    CaptureTextureMethod_OnTextureKeyFrame, 
    
    /// Capture textures on each frame
    CaptureTextureMethod_Always,

    CaptureTextureMethod_ForceDword = 0x7fffffff /* force 32-bit size enum */
};

struct ScanningProcedureSettings
{
    /// 0 means no limit, negative values are not valid
    int                         maxFrameCount;          
    
    /// tracking type
    RegistrationAlgorithmType   registrationType;

    /// Combination of ScanningPipeline values
    int                         pipelineConfiguration;  
    
    /// Initial scanning state
    ScanningState               initialState;

    /// Callback interface for captured data processing
    /// For example adding frames for rendering while scanning. Can be NULL
    IScanningProcedureObserver* scanningCallback;

    /// if this flag is true, scanning procedure adds all successfully reconstructed frames to the result scan.
    /// if flag is false, scanning procedure adds only successfully registered frames to the result scan.
    /// flag influences the result only if "ScanningPipeline_RegisterFrame" is enabled.
    bool                        ignoreRegistrationErrors;

    /// How to capture texture from scanner
    CaptureTextureMethod        captureTexture;         
    
    /// How often to capture texture. 
    /// Used for CaptureTextureMethod_EveryNFrame method
    /// If CaptureTextureMethod_EveryNFrame selected, 0 and 1 means capture on every frame,
    /// other values means "capture texture on each N't frame"
    int                         captureTextureFrequency;

    /// This flag indicates that surfaces with reconstruction failures will be added to scan as "empty" ones
    /// It might be useful for texturization algorithm afterwards and to preserve numbering between 
    /// frames of different scans (when scanning with bundle)
    bool                        saveEmptySurfaces;
};

extern "C"
{
    /// Initializes scanning procedure descriptor with defaults settings
    ErrorCode ASCANNINGSDK_LINK_SPEC 
        initializeScanningProcedureSettings(ScanningProcedureSettings* desc);

    ErrorCode ASCANNINGSDK_LINK_SPEC
        createScanningProcedure(IScanningProcedure** job, artec::sdk::capturing::IScanner* scanner, const ScanningProcedureSettings* desc = NULL);
}

/// IScanningProcedure is controler of scanning procedure.
/// This class needs AlgorithmWorkset because the way of its calls is the same as in algorithms.
class IScanningProcedure : public artec::sdk::base::IJob
{
public:
    ///get current scanning event handler
    virtual ScanningState getState() = 0;

    ///set new scanning  event handler
    virtual ErrorCode setState( ScanningState state ) = 0;

    /**
     * Set "improve by neighbor" sensitivity parameter
     * used im mesh reconstruction
     * can be changed while capture in progress
     * @param sensitivity - value between 0.0f and 1.0f
     */
    virtual ErrorCode setSensitivity(float sensitivity) = 0;

    /**
     * Get "improve by neighbor" sensitivity parameter
     * used im mesh reconstruction
     * @return sensitivity - value between 0.0f and 1.0f
     */
    virtual float getSensitivity() = 0;

    /**
     * Update scanning range
     * can be changed while capture in progress
     */
    virtual ErrorCode setScanningRange(float rangeNear, float rangeFar) = 0;

    /**
     * Update scanning range
     * @param rangeNear - near range limit
     * @param rangeFar  - far range limit
     */
    virtual ErrorCode getScanningRange(float* rangeNear, float* rangeFar) = 0;

    /**
     * Update scanning region of interest
     * can be changed while capture in progress
     * call with rect == NULL for disable ROI
     */
    virtual ErrorCode setROI(artec::sdk::base::RectF* rect) = 0;

    /**
     * Get scanning region of interest
     * @param rect - rect to return
     */
    virtual ErrorCode getROI(artec::sdk::base::RectF* rect) = 0;
};

} } } // namespace artec::sdk::scanning

#endif // _ISCANNINGPROCEDURE_H_