Binary Clustering API: Difference between revisions

From ADVACAM Wiki
Jump to navigation Jump to search
Line 323: Line 323:
== SetNewClusters…Callback functions ==
== SetNewClusters…Callback functions ==
This are functions that where sets the new cluster callback. There are 2 variants ot the outputs: Clusters parameters list or Cluster list including pixels lists of each cluster. Only one of the callbacks NewClustersCallback or NewClustersWithPixelsCallback can be set. If was set both, only last is working.
This are functions that where sets the new cluster callback. There are 2 variants ot the outputs: Clusters parameters list or Cluster list including pixels lists of each cluster. Only one of the callbacks NewClustersCallback or NewClustersWithPixelsCallback can be set. If was set both, only last is working.
{{ApiBinaryItem
| Nam = pxpClSetNewClustersCallback
| HeSym = ===
| Sum = Callback when new clusters are measured/processed. Provides a statictics about clusters.
| DefH = PXCLAPI int
| DefP = clhandle_t handle, ClNewClustersCallback callback, void* userData
| handle – Clustering instance handle
| callback – The callback function. The ClNewClustersCallback is defined in the clusteringapi.h.
| userData – pointer to data of the user that were set in set callback function
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a CL_ERR_XXX code.
| Not =
| War =
| Exa = void myNewClustersCallback(PXPCluster* clusters, size_t clusterCount, size_t acqIndex, void*
userData) {
    // Do something with the clusters
}
struct {
    int d1;
    int d2;
} usrData = {123, 456};
int rc = pxpClSetNewClustersCallback(myHandle, myNewClustersCallback, (vois*)&usrData);
errorToList("pxpClSetNewClustersCallback", rc);
}}

Revision as of 18:13, 19 December 2023

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

// Using the pxpClGetLastError 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];
			
	pxpClGetLastError(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);
}


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.


SetNewClusters…Callback functions

This are functions that where sets the new cluster callback. There are 2 variants ot the outputs: Clusters parameters list or Cluster list including pixels lists of each cluster. Only one of the callbacks NewClustersCallback or NewClustersWithPixelsCallback can be set. If was set both, only last is working.

pxpClSetNewClustersCallback

Callback when new clusters are measured/processed. Provides a statictics about clusters.
Definition
PXCLAPI int pxpClSetNewClustersCallback(clhandle_t handle, ClNewClustersCallback callback, void* userData);

Parameters

  • handle – Clustering instance handle
  • callback – The callback function. The ClNewClustersCallback is defined in the clusteringapi.h.
  • userData – pointer to data of the user that were set in set callback function
Return value
0 if successful, otherwise the return value is a CL_ERR_XXX code.

Example

void myNewClustersCallback(PXPCluster* clusters, size_t clusterCount, size_t acqIndex, void* 
userData) {
    // Do something with the clusters
}

struct {
    int d1;
    int d2;
} usrData = {123, 456};

int rc = pxpClSetNewClustersCallback(myHandle, myNewClustersCallback, (vois*)&usrData);
errorToList("pxpClSetNewClustersCallback", rc);


Retrieved from "https://wiki.advacam.cz/index.php?title=Binary_Clustering_API&oldid=722"