MikroCADSDK.h

Go to the documentation of this file.

/**
* @file MikroCADSDK.h
* @brief MikroCAD SDK interface description
*
* @author LMI Technologies
*/

#ifndef _MikroCADSDK_h
#define _MikroCADSDK_h

#include "MeasurementDefs.h"
#include "MeasProgram.h"
#include "CalibrationExport.h"

#if defined(WIN32)
#  define MC3D_EXPORT __declspec(dllexport)
#else
#  define MC3D_EXPORT    /* nothing */
#endif

#ifdef __cplusplus
extern "C"
{
#endif

/**
If Path with sensor DLLs is different to calling path, the sensor DLL path must be set
@param pszProgramPath   Path with sensor DLLs
*/
MC3D_EXPORT void __cdecl MikroCAD_SetProgramPath(char* pszProgramPath);

/**
Initializes global library. Use only if you use static version of the library.
Call only once and before any other library function.
*/
MC3D_EXPORT void __cdecl MikroCAD_InitializeStaticLib();

/**
Deinitializes global library. Use only if you use static version of the library.
You should call this at application exit in order to cleanup 
all resources left over from API.
AFTER THAT, NO OTHER API FUNCTIONS MUST BE CALLED ANY LONGER!
*/
MC3D_EXPORT void __cdecl MikroCAD_DeinitializeStaticLib();

/**
Returns version infos (no connection with the sensor necessary)
@param dwModuleVersion      Return module version
@param  dwInterfaceVersion  Return module interface version
*/
MC3D_EXPORT void __cdecl MikroCAD_GetModuleVersionInfo(unsigned long& dwModuleVersion, 
  unsigned long& dwInterfaceVersion);

/**
Returns the number of the connected sensor modules
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetNumConnectedSensorModules();


/**
Register a function to be called when a USB communication error happens

@param  funcPtr  Function pointer, use NULL to unregister
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_SetUSBCommErrorHandler(COMM_ERROR funcPtr);


/**
Returns sensor infos of a connected sensor module

@param dwIndex          Index in list
@param dwModuleVersion     Return version of the module (DLL)
@param dwFirmwareVersion   Return firmware version of the sensor
@param dwInterfaceVersion  Return  version of the interface (protocol) to hardware
@param SensorType       Return sensor type ID
@return Success 
*/
MC3D_EXPORT unsigned char __cdecl MikroCAD_GetSensorModuleInfo(
   unsigned long dwIndex,
   unsigned long& dwModuleVersion, 
   unsigned long& dwFirmwareVersion, 
   unsigned long& dwInterfaceVersion, 
   SensorTypeID& SensorType); 


/**
List all available sensors (Before connection with the sensor)

@return Number of listed Sensors
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_ListAllSensors();

/**
Returns the serial number of a listed sensor

@param dwIndex Index in list
@return Serial number
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetSensorSerialNumber(unsigned long dwIndex);

/**
Returns the Sensor type id
*/
MC3D_EXPORT SensorTypeID __cdecl MikroCAD_GetSensorTypeID();


/**
Initialize the measurement module

@param dwSensorNo    Sensor number
@param OperatingMode Operating mode (measurement, simple calibration....)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_Initialize(unsigned long dwSensorNo, SensorOperatingMode 
  OperatingMode = SensorOperatingMode_Measure);

/**
Deinitialize the measurement module
*/
MC3D_EXPORT void __cdecl MikroCAD_Deinitialize();

/**
Is parameter available

@param ParameterID Parameter ID
@return Availability of the parameter (flags)
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_ParameterAvailable(MeasurementParameterID ParameterID);

/**
Write integer parameter

@param ParameterID Parameter ID
@param lParameter Parameter value
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_SetIntegerParameter(MeasurementParameterID ParameterID, long lParameter);

/**
Read integer parameter

@param ParameterID   Parameter ID
@param lParameter Returns the parameter value
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetIntegerParameter(MeasurementParameterID ParameterID, long& lParameter);

/** Read integer parameter limits

@param ParameterID          Parameter ID
@param lMinParameter    Returns the minimum value of the parameter
@param lMaxParameter    Returns the maximum value of the parameter
@return: Error code
*/
MC3D_EXPORT  long __cdecl MikroCAD_GetIntegerParameterLimits(MeasurementParameterID ParameterID, long& lMinParameter,
  long& lMaxParameter);

/**
Write float parameter

@param ParameterID   Parameter ID
@param dParameter Parameter value
return: Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_SetFloatParameter(MeasurementParameterID ParameterID, double dParameter);

/**
Read float parameter

@param ParameterID   Parameter ID
@param dParameter Returns the parameter value
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetFloatParameter(MeasurementParameterID ParameterID, double& dParameter);

/**
Read float parameter limits

@param ParameterID          Parameter ID
@param dMinParameter    Returns the minimum value of the parameter
@param dMaxParameter    Returns the maximum value of the parameter
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetFloatParameterLimits(MeasurementParameterID ParameterID, double& dMinParameter,
  double& dMaxParameter);


/**
Sets the measurement area

@param dSizeX  Measurement area size in X percental to the camera image limits (0.0...1.0)
@param dSizeY  Measurement area size in Y percental to the camera image limits (0.0...1.0)
@param dX0     X-Origin of the area (-1.0...1.0) percental to the camera image limits
@param dY0     Y-Origin of the area (-1.0...1.0) percental to the camera image limits
*/
MC3D_EXPORT void __cdecl MikroCAD_SetMeasurementArea(double dSizeX, double dSizeY, double dX0, double dY0);

/**
Sets the measurement area

@param pbyMeasArea   Measurement area as mask
*/
MC3D_EXPORT void __cdecl MikroCAD_SetMeasurementAreaMask(unsigned char* pbyMeasArea);

/**
Resets the measurement area
*/
MC3D_EXPORT void __cdecl MikroCAD_ResetMeasurementArea();

/** Sets the projection area

@param dSizeX  Projection area size in X percental to the camera image limits (0.0...>1.0)
@param dSizeY  Projection area size in Y percental to the camera image limits (0.0...>1.0)
@param dX0     X-Origin of the area (<-1.0...>1.0) percental to the camera image limits
@param dY0     Y-Origin of the area (<-1.0...>1.0) percental to the camera image limits
*/
MC3D_EXPORT void __cdecl MikroCAD_SetProjectionArea(double dSizeX, double dSizeY, double dX0, double dY0);

/**
Set projection mask

@param pbyMask Projection mask (in camera coordinates)
*/
MC3D_EXPORT void __cdecl MikroCAD_SetProjectionMask(unsigned char* pbyMask);

/**
Resets the projection area
*/
MC3D_EXPORT void __cdecl MikroCAD_ResetProjectionArea();

/**
Gets a camera image (Black / White)

@param pbyImage          Buffer for camera image
@param dwAverage        How many averages?
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetCameraImage8(unsigned char* pbyImage, unsigned long dwAverage = 1);

/**
Gets a camera image in a ROI - 8 bit (Black / White)

@param pbyImage     Buffer for camera image
@param lX0          ROI coordinate X begin 
@param lY0          ROI coordinate Y begin 
@param lX1          ROI coordinate X end 
@param lY1          ROI coordinate Y end 
@param bFullImage   Use full camera image ?
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetCameraImageROI8(unsigned char* pbyImage, long lX0, long lY0, long lX1, 
    long lY1, bool bFullImage = false);

/**
Gets a camera image (Color)

@param pbyImage          Buffer for camera image (Red, green, blue, red, green...)
@param dwAverage        How many averages?
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GetCameraImage24(unsigned char* pbyImage, unsigned long dwAverage = 1);

/**
Projects a gray value (whole image the same color)

@param cValue  Gray value
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectValue(unsigned char cValue);

/**
Projects a color value (whole image the same color)

@param cRed    Red color component
@param cGreen  Green color component
@param cBlue      Blue color component
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectColorValue(unsigned char cRed, unsigned char cGreen, unsigned char cBlue);

/**
Projects a black / white image 

@param pbyImage  Buffer for projector image
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectImage8(unsigned char* pbyImage);

/**
Projects a color image 

@param pbyImage  Buffer for camera image (Red, green, blue, red, green...)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectImage24(unsigned char* pbyImage);

/**
Projects a predefined pattern (cross, ...)

@param nPatternIndex  - 0...NumPattern, 0 - off
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectPattern(short nPatternIndex);

/**
Projects a predefined stripe pattern

@param nPatternIndex  - 0...NumStripePattern, 0 - off
@param bInvers - Inverse ?
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ProjectStripePattern(short nPatternIndex, bool bInvers);

/**
Is projector lamp switch on / off available?

@return Switch available
*/
MC3D_EXPORT bool __cdecl MikroCAD_SwitchOnOffProjectorLampAvailable();

/**
Switch on/off the projector lamp

@param bOn  Projector on (true) or off (false)
*/
MC3D_EXPORT void __cdecl MikroCAD_SwitchOnOffProjectorLamp(bool bOn);

/**
Returns the projector lamp state

@return Lamp state, true if on, otherwise false
*/
MC3D_EXPORT ProjectorLampState __cdecl MikroCAD_GetProjectorLampState();


/**
Returns the number of predefined measurement parameter sets

@return Number of predefined measurement parameter sets
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetNumPredefinedMeasParameterSets();

/**
Returns the name of a predefined measurement parameter sets

@param dwIndex Index in list
@return Parameter set name
*/
MC3D_EXPORT char* __cdecl MikroCAD_GetPredefinedMeasParameterSetName(unsigned long dwIndex);

/**
Selects the current measurement program

@param pszMeasProgName Measurement program name (not case sensitive) - NULL - default program
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_SelectCurrentMeasurementProgram(char* pszMeasProgName = NULL);

/**
Get current measurement program index (< 0 - Default measurement program)

@return Current measurement program index
*/
MC3D_EXPORT long __cdecl MikroCAD_GetCurrentMeasurementProgramIndex();

/**
Get current measurement program ("" - Default measurement program)

@return Current measurement program name
*/
MC3D_EXPORT char* __cdecl MikroCAD_GetCurrentMeasurementProgram();


/**
Which measuring program is identical to the default measuring program

@return Measurement program name or -1, if no measurement program is identical
*/
MC3D_EXPORT char* __cdecl MikroCAD_GetDefaultMeasProgramName();

/**
Start a measurement and lock the data buffer

@param bOnSensor Height image calculation on sensor or sensor DLL if possible. Always true for normal cases, false for development or tests
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_Measure(bool bOnSensor = true);

/**
Returns a pointer to height image data or NULL if not available

@return Pointer to the height image
*/
MC3D_EXPORT short* __cdecl MikroCAD_HeightImagePtr();

/**
Returns a pointer to valid data or NULL if not available

@return Pointer to the valid data
*/
MC3D_EXPORT unsigned char* __cdecl MikroCAD_ValidDataPtr();

/**
Returns a pointer to camera image data (texture) or NULL if not available

@return A pointer to the 24 bit texture image (red, green, blue, red...)
*/
MC3D_EXPORT unsigned char* __cdecl MikroCAD_CameraImagePtr();

/**
Returns a pointer to camera image data (raw data) or NULL if not available

@return A pointer to the 24 bit raw image (red, green, blue, red...) used for texture generation
*/
MC3D_EXPORT unsigned char* __cdecl MikroCAD_CameraRawImagePtr();

/**
Returns a pointer to the power spectrum

@return Pointer to the power spectrum
*/
MC3D_EXPORT short* __cdecl MikroCAD_PowerSpectrumPtr();

/**
Is data buffer locked?

@return True if data buffer is locked, otherwise false
*/
MC3D_EXPORT bool __cdecl MikroCAD_IsDataBufferLocked();

/** 
Unlocks the data buffer
*/
MC3D_EXPORT void __cdecl MikroCAD_UnlockDataBuffer();

/**
Turn pre-filter on or off

@param byUse 0 if not pre-filter should be used, otherwise pre-filter is used 
*/
MC3D_EXPORT void __cdecl MikroCAD_UsePrefilter(unsigned char byUse);

/**
Returns a pointer to the measuring program set object

@return Pointer to measuring program set
*/
MC3D_EXPORT CMeasProgramSet* __cdecl MikroCAD_GetMeasProgramSetPtr();

/**
Reads the configuration

@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ReadConfig();

/**
Writes the configuration

@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_WriteConfig();

/**
Reads the initial parameters from file

@param pszFileName  File name (incl. path)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ReadInitialParameterFromFile(char* pszFileName); 

/**
Writes the initial parameters to file

@param pszFileName  File name (incl. path)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_WriteInitialParameterToFile(char* pszFileName);

/** 
Reads the measurement program data from file

@param pszFileName  File name (incl. path)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ReadMeasProgramDataFromFile(char* pszFileName);

/** 
Writes the measurement program data to file

@param pszFileName  File name (incl. path)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_WriteMeasProgramDataToFile(char* pszFileName);

/**
List all available sensors of a special type (before connection with the sensor)

@param SensorType  Sensor type ID
@return Number of listed Sensors
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_ListAllSensorsType(SensorTypeID SensorType);   

/**
Returns the serial number of a listed sensor of a special type

@param dwIndex Index in list
@return Serial number
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetSensorSerialNumberType(unsigned long dwIndex);

/** 
List all sensor descriptions (only for sensors with separate camera and projector) (Sensor mustn't be initialized!)

@param TypeID  Sensor type ID
@return Number of description items
*/
MC3D_EXPORT long __cdecl MikroCAD_ListSensorDescriptions(SensorTypeID TypeID); 

/**
Reads the sensor description

@param lIndex  Index in list
@return Pointer to sensor description
*/
MC3D_EXPORT TSensorDescription* __cdecl MikroCAD_ReadSensorDescription(long lIndex); 

/** 
Reads the current calibration mode 

@return Current calibration mode (0: no calibration, 1: simple calibration, 2 multi level calibration)
*/
MC3D_EXPORT CalibrationMode __cdecl MikroCAD_GetCurrentCalibrationMode();

/**
Is there any calibration on sensor (Sensor mustn't be initialized)

@param dwSensorNo Sensor number
@param CalMode    Calibration mode
@return True if there is a calibration on the sensor
*/
MC3D_EXPORT bool __cdecl MikroCAD_CalibrationOnSensor(unsigned long dwSensorNo, CalibrationMode CalMode);

/**
Executes a grid calibration

@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GridCalibration();

/**
Executes a plane calibration

@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_PlaneCalibration();

/** 
Gets the number of grove calibrations
*/
MC3D_EXPORT long __cdecl MikroCAD_GetNumGrooveCalibrations();

/**
Executes a groove calibration 

@param lIndex Index (basis calibration - nIndex == 0, additional groove calibration - nIndex == 1..., see also number of groove calibrations)
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_GrooveCalibration(long lIndex);

/** 
Returns the calibration state

@return State flags (SIMPLE_CALIB_STATE_NONE 0, SIMPLE_CALIB_STATE_PLANE 1, SIMPLE_CALIB_STATE_GRID 2, SIMPLE_CALIB_STATE_GROOVE 4)
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetCalibrationState();

/**
Calibration data transfer to sensor

@return Error code
*/
MC3D_EXPORT long  __cdecl MikroCAD_CalibrationToSensor();

/**
Returns a pointer to result data
*/
MC3D_EXPORT short* __cdecl MikroCAD_GetCalibrationResultData();

/**
Get simple calibration parameters buffer size

@return Buffer size in bytes
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetSimpleCalibrationBufferSize();

/**
Load the simple calibration parameters and transfer this in a byte buffer

@param pbyData buffer
@return Success true
*/
MC3D_EXPORT bool __cdecl MikroCAD_GetSimpleCalibrationParameter(unsigned char* pbyData);

/**
Save the simple calibration parameters from a buffer to the scanner
@param pbyData Buffer
@return Success - true
*/
MC3D_EXPORT bool __cdecl MikroCAD_SetSimpleCalibrationParameter(unsigned char* pbyData);

/**
Get multi level calibration parameters buffer size
@return Buffer size in bytes
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetMultiLevelCalibrationBufferSize();

/**
Load the multi level calibration parameters and transfer this in a byte buffer

@param pbyData buffer
@return Success true
*/
MC3D_EXPORT bool __cdecl MikroCAD_GetMultiLevelCalibrationParameter(unsigned char* pbyData);

/**
Unlock the calibration data buffer
*/
MC3D_EXPORT void __cdecl MikroCAD_UnlockCalibrationDataBuffer();

/**
Returns the number of the available event types

@return Number of available event types
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetNumAvailableEventTypes();

/**
Returns the sensor event type 

@param lIndex  Index in event type list
@return Sensor event type or "SensorEventType_None" if not found
*/
MC3D_EXPORT SensorEventType __cdecl MikroCAD_GetEventType(long lIndex);

/**
Registers a event function

@param EventFunc Sensor event function
*/
MC3D_EXPORT void __cdecl MikroCAD_StartSensorEvent(MikroCADEventFunc EventFunc);

/**
Unregisters all event functions
*/
MC3D_EXPORT void __cdecl MikroCAD_StopSensorEvent();

/**
Save the hardware log file to the given file name (file will be overwritten!)

@param filename File name
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_SaveHardwareLogfile(const char *filename);

/** 
List all user data files on scanner (directory)

@param pszMask Directory mask (*.*, ...)
@return Number of items
*/
MC3D_EXPORT long __cdecl MikroCAD_ListUserDataFileDirectory(char* pszMask);

/** 
Return a user data file item from directory

@param lIndex Index in directory
@return Item name or NULL if not exists
*/
MC3D_EXPORT char* __cdecl MikroCAD_GetUserDataFileDirectoryItem(long lIndex);

/** 
User data file item exists ?

@param pszDataFileName Data file name
@return Exists - true
*/
MC3D_EXPORT bool __cdecl MikroCAD_UserDataFileExists(char* pszDataFileName);

/** 
Writes a user data file to the scanner 

@param pszDataFileName Data file name
@param pbyData Data file data
@param dwDataSize Data file size in bytes
@param bOverwriteExist Overwrite if file exists ? (def.: true)
@return Success - true
*/
MC3D_EXPORT bool __cdecl MikroCAD_WriteUserDataFile(char* pszDataFileName, unsigned char* pbyData, unsigned long dwDataSize, 
    bool bOverwriteExist = true);

/** 
Gets the user data file size on the scanner  

@param pszDataFileName Data file name
@return Size in bytes
*/
MC3D_EXPORT unsigned long __cdecl MikroCAD_GetUserDataFileSize(char* pszDataFileName);

/** 
Reads a user data file from the scanner

@param pszDataFileName Data file name
@param pbyData Data file data
@return Success - true
*/
MC3D_EXPORT bool __cdecl MikroCAD_ReadUserDataFile(char* pszDataFileName, unsigned char* pbyData);

/**
Deletes a user data file on the scanner

@param pszDataFileName Data file name
*/
MC3D_EXPORT void __cdecl MikroCAD_DeleteUserDataFile(char* pszDataFileName);

/**
Reset the current settings to factory settings
@param Mode Kind of settings
@return Error code
*/
MC3D_EXPORT long __cdecl MikroCAD_ResetToFactorySettings(ConfigDataTransferMode Mode);

/**
Set user defined parameter set

@param lIndex  Index of the parameter set (0..2, 0 for 1st brightness, 1 for 2nd brightness, 2 for 3rd brightness)
@param lProjectorBrightness Projector brightness
@param lCameraShutter Camera shutter
@param lCameraGain Camera gain
*/
MC3D_EXPORT void __cdecl MikroCAD_SetUserDefinedParameterSet(long lIndex, long lProjectorBrightness,
    long lCameraShutter, long lCameraGain);

/** 
Enable / disable user defined parameter ?

@param bEnabled Parameter set enabled -> true
*/
MC3D_EXPORT void __cdecl MikroCAD_EnableUserDefinedParameterSet(bool bEnabled);

#ifdef __cplusplus
}
#endif

#endif // _MikroCADSDK_h