Binary Spectral Imaging API

Under construction

• Under construction
• Under construction
• Under construction
• Under construction
• Under construction

Introduction

The SpectraImg is designed for easy working with an energy spectras. It can work with previous saved data using the pxpClReplayData or with physical device using the pxpClStartMeasurement. Measured data will be clusterized, clusters will be will be divided into the required number of channels. Next you can use some frame-generating functions and data will be filtered by applied criteria and converted to pixels on output images. Or use graph-generating functions to generate graphs.

The Spectral imaging API basic workflow

This API is defined in the spectraimgapi.h file.
Typical usage:

Measuring, processing and use of the processed data

1.a Load the Pixet core using pxpSiLoadPixetCore("pxcore.dll");

1.b Or normally start the application using the Pixet core API pxcInitialize function, get the core pointer using pxcGetIPixet(), set the core pointer to the SpectraImg API using pxpSiSetIPixet(iPixet);

2. Get the SpectraImg instance using pxpSiCreate(device_index);

3. Set-up the callbacks (not required).

4. Load device calibration (not required).

5. Set the measurement parameters using the pxpSiSetMeasParams.

6. Set the X-ray fluorescence compensation parameters (not required) pxpSiSetXrfCorrectionParams.

7.a Start the measurement using pxpSiStartMeasurement.

7.b Or replay old data using the pxpSiReplayData function.

8. Wait for measurement and processing is complete (and display the progress) using while-pxpSiIsRunning.

9. Use some get… method and use the processed data.

10. Deinitialize the Pixet core, if the pxcInitialize was used in step 1.

Using BSTG files to save processing time

1. After processing is complete (end of waiting steps above), use the pxpSiSaveToFile(handle, "file.bstg") method.

2. Anytime later use the pxpSiLoadFromFile(handle, "file.bstg").

3. Use the pxpSiGetMeasParams to evaluate measure settings or set it to your program variables or GUI

4. Continue using the data as it was processed. The program now is in the step 9 of the list above.

General functions

LoadPixetCore and UnloadPixetCore

pxpSiLoadPixetCore

---

Loads the pixet core library (pxcore.dll/so). When the measurement with a device is intented the user has to either load pixet core with this function, or if the core is already loaded in the application (pxcore.dll/so was loaded separatelly), the setIPixet function has to be called.

Definition

PXSIAPI int pxpSiLoadPixetCore(const char* pxCoreLibPath);

Parameters

• pxCoreLibPath – path to the pxcore library

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

Example

int rc = pxpSiLoadPixetCore("pxcore.dll");
errorToList("pxpSiLoadPixetCore", rc);

pxpSiUnloadPixetCore

---

Deinitializes ane unloads the Pixet core.

Definition

PXSIAPI void pxpSiUnloadPixetCore();

Parameters

(no pars)

Return value

(void)

SetIPixet and GetIPixet

pxpSiSetIPixet

---

Sets the internal Pixet API pointer. This is used when pxcore library is loaded separatelly in application. The use must pointer obtained via function pxcGetIPixet and should not load the pixet core with pxpSiLoadPixetCore function.

Definition

PXSIAPI void pxpSiSetIPixet(void* pixet);

Parameters

• pixet – The iPixet pointer from the pxcGetIPixet() function of the pxcore API.

Return value

(void)

Example

iPixet = pxcGetIPixet(); // Warning: Use the pxcGetIPixet from pxcapi.h,
                         // not pxpSIGetIPixet from spectraimgapi.h
if (iPixet==0) msgToList("pxcGetIPixet=NULL"); else msgToList("pxcGetIPixet OK");
pxpClSetIPixet(iPixet);

pxpSiGetIPixet

---

Return internal Pixet structure pointer or 0 if not set.

Can be used if you want use functions of the pxcore API if the program was started using pxpSiLoadPixetCore.

Definition

PXSIAPI void* pxpSiGetIPixet();

Parameters

(no pars)

Return value

internal Pixet structure pointer or 0 if failed

Warning

Do not confuse this with the pxcGetIPixet() function of the pxcore API.

Create and Free

pxpSiLoadPixetCore

---

Definition

PXSIAPI sihandle_t pxpSiLoadPixetCore(int deviceIndex=SI_NO_DEVICE);

Parameters

• deviceIndex – index of the device this SpectraImg instance will manage.

If used offline (pxcore library not loaded), use SI_NO_DEVICE. The measurement will be not possible. Only replaying of data.

Return value

the handle of newly create instance of Spectra Imaging, or SI_INVALID_HANDLE if error

Note

If no device present, device with idx 0 is virtual file device. This is second way to offline use.

Example

siHandle = pxpSiCreate(0);
if (siHandle==CL_INVALID_HANDLE) msgToList("pxpSiCreate INVALID");
else msgToList("pxpSiCreate OK");

pxpSiFree

---

Frees the created instance of SpectraImg.

Definition

PXSIAPI int pxpSiFree(sihandle_t handle);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

GetLastError

pxpSiGetLastError

---

Gets the last error message - when a function returns error code. Gets either global message when handle = 0, or message for the specific SpectraImg instance. You can use this function or the message callback.

Definition

PXSIAPI int pxpSiGetLastError(clhandle_t handle, char* errorMsgBuffer, unsigned size);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• errorMsgBuffer – output buffer where the error message will be stored

• size – size of the supplied errorMsgBuffer

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

Example

// Using the pxpSiGetLastError in C++ CLR Windows app
const unsigned	cErrBufSize = 512;
// primary use to show function name, return code, last error message
void errorToList(const char* fName, int rc) {
	char errorMsg[cErrBufSize];
	char cMsg[cErrBufSize];
			
	pxpSiGetLastError(clHandle, errorMsg, cErrBufSize);
	if (rc!=0) {
		sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
	} else {
		sprintf(cMsg, "%s %d err: ---", fName, rc);
	};
	String^ sMsg = gcnew String(cMsg);
	msgToList(sMsg);
}

Load calibration functions and test if calibration loaded

pxpSiLoadCalibrationFromDevice

---

Loads the calibrations from the physically connected device. The device must support this feature. Minipix Tpx3 for example.

Definition

PXSIAPI int pxpSiLoadCalibrationFromDevice(sihandle_t handle);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

pxpSiLoadCalibrationFromFiles

---

Loads the calibration files (a,b,c,t files or a single xml device config file).

Definition

PXSIAPI int pxpSiLoadCalibrationFromFiles(sihandle_t handle, const char* filePaths);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• filePaths – Path to the file(s), variants:

The device xml config file

The four ABCT text files separated by the | symbol.

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

Example

rc = pxpSiLoadCalibrationFromFiles("mydetector.xml");
rc = pxpSiLoadCalibrationFromFiles("calibA.txt|calibB.txt|calibC.txt|calibT.txt");

pxpSiIsCalibrationLoaded

---

Test if calibration is loaded.

Definition

PXSIAPI int pxpSiIsCalibrationLoaded(clhandle_t handle);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate

Return value

Returns > 0 is loaded, = 0 not loaded, < 0 error

Example

int rc = pxpSiIsCalibrationLoaded(si);
if (rc<0) {
    print("pxpSiIsCalibrationLoaded: error %d", rc);
} else if (rc==0) {
    print("pxpSiIsCalibrationLoaded: Not loaded - output will NOT be calibrated (raw ToT values)");
} else {
    print("pxpSiIsCalibrationLoaded: Loaded - output data will be calibrated (keV)");
}

SetMeasParams, GetMeasParams and SetXrfCorrectionParams

pxpSiSetMeasParams

---

Sets the parameters of the future measurement and processing

Definition

PXSIAPI int pxpSiSetMeasParams(clhandle_t handle, int spectFrom, int spectTo, double spectStep, bool maskNoisyPixels, bool doSubPixCorrection, bool correctXrf);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• spectFrom – minimal spectrum energy [keV]

• spectTo – maximal spectrum energy [keV]

• spectStep – Step width in the spectrum [keV] (float, but values significantly <1 may not work correctly).

• maskNoisyPixels – if measuring, periodically checks for noisy pixels and masks them

• doSubPixCorrection – if special filter should be applied to sub pixel images

• correctXrf – if the CdTe sensor internal fluorescence should be corected

Enable (true) or disable (false) XRF correction. Detected XRF energy will replaced by 25 keV.

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

Example

// set-up future spectrum measuring or processing to:
// 500 to 1500 keV with steps 1.25, enable noisy masking and XRF correction
int rc = pxpSiSetMeasParams(si, 500, 1500, 1.25, true, false, true);
errorToList("pxpSiSetMeasParams", rc);

pxpSiGetMeasParams

---

Reads the processing parameters of the data in the SpectraImg instance memory.

(The parameters are pointers to output variables with the some meaning as the pxpSiSetMeasParams parameters)

Usesfull after loading a BSTG file.

Definition

PXSIAPI int pxpSiGetMeasParams(clhandle_t handle, int* spectFrom, int* spectTo, double* spectStep, bool* maskNoisyPixels, bool* doSubPixCorrection, bool* correctXrf);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• *spectFrom – pointer to store minimal spectrum energy [keV]

• *spectTo – pointer to store maximal spectrum energy [keV]

• *spectStep – pointer to store step width in the spectrum [keV] (float, but values significantly <1 may not work correctly).

• *maskNoisyPixels – pointer to store setting if measuring, periodically checks for noisy pixels and masks them

• *doSubPixCorrection – pointer to store setting if special filter should be applied to sub pixel images

• *correctXrf – pointer to store setting if the CdTe sensor internal fluorescence should be corected

Enable (true) or disable (false) XRF correction. Detected XRF energy will replaced by 25 keV.

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

pxpSiSetXrfCorrectionParams

---

Sets the paramaters of the CdTe XRF correction in the future measurement and processing

Definition

PXSIAPI int pxpSiSetXrfCorrectionParams(clhandle_t handlee, double minVol, double maxVol, double toaDiff, bool remove);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• minVol – minimal energy volume of event to be considered as XRF

• maxVol – maximal energy volume of event to be considered as XRF

• toaDiff – maximal toa difference between primary and secondary XRF event

• remove – if XRF events should be removed (true) or assigned to original event (false)

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

StartMeasurement, ReplayData, IsRunning and Abort

pxpSiStartMeasurement

---

Starts measuremnt with the device for specified time and process the data. Only if the SI connected to the device. If calibration is loaded, energy values will be calibrated. Measurement works in the background. Use while pxpSiIsRunning() to wait for end, if need it.

Definition

PXSIAPI int pxpSiStartMeasurement(clhandle_t handle, double acqTime, double measTime, const char* outputFilePath, bool processData);

Parameters

• handle – SpectraImg handle received from function pxpSiCreate
• measTime –

• outptuFilePath –

• processData –

• {{{8}}}

Return value

0 if successful, otherwise the return value is a SI_ERR_XXX code.

Example

errorToList("pxpSiLoadPixetCore", rc);