You are here: Reference Guide > SPIP Plug-in Functions > SPIP Plug In Functions for C++

SPIP Plug-in Functions for C++

Required Interface Functions:

There are two interface functions needed to establish a connection between the SPIP program and a Plug-in function SpipExport and AddToSPIP, and for cleaning up plug-ins containing dialogs an ImCloseAllDialogs should also exist.

void SpipExport()

To inform the SPIP program about the available Plug-in functions a SpipExport() function need to be defined. This function should perform one AddToSPIP call for each Plug-in interface function that shall appear in the SPIP User Prog menu.

void AddToSPIP(char* FunctionName, char* VisibleName, char* GroupName, int ICON);

The AddToSPIP function defines the individual Plug-ins that can be called from the SPIP menu.

The first parameter should be identical to the name of the function to be associated with a menu item (except for Borland compilers where you need to include an underscore in front of the name, e.g., _TiltXUp).

The second parameter is the friendly name that will appear as the menu item text.

The third parameter is the Group Name, which enables you to group the Plug-in functions to different submenus.

The last parameter is reserved for future application of icons.

The user functions which AddToSPIP refers to should be declared with an

extern "C" _declspec(dllexport) compiler directive to make them available for the SPIP program.

for example: extern "C" _declspec(dllexport) int TiltXUp()

The return parameter should be true for success and false for failure.

extern "C" _declspec(dllexport) int ImCloseAllDialogs()

The ImCloseAllDialogs is only required for Plug-ins containing Plug-ins and should contain the necessary code for cleaning up and destroying dialogs.

The CSpipExchange Class:

Exchange of data between the SPIP program and the Plug-in functions are performed through the CSpipExchange class with the methods and variables described below:

CSpipExchange Class Primary Methods:

CSpipExchange::CSpipExchange()

The constructor that will establish a connection to the SPIP program.

float* Get_ImageData();

Retrieve Data from the active SPIP client window (1D or 2D) into a floating-point array. If no active window exists a NULL pointer is returned.

float* Create_ImageData(int sizeX, int sizeY);

Use this function to create your own data independent on existing SPIP windows. A floating-point array of sizeX ´ sizeY elements will be returned if successful otherwise a NULL pointer is returned.

void Show_ImageData(IM_PWIN* Window, _bstr_t Name, int iFlag);

Shows the data in the SPIP client window defined by the Window parameter. If Window is set to NULL a new SPIP window is created and the Window parameter is set to refer to the new window so next time Show_ImageData is called with the same Window parameter the data is shown in that same window.

The Name parameter defines the caption of the data window.

iFlag can be set to IMF_3D indicating that the data should be shown in a 3D view or IMF_SOURCE to show the image in the SPIP source window. These flags will overwrite the function of the Window parameter.

CSpipExchange Class Primary Data Elements:

float *Data;

Floating point pointer to the image or curve data array of the object.

int SizeX; int SizeY;

The number of x pixels and y pixels in the Data array.

int SizeTotal;

The total number of elements in the Data array, equals SizeX x SizeY.

IM_PWIN *pWin;

The SPIP window defined when the data was shown using the Show_ImageData() method.

CSpipExchange Class Get Methods:

_bstr_t Get_Filename();	Get the current filename
int Get_IsForceData();	If the return value is larger than 0 the data are Force Data
intGet_IsVoidPoint(int x, int y, int z);	if larger than zero the point is a void point, for 2D image the z value should be set to zero and for volume images the z value defines the z-plane
_bstr_t Get_Orgfilename();	Get Original filename
float Get_CantileverSensitivity();	Get the Cantilever sensitivity
_bstr_t Get_Desc();	Get the Description
TCHAR Get_FrameDir();	Get the Direction of the image scan (Upwards or Downwards ~ 'u' or 'd')
TCHAR Get_LineDir();	Get the Direction of the line scans (left right ~ 'l' or 'r')
float Get_Max( );	Get the Maximum from the value of the Data array
float Get_Min( );	Get the Minimum from the value of the Data array
float Get_RetraceTime();	Get the Retrace time = time between the end of a line scan and the beginning of the next
float Get_RotationAngle();	Get angle of rotation while scanning the image
float Get_SpringConstant();	Get the Spring Constant of the Cantilever
float Get_TimePerImage();	Get time used for scanning the Image
float Get_TraceTime();	Get Trace time = time for scanning one line
int Get_WordSize();	Get Word size of the Data Array = 4
float Get_XOffset();	Get the X offset for of the physical coordinates used when scanning the image
float Get_XRange();	Get the X Range in the current Xunit
_bstr_t Get_Xunit();	Get the X axis unit
float Get_XYRatio();	Get the XY ratio = SizeX/SizeY
float Get_YOffset();	Get the Y offset for of the physical coordinates used when scanning the image
_bstr_t Get_Yunit();	Get the X axis unit
float Get_YRange();	Get the X Range in the current Yunit
float Get_ZScale();	Get the scaling Z scaling factor to convert to nanometers, normally 1.0
_bstr_t Get_Zunit();	Get the Z axis unit

CSpipExchange Class Put Methods:

void Put_CantileverSensitivity( float newVal)	Put the Cantilever sensitivity
void Put_Desc(_bstr_t cBuf);	Put the description to the object
void Put_Filename(_bstr_t cBuf);	Put filename, also used for running a specific batch process, se below
void Put_IsForceData( int newVal);	Defines if the data is considered as force curve data, so that SPIP will handle the data correctly
void Put_FrameDir( TCHAR newVal);	Put the Direction of the image scan (Upwards or Downwards ~ 'u' or 'd')
void Put_IsVoidPoint( int x, int y, int z, int newVal);	Defines a pixel as being void, for 2D images the z value should be set to zero for volume images the z parameter defines the z-plane
void Put_LineDir( TCHAR newVal);	Put the Direction of scanning a line (left right ~ 'l' or 'r')
void Put_Orgfilename(_bstr_t cBuf);	Put Original filename
void Put_RetraceTime( float newVal);	Put the Retrace time = time between the end of one line scan and the beginning of the next
void Put_RotationAngle( float newVal);	Put angle of rotation for used when scanning the image image
void Put_SpringConstant( float newVal);	Put the Spring Constant of the cantilever related
void Put_TimePerImage( float newVal);	Put the time used for scanning the Image
void Put_TraceTime( float newVal);	Put the Trace time = time for scanning one line
void Put_XOffset( float newVal);	Put X offset for the physical coordinates used when scanning
void Put_XRange( float newVal);	Put the X Range in defined in the actual XUnit
void Put_Xunit(_bstr_t cBuf);	Put the unit for the X axis
void Put_YOffset( float newVal);	Put the Y offset of the physical coordinates used when scanning
void Put_YRange( float newVal);	Put the Y Range in the actual Y Unit YUnit
void Put_Yunit(_bstr_t cBuf);	Put the unit for the Y axis
void Put_ZScale( float newVal);	Put a scaling factor for to be multiplied with the image. Should be 1.0
void Put_Zunit(_bstr_t cBuf);	Put the unit for the Z axis

File Import functions

The important functions to have in mind when constucting a file importer plug-in are:

bool ImFileImport( wchar_t* FileName), which is the function SPIP will be looking for and call in case none of SPIP's own file importers are able to read the file.

bool ImFileImportFirstPriority( wchar_t* FileName) If you want to give your file importer first priority above the internal SPIP file importers you should call it ImFileImportFirstPriority instead of ImFileImport. If the file importer reads the file successfully no other file importers will be called.

void CSpipExchange::Add_ImageDataToInputList(char* pVal)

This function will add images to SPIP's internal list of images and curves found in the file. SPIP will check this list when the plug-in returns, so that they can be displayed in the SPIP program window or the ImageMet Explorer. Note, that an importer plug-in can this way return more images or curves from the same input file.

When SPIP returns a NULL pointer from Get_ImageData() the function shall just provide information about the parameters that can be calculated. This information is defined in the ResultParameterSet structure and provided through the Add_ParameterToResultList function.

Roughness parameter functions

A roughness plug-in is recognized by having a function defined as:

extern "C" _declspec(dllexport) bool ImCalculateParameter( )

This function shall provid parameter information through the Add_ParameterToResultList function:

CSpipExchange::Add_ParameterToResultList(ResultParameterSet &ParameterResult)

This function serves two purposes:

It informs SPIP about the parameters this plug-in can provide
In case a calculation has been performed it should also be used for delivering the parameter value.

The information is provided throgh the ResultParameterSet structure. Currently only the ID, FriendlyName, Unit and Result structure fields are used by SPIP. FriendlyLongName and StandardRef are meant for future use

Working with void pixels

Pixels can be defined as void by setting their value to the maximal floating point value, MAX_FLT, and in this way be treated as invisible, see donut example in the reference guide.

Activating a Batch Process

A batch process can be activated for at plug-in generated or modified image by setting the file name to the name of the batch process file:

b.Put_Filename("Roughness.batch");

b.Put_Orgfilename("TheNameOfTheImage.bcr");

The name of the image will then be defined by the Put_Orgfilename function.

If a batch process is active but you do not want a given image to be processed by the batch sequence you can put "norun" behind the filename as show below:

b.Put_Filename("MyFile.Bcr norun");

b.Put_Filename("norun");

Forcing an image to be shown in the Main Image Window

To force an image to be shown in the Main Image Window put "show_in_main" behind the filename as shown below:

b.Put_Filename("MyFile.Bcr show_in_main");

This might be desirable if the user want to process the image further with the extra processing utilities associated with the Main Image Window.