Binary Clustering API

Under construction

• Warning: This page is under construction

The Clustering API

This API is defined in the clusteringapi.h file.

Typical usage

1.a Load the Pixet core using the pxpClLoadPixetCore("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 Clustering API using pxpClSetIPixet(iPixet);

2. Get the clustering instance handle using pxpClCreate(device_index);

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

4. Load the calibration (not required).

5. Start the measurement or repaly your data.

6. Use the data via one of NewClusters callbacks or from saved clog file.

LoadPixetCore and UnloadPixetCore

pxpClLoadPixetCore

---

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

PXCLAPI int pxpClLoadPixetCore(const char* pxCoreLiPath);

Parameters

• pxCoreLiPath – path to the pxcore library

Return value

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

Example

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

pxpClUnloadPixetCore

---

Deinitializes and unloads the Pixet core.

Definition

PXCLAPI void pxpClUnloadPixetCore();

Parameters

• (no pars)

Return value

(void)

Example

pxpClUnloadPixetCore();

SetIPixet and GetIPixet

pxpClSetIPixet

---

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

PXCLAPI void pxpClSetIPixet(void* pixet);

Parameters

(no pars)

Return value

(void)

Example

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

pxpClGetIPixet

---

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 pxpClLoadPixetCore.

Definition

PXCLAPI void* pxpClGetIPixet();

Parameters

(no pars)

Return value

internal Pixet structure pointer or 0 if not set

Warning

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

Create and Free

pxpClCreate

---

Creates a new instance of clustering.

Definition

PXCLAPI clhandle_t pxpClCreate(int deviceIndex=CL_NO_DEVICE);

Parameters

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

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

Return value

Returns the handle of newly create instance of Spectra Imaging, or CL_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

clHandle = pxpClCreate(0);
if (clHandle==CL_INVALID_HANDLE) msgToList("pxpClCreate INVALID");
else msgToList("pxpClCreate OK");

pxpClFree

---

Frees the created instance of clustering

Definition

PXCLAPI int pxpClFree(clhandle_t handle);

Parameters

• handle – clustering handle

Return value

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

GetLastError

pxpClGetLastError

---

Definition

PXCLAPI int pxpClGetLastError(clhandle_t handle, char* errorMsgBuffer, unsigned size);

Parameters

• handle – clustering 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 CL_ERR_XXX code.

Example

errorToList("pxpClLoadPixetCore", rc);

LoadCalibrationFromDevice and LoadCalibrationFromFiles

pxpClLoadCalibrationFromDevice

---

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

Definition

PXCLAPI int pxpClLoadCalibrationFromDevice(clhandle_t handle);

Parameters

• handle – clustering handle received from function pxpSiCreate

Return value

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

Example

errorToList("pxpClLoadPixetCore", rc);

pxpClLoadCalibrationFromFiles

---

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

Definition

PXCLAPI int pxpClLoadCalibrationFromFiles(clhandle_t handle, const char* filePaths);

Parameters

• handle – clustering 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 CL_ERR_XXX code.

Example

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

StartMeasurement, ReplayData, IsRunning and Abort

pxpClStartMeasurement

---

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

Definition

PXCLAPI int pxpClStartMeasurement(clhandle_t handle, double acqTime, double measTime, const char* outputFilePath);

Parameters

• handle – Clustering instance handle
• acqTime – acquisition time of a single frame / pixel measurement in seconds.

– Primarily intended for frame-based only devices (Medipixes, Timepix, no Tpx3). This is single frame time. Use a short enough time to prevent clusters overlapping. Too short time can cause too many losses between frames.

– On data-driven supporting devices (Timepix3, no Timepix), this is the ToA limit. After exceeds, a ToA is resets and acqIndex in the newClusters... callbacks is incremented. acqTime=measTime can be used.

• measTime – total time of measurement in seconds. Use 0 to endless measurement (progress will always 100%).

• outputFilePath – output file where the process data (clusters) will be saved (*.clog). If saving not required, put "".

Return value

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

Example

// measure for 60 seconds and save the clog.
int rc;
if (devType=="Tpx3") rc = pxpClStartMeasurement(handle, 60, 60, "out-files/test.clog");
else rc = pxpClStartMeasurement(handle, 0.01, 60, "out-files/test.clog");
errorToList("pxpClStartMeasurement", rc);

pxpClReplayData

---

Replays and process already measured data files (*.pmf, *.txt, *.t3r, *.t3pa, ...) and calls the corresponding callbacks. If calibration is loaded, energy values will be calibrated. If the output path defined and ending with .clog, cluster log will be saved.

Definition

PXCLAPI int pxpClReplayData(clhandle_t handle, const char* filePath, const char* outputFilePath, bool blocking);

Parameters

• handle – Clustering instance handle
• filePath – full path to a data file to be replayed

• outputFilePath – output file where the process data (clusters) will be saved (*.clog). If saving not required, put "".

• blocking – whether the function will block until all clusters processed

Return value

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

Clog files note

For historical reasons, there are two CLOG formats. Tpx3 have one additional column. The pxpClReplayData cannot replay CLOG form Tpx3. Use the T3PA instead the CLOG. The T3PA files can be generated by data-driven measuring in the pxcore API.

pxpClIsRunning

---

Returns 1 if running, 0 = not running, < 0 error.

Definition

PXCLAPI int pxpClIsRunning(clhandle_t handle);

Parameters

• handle – Clustering instance handle

Return value

Returns 1 if running, 0 = not running, < 0 error.

pxpClAbort

---

Aborts the measurement or replaying of the data.

Definition

PXCLAPI int pxpClAbort(clhandle_t handle);

Parameters

• handle – Clustering instance handle

Return value

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