ADVACAM Wiki - User contributions [en]

Binary core API

2026-05-06T13:01:31Z

HudecekP: /* Parameter Get/Set functions (using text paramName) */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warnings:'''
* Most parameters are for testing purposes only and you will '''not need them in normal use'''.
* Some parameters '''has variations between revisions''' of devices, firmware versions and Pixet versions.

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 30;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Binary core API

2026-05-06T12:57:21Z

HudecekP: /* Metadata */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 30;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Pixet SDK

2026-05-06T12:37:34Z

HudecekP: /* Python API */

= Overview =
We provide SDK for our products. Currently it has binary and python API.<br>
The SDK packages are available here: https://downloads.advacam.com/sdk.php <br>
Each API contain 3 groups of using type:

== Core/Basic measuring and settings ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)
[[File:Basic-measuring-example.png|frame|none|alt=Basic measuring example|Basic measuring example]]
<br>

== Cluster processing ==
* Searching for clusters in saved data
* Measuring with online searching for clusters
* Getting informations about clusters - Time of arrival, energy, size, ...
[[File:Clustering-example.png|frame|none|alt=Clustering example|Clustering example]]
<br>

== Spectral imaging ==
* Cluster processing with convert each cluster to pixel and create images by spectrum settings
* Getting spectrum information from whole chip, selected rectangle area or from single pixels
* Generating image with subpixel resolution
[[File:SpectralImg-example.png|frame|none|alt=Spectral Imaging examles|Spectral Imaging examles]]<br>

= Binary (C/C++) APIs =
This APIs contains binary libraries, DLLs for Windows and SOs for Linux.<br>
It is intended to be '''easily used from C/C++''', but it is also possible to use it from many other languages, e.g. '''C#''', '''Visual Basic''', '''kotlin''', '''Xojo basic''', can be used in '''Python via ctypes''', if our Pyhon API did not suit you, ... and can be imported to the '''LabView'''.<br>
This API was created as simplified, for ease of use, for example in industry, so it is not object-oriented.<br>
Binary libraries are available in 32 and 64 bit versions for PCs and for ARMs and can be used on PC, RPi and some Android phones<br>
<br>
The libraries are exportes in C style:
* Windows DLLs - extern "C" __declspec(dllexport)
* Linux SOs - extern "C" __attribute__ ((visibility("default")))
<br>
; Download the AdvacamAPIexamples package:
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)
<br>
The binary API has parts:

== Core/basic API ==
With the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)

'''See [[Binary core API ]]'''
<br>

== Clustering API ==
With the '''pxproc library''', designed for searching and processing clusters. Processing is possible online during measurement, or offline by processing data from files.<br>
Files:
* '''clusteringapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Clustering API]]'''
<br>

== Spectral Imaging API ==
Also with the '''pxproc library''', which, after cluster processing, additionally creates frames, where a single pixel is created from each cluster. And energy spectrum graphs can also be easilly generated. From the entire surface or a selected section.<br>
Files:
* '''spectraimgapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Spectral Imaging API ]]'''
<br>

= Python API =
The Python API was created primarily for scientific purposes, so it is quite extensive and fully object-oriented. It can be used either directly using Python installed on the computer or from a small IDE integrated in the Pixet program.<br>
API files list:
* '''pypixet.pyd''' - Basic API file for '''all basic device functions''' like as settings, measuring and get status information.
* '''pypxproc.pyd''' - Pixel processing, used by '''Clustering''' and '''Spectral imaging''' objects.
* '''pypixetgui.pyd''' - API for using the Pixet GUI. Programmer can create windows, dialogs, graphs, ... (Usable only if started from the IDE integrated in the Pixet program).
<br>
This API also using the '''pxcore''' and '''pxproc''' libraries.<br>
'''Note:''' The '''pypxproc''' library are currently '''on demand''', not included in default API package.<br>

'''See [[Python API]]'''<br>

= Auxilliary files =
If you want using some our API, you need an auxilliary files:
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio installed|Directory of minimalistic program using binary API and working on computer with Visual Studio files installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
* The '''pixet.ini file''' located in the directory with the program.
* '''hwlib file(s)''' listed in the pixet.ini.
* '''Drivers for some devices''' properly installed on the computer.
* '''Additional files''' required for some devices. Typically FPGA firmwares. Located in the directory with the program.
* '''system libraries''' used by SDK libraries (pxcore.dll depends on: mfc110.dll, mfcloop.dll, msvcp120.dll, msvcp140.dll, msvcr110.dll, msvcr120.dll, vccorlib140.dll, vcruntime140.dll). This is not needed when the program is running from a development environment, or on a computer where the environment is installed. Don't forget to add the files when exporting for use on another computer.
* '''Device factory configuration XML file(s)''' for individual device. Located by pixet.ini settings, default is the "factory" subdirectory of the program starting directory.
* '''Location for saving the current configuration''', with write enabled. Located by pixet.ini settings, default is the "configs" subdirectory of the program starting directory.
* '''Location for storing log files''', with write enabled. Located by pixet.ini settings, default is the "logs" subdirectory of the program starting directory.

'''Notes:'''
# Devices without proper configuration loaded '''can working, but it measuring strange things'''.<br>
# For simple test You can copy your executable file to the Pixet working directory. But it is better to create a separate directory (directories) for development, to avoid chaos in files.
<br>
'''See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]'''

Pixet SDK

2026-05-06T12:35:13Z

HudecekP: /* Python API */

= Overview =
We provide SDK for our products. Currently it has binary and python API.<br>
The SDK packages are available here: https://downloads.advacam.com/sdk.php <br>
Each API contain 3 groups of using type:

== Core/Basic measuring and settings ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)
[[File:Basic-measuring-example.png|frame|none|alt=Basic measuring example|Basic measuring example]]
<br>

== Cluster processing ==
* Searching for clusters in saved data
* Measuring with online searching for clusters
* Getting informations about clusters - Time of arrival, energy, size, ...
[[File:Clustering-example.png|frame|none|alt=Clustering example|Clustering example]]
<br>

== Spectral imaging ==
* Cluster processing with convert each cluster to pixel and create images by spectrum settings
* Getting spectrum information from whole chip, selected rectangle area or from single pixels
* Generating image with subpixel resolution
[[File:SpectralImg-example.png|frame|none|alt=Spectral Imaging examles|Spectral Imaging examles]]<br>

= Binary (C/C++) APIs =
This APIs contains binary libraries, DLLs for Windows and SOs for Linux.<br>
It is intended to be '''easily used from C/C++''', but it is also possible to use it from many other languages, e.g. '''C#''', '''Visual Basic''', '''kotlin''', '''Xojo basic''', can be used in '''Python via ctypes''', if our Pyhon API did not suit you, ... and can be imported to the '''LabView'''.<br>
This API was created as simplified, for ease of use, for example in industry, so it is not object-oriented.<br>
Binary libraries are available in 32 and 64 bit versions for PCs and for ARMs and can be used on PC, RPi and some Android phones<br>
<br>
The libraries are exportes in C style:
* Windows DLLs - extern "C" __declspec(dllexport)
* Linux SOs - extern "C" __attribute__ ((visibility("default")))
<br>
; Download the AdvacamAPIexamples package:
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)
<br>
The binary API has parts:

== Core/basic API ==
With the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)

'''See [[Binary core API ]]'''
<br>

== Clustering API ==
With the '''pxproc library''', designed for searching and processing clusters. Processing is possible online during measurement, or offline by processing data from files.<br>
Files:
* '''clusteringapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Clustering API]]'''
<br>

== Spectral Imaging API ==
Also with the '''pxproc library''', which, after cluster processing, additionally creates frames, where a single pixel is created from each cluster. And energy spectrum graphs can also be easilly generated. From the entire surface or a selected section.<br>
Files:
* '''spectraimgapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Spectral Imaging API ]]'''
<br>

= Python API =
The Python API was created primarily for scientific purposes, so it is quite extensive and fully object-oriented. It can be used either directly using Python installed on the computer or from a small IDE integrated in the Pixet program.<br>
API files list:
* '''pypixet.pyd''' - Basic API file for '''all basic device functions''' like as settings, measuring and get status information.
* '''pypxproc.pyd''' - Pixel processing, used by '''Clustering''' and '''Spectral imaging''' objects.
* '''pypixetgui.pyd''' - API for using the Pixet GUI. Programmer can create windows, dialogs, graphs, ... (Usable only if started from the IDE integrated in the Pixet program).
'''Note:''' The pxproc library are currently '''on demand''', not included in default API package.<br>
<br>
This API also using the '''pxcore''' and '''pxproc''' libraries.<br>
<br>
'''See [[Python API]]'''<br>

= Auxilliary files =
If you want using some our API, you need an auxilliary files:
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio installed|Directory of minimalistic program using binary API and working on computer with Visual Studio files installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
* The '''pixet.ini file''' located in the directory with the program.
* '''hwlib file(s)''' listed in the pixet.ini.
* '''Drivers for some devices''' properly installed on the computer.
* '''Additional files''' required for some devices. Typically FPGA firmwares. Located in the directory with the program.
* '''system libraries''' used by SDK libraries (pxcore.dll depends on: mfc110.dll, mfcloop.dll, msvcp120.dll, msvcp140.dll, msvcr110.dll, msvcr120.dll, vccorlib140.dll, vcruntime140.dll). This is not needed when the program is running from a development environment, or on a computer where the environment is installed. Don't forget to add the files when exporting for use on another computer.
* '''Device factory configuration XML file(s)''' for individual device. Located by pixet.ini settings, default is the "factory" subdirectory of the program starting directory.
* '''Location for saving the current configuration''', with write enabled. Located by pixet.ini settings, default is the "configs" subdirectory of the program starting directory.
* '''Location for storing log files''', with write enabled. Located by pixet.ini settings, default is the "logs" subdirectory of the program starting directory.

'''Notes:'''
# Devices without proper configuration loaded '''can working, but it measuring strange things'''.<br>
# For simple test You can copy your executable file to the Pixet working directory. But it is better to create a separate directory (directories) for development, to avoid chaos in files.
<br>
'''See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]'''

Pixet SDK

2026-05-06T12:34:23Z

HudecekP: /* Binary (C/C++) APIs */

= Overview =
We provide SDK for our products. Currently it has binary and python API.<br>
The SDK packages are available here: https://downloads.advacam.com/sdk.php <br>
Each API contain 3 groups of using type:

== Core/Basic measuring and settings ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)
[[File:Basic-measuring-example.png|frame|none|alt=Basic measuring example|Basic measuring example]]
<br>

== Cluster processing ==
* Searching for clusters in saved data
* Measuring with online searching for clusters
* Getting informations about clusters - Time of arrival, energy, size, ...
[[File:Clustering-example.png|frame|none|alt=Clustering example|Clustering example]]
<br>

== Spectral imaging ==
* Cluster processing with convert each cluster to pixel and create images by spectrum settings
* Getting spectrum information from whole chip, selected rectangle area or from single pixels
* Generating image with subpixel resolution
[[File:SpectralImg-example.png|frame|none|alt=Spectral Imaging examles|Spectral Imaging examles]]<br>

= Binary (C/C++) APIs =
This APIs contains binary libraries, DLLs for Windows and SOs for Linux.<br>
It is intended to be '''easily used from C/C++''', but it is also possible to use it from many other languages, e.g. '''C#''', '''Visual Basic''', '''kotlin''', '''Xojo basic''', can be used in '''Python via ctypes''', if our Pyhon API did not suit you, ... and can be imported to the '''LabView'''.<br>
This API was created as simplified, for ease of use, for example in industry, so it is not object-oriented.<br>
Binary libraries are available in 32 and 64 bit versions for PCs and for ARMs and can be used on PC, RPi and some Android phones<br>
<br>
The libraries are exportes in C style:
* Windows DLLs - extern "C" __declspec(dllexport)
* Linux SOs - extern "C" __attribute__ ((visibility("default")))
<br>
; Download the AdvacamAPIexamples package:
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)
<br>
The binary API has parts:

== Core/basic API ==
With the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)

'''See [[Binary core API ]]'''
<br>

== Clustering API ==
With the '''pxproc library''', designed for searching and processing clusters. Processing is possible online during measurement, or offline by processing data from files.<br>
Files:
* '''clusteringapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Clustering API]]'''
<br>

== Spectral Imaging API ==
Also with the '''pxproc library''', which, after cluster processing, additionally creates frames, where a single pixel is created from each cluster. And energy spectrum graphs can also be easilly generated. From the entire surface or a selected section.<br>
Files:
* '''spectraimgapi.h''' API header file
* '''pxproc.dll''' or '''pxproc.so''' binary libraries for Windows or Linux
* '''pxproc.lib''' static linging file for easier using on Windows (compile time only)
'''Note:''' These files are currently '''on demand''', not included in default API package.<br>
'''See [[Binary Spectral Imaging API ]]'''
<br>

= Python API =
The Python API was created primarily for scientific purposes, so it is quite extensive and fully object-oriented. It can be used either directly using Python installed on the computer or from a small IDE integrated in the Pixet program.<br>
API files list:
* '''pypixet.pyd''' - Basic API file for '''all basic device functions''' like as settings, measuring and get status information.
* '''pypxproc.pyd''' - Pixel processing, used by '''Clustering''' and '''Spectral imaging''' objects.
* '''pypixetgui.pyd''' - API for using the Pixet GUI. Programmer can create windows, dialogs, graphs, ... (Usable only if started from the IDE integrated in the Pixet program).
<br>
This API also using the '''pxcore''' and '''pxproc''' libraries.<br>
<br>
'''See [[Python API]]'''<br>

= Auxilliary files =
If you want using some our API, you need an auxilliary files:
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio installed|Directory of minimalistic program using binary API and working on computer with Visual Studio files installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
* The '''pixet.ini file''' located in the directory with the program.
* '''hwlib file(s)''' listed in the pixet.ini.
* '''Drivers for some devices''' properly installed on the computer.
* '''Additional files''' required for some devices. Typically FPGA firmwares. Located in the directory with the program.
* '''system libraries''' used by SDK libraries (pxcore.dll depends on: mfc110.dll, mfcloop.dll, msvcp120.dll, msvcp140.dll, msvcr110.dll, msvcr120.dll, vccorlib140.dll, vcruntime140.dll). This is not needed when the program is running from a development environment, or on a computer where the environment is installed. Don't forget to add the files when exporting for use on another computer.
* '''Device factory configuration XML file(s)''' for individual device. Located by pixet.ini settings, default is the "factory" subdirectory of the program starting directory.
* '''Location for saving the current configuration''', with write enabled. Located by pixet.ini settings, default is the "configs" subdirectory of the program starting directory.
* '''Location for storing log files''', with write enabled. Located by pixet.ini settings, default is the "logs" subdirectory of the program starting directory.

'''Notes:'''
# Devices without proper configuration loaded '''can working, but it measuring strange things'''.<br>
# For simple test You can copy your executable file to the Pixet working directory. But it is better to create a separate directory (directories) for development, to avoid chaos in files.
<br>
'''See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]'''

Files and directories of the Pixet and SDK

2026-04-24T15:02:42Z

HudecekP: /* [Plugins] */

= Main directory of the Pixet program =
[[File:Directory-pixet.png|thumb|alt=Pixet main directory if all here|Pixet main directory if all here]]
Here are main program files, binary libraries, API files, licence file and the '''pixet.ini''' file. Here may also be hwlibs subdirectory, special files for some devices. Their location depends on the <nowiki>[Hwlibs]</nowiki> section of the pixet.ini file.<br>
There can also be subdirectories factory, configs and logs. They are there if '''UseAppDataDir''' is disabled in '''pixet.ini''', in the '''<nowiki>[Settings]</nowiki>''' section.<br>
If here are not located configs, inis and logs, this directory can be located in Program files, or in another location where the user cannot normally write.

; Warning
: It may be confusing that this directory contains device ini files, such as zest.ini, dummy.ini, ..., since installation, but if '''UseAppDataDir''' is enabled or '''AppDataDir'''= is set, in pixet.ini, the files located here have no effect on the devices.

= User data directory =
This is location of [[#The factory and the configs subdirectories|configuration]] and [[#logs|log]] files. The program must be able to write here.<br>
This is used, if in the '''[[Files_and_directories_of_the_Pixet_and_SDK#pixet.ini_file|pixet.ini]]''', in the '''<nowiki>[Settings]</nowiki>''' section is located '''UseAppDataDir=true''' (default state).
[[File:Directory-appdata.png|thumb|alt=AppData - user data directory|AppData - user data directory]]
<br>
Default location is in the user's system application data directory, like us:<br>
* '''Windows''' C:\Users\username\AppData\Local\PixetPro
* '''Linux''' ~/.config/PixetPro
* '''MacOS''' ~/Library/Application Support/PixetPro
<br>
; Notes
* Location of the directory can be changed anywhere, using the '''AppDataDir=''' line in the pixet.ini.
* Turning on '''UseAppDataDir''' does not affect the '''factory''' directory. If it is not changed using '''factoryDir=''', it is still expected beside the running program, or in the current directory, if different.

'''See''': [[#pixet.ini file]]

= Subdirectories of the Pixet program =

== The factory and the configs subdirectories ==
The factory directory should contain the factory default configuration XML files.
The Pixet core use it while starting, if the configuration file is not in the configs directory.
The configs directory contain configuration XML files.
The Pixet core try to use it while starting and save the current settings to it, if exiting.<br>
(This process works the same way when you start and quit the Pixet program or if you use C API functions pxcInit/pxcExit or Python API functions pypixet.start() / pixet.exitPixet()+pypixet.exit().)<br>
'''The detector cannot work properly if proper config not loaded'''.<br>
See [[#Configuration XML files]]<br>
<br>
Location of this subdirs can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file.<br>

=== factory ===
It should contain the factory default configuration XML files. The Pixet core use it while starting, if the configuration file is not in the configs directory or if user click the "Load factory config" or scripts can use it by the loadFactoryConfig() method.<br>
Location of this subdir can be in the main program directory or can be located anywhere using the '''FactoryDir=''' line in the pixet.ini file.<br>
Hint: If you frequently do experiments with more instances of Pixet, API-using programs or scripts and have more devices, you can use single location of the factory directory for all.

'''Notes:'''
* Location of this directory '''not affected by''' the '''UseAppDataDir=''' in pixet.ini.
* File '''names must be exact''', for example MiniPIX-D06-W0065.xml, AdvaPIX-C06-W0127-4.xml. It is the complete device name, where all spaces are replaced by minuses. If not exact, a load-factory like functions cannot find it.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

=== configs ===
Contain '''configuration XML files for devices'''. The Pixet core try to use it while starting the Pixet program or in pypixet.start() method in scripts, or if the C API function pxcInit() used. And automatically save the current settings to it, while exitting the Pixet program, or if the pypixet.exit() method is used in scripts, or if the pxcExit() function used via C API.<br>
<br>
In addition, this directory contains:
* '''Configuration XML files for filters''' - name format filtername_DevName ChipID.xml - for example "adaptiveff_MiniPIX D06-W0065.xml"
* '''Configuration INI files for plugins - dev specific''' - name format pluginname_ChipID.ini - for example "devcontrol_D06-W0065.ini"
* '''Configuration INI files for plugins''' - name format pluginname.ini - for example "pyscripting.ini"

Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''ConfigsDir=''' line in the pixet.ini file.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== logs ==
[[File:Directory-logs.png|thumb|alt=The logs directory|The logs directory]]
Here are log files from all hardware libraries, pixet core. Files are from last Pixet core run. While next run, the core archive last log files. Subdirectories logs1, logs2, ... contains backups for last 10 sessions.<br>
Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''LogsDir=''' line in the pixet.ini file.

* Main log file is the '''log.log'''. This is the main log of the Pixet core.
:: You can see here the attempts to load hwlibs, whether any device was found, whether hwlib was able to start, load the configuration, ...
* Hwlib logs are named by each hwlib, eq. '''minipix.log'''.
:: You can see here the hwlib messages. It contains detected device names, serial numbers and types.
* Device logs are named by hwlib and each device, eq. '''minipixtpx3_0144 A.log'''.
:: Here are the low-level informations. It can be helpful for our Technical support if the device is naughty.
* The '''runtime.log'''.
:: Simple list of init/exit times of the Pixet core.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== hwlibs ==
This is the usual place for hwlib libraries, designed to work with different types of devices. The actual location of the files is defined in the <nowiki>[hwlibs]</nowiki> section of the pixet.ini file. Default is the hwlibs subdirectory of the main program running directory. But here are a simple relative paths from the main program location and can be configured without subdirectory. It is commonly used in single-purpose programs using API.<br>
'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Hwlibs]</nowiki> section

== plugins ==
Default location of plugins to the Pixet program.<br>
Warning: Some plugins can be need for API too.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Plugins]</nowiki> section

== drivers ==
Installators of drivers for some devices.

== libs ==
Libraries for Python scripting plugin.

== scripts ==
* Sample scripts for using Python scripting plugin.
* The default place to search for imports used in scripts run from the Python scripting plugin.

== Other subdirs ==
* samples - Sample data for demo when using virtual file device.
* help - PDF manuals
* platforms, styles - System directories of QT.

= Main directory of the API-using programs, independent on the Pixet =
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio files installed|Directory of minimalistic program using binary API and working on computer with Visual Studio installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
User can write programs using our API. To operate them, need:
* '''Pixet core library''' - The core of the Pixet program. '''pxcore.dll''', or pxcore.so file.
* '''Pixel processing library''' - '''pxproc.dll''' or pxproc.so library - only for Clustering and Spectral imaging use
* '''Static linking libraries''' - To compile binary programs on Windows, user need the pxcore.lib (and pxproc.lib). Only in compile time. Compiler must be setup for using it.
* '''Auxilliary libraries of system''' - If program must working on computer without an IDE installed, can need some auxilliary libs, like as: msvcp140.dll, vcruntime140.dll, etc
* '''pixet.ini''' - configuration for the Pixet core. See [[#pixet.ini file]]
* '''HWlibs''' for the given hardware (and firmwares if devices need). See [[#hwlibs]] and [[#Device firmware files]]
* '''Device configuration files''' in the '''factory''' and '''configs''' directories, or elsewhere according to the settings in pixet.ini. See [[#The factory and the configs subdirectories]]
* '''Place for logs''' in the '''logs''' directory, or elsewhere according to the settings in pixet.ini. See [[#logs]]
* '''Python interface''' - To run Python scripts, '''pypixet.pyd''' is needed in addition. And a '''pypxproc.pyd''' for Clustering and Spectral imaging objects.<br>
<br>
Basic files are in the API packages:
{{APIpackages}}

Alternatives to run the API using programs:
# Copy all need files to the Project directory.
# While running the program, change the operating directory to the Pixet main directory.
# Copy the binary executable or python script to the Pixet main directory and run it from here. Useful for occasional single test, but can do problems in more extensive cases.

= Special files =

=== Configuration XML files ===
The config file contains all detector settings and you can start and continue with the settings as it was while last program exit. The factory config is config saved afther low-level detector setup, finding of bad pixels, calibrations and other factory tests.<br>
<br>
'''Notes:'''
* '''The detector cannot work properly if proper config not loaded'''.
* The files must have proper names. “WidePIX-B04-W0535-10.xml” for example. If not, automatic load at start will not work. To optain proper config name, you can do the program exit and see saved filename in the configs directory.
'''See:'''
* [[#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>

== pixet.ini file ==
This is the main configuration file of the Pixet core. It has several sections beginning with a title in square brackets. Sections contain configuration lines formated as '''Name=value''' or '''Name=''' for default value. They can also contain comments, which start with a semicolon. This way you can also deactivate some configuration lines.<br>
Default version of the file conaining used options and all remaining options disabled + with =default. User can edit it and enable.<br>
<br>
'''Warning:'''<br>
Up to release 1.8.3 the [Hwlibs] section contains lines without the = symbol. This is not compliant with the INI standard. '''The file format will change''' soon. From the next version all data lines will starts with the name=.<br>
<br>
The default '''path where Pixet core looks for the pixet.ini''' file is the same as the path to the program that started the pxcore library. So the file should be next to it. Attention, '''all other paths''' are relative to the current directory, not to the position of the program.<br>
So if you run c:\program files\pixet\pixet.exe from c:\users\myname, pxcore will try to load c:\program files\pixet\pixet.ini and all other relative paths (including those listed in the pixet.ini) will start with c:\users\myname.

=== <nowiki>[Settings]</nowiki> ===
General settings of used directories, core and the Pixet program parameters:
* '''UseAppDataDir''' UseAppDataDir=true - Change default location of the configs and logs subdirs and ini files to the user data directory. It also allows different login users to have different settings of same devices in same programs.
: Note: This does not affects the factory directory.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIniInAppDataDir''' PixetIniInAppDataDir=true - Enable reading the pixet.ini file from the user data directory. Very usesful if the program is located in the Program files or at other location with no write rights. It also allows different users to have different pixet.ini. Note: Enabling this option means that the Pixet core first loads this file (from the program launch point) and, after detecting this option, loads it again from the user data directory. Other settings in the default pixet.ini are therefore ignored.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIni''' PixetIni=C:\myPixetAppData\myPixetIni1.ini - Change name and location of the pixet.ini file. Similar to the case of PixetIniInAppDataDir, when using PixetIni=, the initialization file will be loaded again and the contents of the original file will not affect the further operation of the software.
* '''AppDataDir''' AppDataDir=C:\myPixetAppData\group1 - Change location of the user data directory to specified path. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings.
* '''ConfigsDir''' ConfigsDir=C:\myPixetAppData\configsGroup1 - Change location od the configs dir to other location. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings of devices.
* '''FactoryDir''' FactoryDir=C:\myPixetAppData\factory - Change location od the factory dir to other location. Useful if user have many independent places of a programs, creating new programs and testing new devices. User can simply store all factory files in one location. Or it is possible to have such a directory on the company server, where users do not have the right to write.
* '''LogsDir''' LogsDir=C:\temp\pxCoreDebug - Change location of the logs directory. Useful if user have many independent places of a programs, typically if creating new programs. User can simply collect all logs to one directory so that he does not have to open another one every time.
* '''Splash''' Splash=true - Use a splash screen when the Pixet program starting. It does not affect programs using the API.
* '''FileDevice''' FileDevice=true - Enable virtual "file device" independent if physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''FileDeviceWhenNoDevs''' = FileDeviceWhenNoDevs=false - Disable virtual "file device" if no physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''SaveSettings''' SaveSettings=false - Disable automatic save device settings on exit pixet core. It affects Pixet as well as programs that use the API.
* '''MaxFrameMemory''' MaxFrameMemory=1024 - Change the frame memory limit for multiframe acquisitions. Reserved for future use, currently not used.
* '''MainUi''' MainUi=devcontrol - Change main user interface plugin of the Pixet program. User can programm your own plugins and one can be used instead of the Pixet main window.
* '''LogLeaveOldLogs''' LogLeaveOldLogs=false - Disable archiving old log files sets.
* '''LogRotateCount''' LogRotateCount=15 - Change number of archived log directories.
* '''HighDPI''' HighDPI=true - Enable AA_EnableHighDpiScaling feature in QT GUI environment. Disable can work only in very old versions of Pixet. Currently is deprecated and allways on.

=== <nowiki>[Hwlibs]</nowiki> ===
List of hardware library files/paths used in startup to search and connect a devices. See the hwlibs subdirectory description for details.<br>
'''Examples:''' Left is default Pixet configuration with hwlib files in the hwlibs subdirectory, right is simple arrangement with files in the program directory. Last line is disabled in both versions.
{|
|-
|colspan=2|    '''Hwlibs section example (dirs/flat structure)'''
|    
|colspan=2|    '''Hwlibs section (old format, before 2025/09)'''
|-
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
Hwlib=hwlibs\minipix.dll
Hwlib=hwlibs\widepix.dll
Hwlib=hwlibs\zem.dll
;Hwlib=hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
Hwlib=minipix.dll
Hwlib=widepix.dll
Hwlib=zem.dll
;Hwlib=zest.dll
</syntaxhighlight>
|          
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlibs\minipix.dll
hwlibs\widepix.dll
hwlibs\zem.dll
;hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
minipix.dll
widepix.dll
zem.dll
;zest.dll
</syntaxhighlight>
|}

User can disable some hwlibs using the ; symbol.<br><br>

'''Warning:'''
* The '''Hwlib=''' must be exactly Hwlib=, it '''case sensitive'''
<br>

'''List of HWLIB files:''' Windows / Linux
* '''Minipix''': minipix.dll / minipix.so
* '''Widepix with Eth''': zest.dll / zest.so
* '''Widepix with USB2''': widepix.dll / widepix.so
* '''Advapix''' or '''Widepix with USB3''': zem.dll (and aux. file okFrontPanel.dll - allways in the program directory) / zem.so + okFrontPanel.so
* '''Advapix new''': abrd-hwlib.dll / abrd-hwlib.so
* And customer-specific files for motor driving, x-ray sources, etc.

=== <nowiki>[Plugins]</nowiki> ===
List of Pixet plugins files/paths. All files is by default in the plugins subdirectory.
; Note
: Some plugins are not only for GUI Pixet
: Accessing specific files like as '''HDF5''', '''TIFF'''
: These plugins are also needed when using an API.

'''Warning:'''
* The Plugin= must be exactly Plugin=, it case sensitive

=== <nowiki>[PixelmanPlugins]</nowiki> ===
List of Pixet plugins files/paths with backward compatibility for old Pixelman program.<br>
'''Warning:'''<br>
This is very obsolette. Support for Pixelman related stuff (this ini section, file formats, etc) '''will be removed soon''' without replacement.

== Device configuration ini files ==
Some devices can has configuration file. Theese files are located in the program main directory or in the user data directory if the UseAppDataDir=true option used. Files have names identical to the names of the corresponding HWlibs, ending with .ini. For example, the Ethernet Widepix uses HWlib zest.dll (or zest.so on Linux) and the configuration is stored in zest.ini.<br>

There is usually no need to edit these files, you can find details about them in the device's manual.<br>

Only for network devices it is sometimes useful to define IP addresses on which Pixet core should search for devices. Either because the general search does not work on the given network, or so that the program does not "steal" a device in another room.
For example, in zest.ini, each device can has its own section and an IP address defined in it:
<syntaxhighlight line lang=ini>
[Device0]
IP=10.10.1.30

[Device1]
IP=10.10.1.31
</syntaxhighlight>

== Device firmware files ==
Some devices need firmware files to upload while initialization process. These files are allways located in the program directory. Names are typically composed from HWlib name and readout chip name (zemtpx3.rbf for example).<br>
List of this kind of files:<br>
zestwpx.bit, zemwpxf.rbf, zemtpx3.rbf, zemtpx3quad.rbf, zemtpx.rbf, cyptpx3pix.rbf<br>
Note: The standard Pixet distribution that comes with your device only contains the files for that device, so you usually won't see all of these files. And Minipix, for example, doesn't need any of it.

== Insidious complications with files/dirs ==
Let's have the following program and with it pypixet.pyd and other necessary files:
<syntaxhighlight lang="python" line>
import os
os.chdir("test-output")
import pypixet

print("pixet core init...")
pypixet.start()
pixet=pypixet.pixet
devices = pixet.devices()
dev = devices[0]

print("dev.doSimpleAcquisition (3 frames @ 1 sec) - start")
rc = dev.doSimpleAcquisition(3, 1, pixet.PX_FTYPE_AUTODETECT, "example.png")
print("dev.doSimpleAcquisition - end:", rc, "(0 is OK)")

pixet.exitPixet()
pypixet.exit()
</syntaxhighlight>
This program normally works with e.g. Minipix, but does not work with e.q. Advapix. Crashes at pypixet.start() or has not any detected devices.<br>
<br>
The problem is that hwlibs load their files eg firmware from the current directory. Minipix not need any other files, Advapix need a firmware .rbf file. Moving '''os.chdir''' after '''pypixet.start()''' solves the problem.

= Related =
* [[Pixet_SDK|Pixet SDK overview]]
* [[PIXet|The PIXet program]]
* [[File types]]

Files and directories of the Pixet and SDK

2026-04-24T14:08:51Z

HudecekP: /* [Hwlibs] */

= Main directory of the Pixet program =
[[File:Directory-pixet.png|thumb|alt=Pixet main directory if all here|Pixet main directory if all here]]
Here are main program files, binary libraries, API files, licence file and the '''pixet.ini''' file. Here may also be hwlibs subdirectory, special files for some devices. Their location depends on the <nowiki>[Hwlibs]</nowiki> section of the pixet.ini file.<br>
There can also be subdirectories factory, configs and logs. They are there if '''UseAppDataDir''' is disabled in '''pixet.ini''', in the '''<nowiki>[Settings]</nowiki>''' section.<br>
If here are not located configs, inis and logs, this directory can be located in Program files, or in another location where the user cannot normally write.

; Warning
: It may be confusing that this directory contains device ini files, such as zest.ini, dummy.ini, ..., since installation, but if '''UseAppDataDir''' is enabled or '''AppDataDir'''= is set, in pixet.ini, the files located here have no effect on the devices.

= User data directory =
This is location of [[#The factory and the configs subdirectories|configuration]] and [[#logs|log]] files. The program must be able to write here.<br>
This is used, if in the '''[[Files_and_directories_of_the_Pixet_and_SDK#pixet.ini_file|pixet.ini]]''', in the '''<nowiki>[Settings]</nowiki>''' section is located '''UseAppDataDir=true''' (default state).
[[File:Directory-appdata.png|thumb|alt=AppData - user data directory|AppData - user data directory]]
<br>
Default location is in the user's system application data directory, like us:<br>
* '''Windows''' C:\Users\username\AppData\Local\PixetPro
* '''Linux''' ~/.config/PixetPro
* '''MacOS''' ~/Library/Application Support/PixetPro
<br>
; Notes
* Location of the directory can be changed anywhere, using the '''AppDataDir=''' line in the pixet.ini.
* Turning on '''UseAppDataDir''' does not affect the '''factory''' directory. If it is not changed using '''factoryDir=''', it is still expected beside the running program, or in the current directory, if different.

'''See''': [[#pixet.ini file]]

= Subdirectories of the Pixet program =

== The factory and the configs subdirectories ==
The factory directory should contain the factory default configuration XML files.
The Pixet core use it while starting, if the configuration file is not in the configs directory.
The configs directory contain configuration XML files.
The Pixet core try to use it while starting and save the current settings to it, if exiting.<br>
(This process works the same way when you start and quit the Pixet program or if you use C API functions pxcInit/pxcExit or Python API functions pypixet.start() / pixet.exitPixet()+pypixet.exit().)<br>
'''The detector cannot work properly if proper config not loaded'''.<br>
See [[#Configuration XML files]]<br>
<br>
Location of this subdirs can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file.<br>

=== factory ===
It should contain the factory default configuration XML files. The Pixet core use it while starting, if the configuration file is not in the configs directory or if user click the "Load factory config" or scripts can use it by the loadFactoryConfig() method.<br>
Location of this subdir can be in the main program directory or can be located anywhere using the '''FactoryDir=''' line in the pixet.ini file.<br>
Hint: If you frequently do experiments with more instances of Pixet, API-using programs or scripts and have more devices, you can use single location of the factory directory for all.

'''Notes:'''
* Location of this directory '''not affected by''' the '''UseAppDataDir=''' in pixet.ini.
* File '''names must be exact''', for example MiniPIX-D06-W0065.xml, AdvaPIX-C06-W0127-4.xml. It is the complete device name, where all spaces are replaced by minuses. If not exact, a load-factory like functions cannot find it.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

=== configs ===
Contain '''configuration XML files for devices'''. The Pixet core try to use it while starting the Pixet program or in pypixet.start() method in scripts, or if the C API function pxcInit() used. And automatically save the current settings to it, while exitting the Pixet program, or if the pypixet.exit() method is used in scripts, or if the pxcExit() function used via C API.<br>
<br>
In addition, this directory contains:
* '''Configuration XML files for filters''' - name format filtername_DevName ChipID.xml - for example "adaptiveff_MiniPIX D06-W0065.xml"
* '''Configuration INI files for plugins - dev specific''' - name format pluginname_ChipID.ini - for example "devcontrol_D06-W0065.ini"
* '''Configuration INI files for plugins''' - name format pluginname.ini - for example "pyscripting.ini"

Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''ConfigsDir=''' line in the pixet.ini file.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== logs ==
[[File:Directory-logs.png|thumb|alt=The logs directory|The logs directory]]
Here are log files from all hardware libraries, pixet core. Files are from last Pixet core run. While next run, the core archive last log files. Subdirectories logs1, logs2, ... contains backups for last 10 sessions.<br>
Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''LogsDir=''' line in the pixet.ini file.

* Main log file is the '''log.log'''. This is the main log of the Pixet core.
:: You can see here the attempts to load hwlibs, whether any device was found, whether hwlib was able to start, load the configuration, ...
* Hwlib logs are named by each hwlib, eq. '''minipix.log'''.
:: You can see here the hwlib messages. It contains detected device names, serial numbers and types.
* Device logs are named by hwlib and each device, eq. '''minipixtpx3_0144 A.log'''.
:: Here are the low-level informations. It can be helpful for our Technical support if the device is naughty.
* The '''runtime.log'''.
:: Simple list of init/exit times of the Pixet core.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== hwlibs ==
This is the usual place for hwlib libraries, designed to work with different types of devices. The actual location of the files is defined in the <nowiki>[hwlibs]</nowiki> section of the pixet.ini file. Default is the hwlibs subdirectory of the main program running directory. But here are a simple relative paths from the main program location and can be configured without subdirectory. It is commonly used in single-purpose programs using API.<br>
'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Hwlibs]</nowiki> section

== plugins ==
Default location of plugins to the Pixet program.<br>
Warning: Some plugins can be need for API too.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Plugins]</nowiki> section

== drivers ==
Installators of drivers for some devices.

== libs ==
Libraries for Python scripting plugin.

== scripts ==
* Sample scripts for using Python scripting plugin.
* The default place to search for imports used in scripts run from the Python scripting plugin.

== Other subdirs ==
* samples - Sample data for demo when using virtual file device.
* help - PDF manuals
* platforms, styles - System directories of QT.

= Main directory of the API-using programs, independent on the Pixet =
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio files installed|Directory of minimalistic program using binary API and working on computer with Visual Studio installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
User can write programs using our API. To operate them, need:
* '''Pixet core library''' - The core of the Pixet program. '''pxcore.dll''', or pxcore.so file.
* '''Pixel processing library''' - '''pxproc.dll''' or pxproc.so library - only for Clustering and Spectral imaging use
* '''Static linking libraries''' - To compile binary programs on Windows, user need the pxcore.lib (and pxproc.lib). Only in compile time. Compiler must be setup for using it.
* '''Auxilliary libraries of system''' - If program must working on computer without an IDE installed, can need some auxilliary libs, like as: msvcp140.dll, vcruntime140.dll, etc
* '''pixet.ini''' - configuration for the Pixet core. See [[#pixet.ini file]]
* '''HWlibs''' for the given hardware (and firmwares if devices need). See [[#hwlibs]] and [[#Device firmware files]]
* '''Device configuration files''' in the '''factory''' and '''configs''' directories, or elsewhere according to the settings in pixet.ini. See [[#The factory and the configs subdirectories]]
* '''Place for logs''' in the '''logs''' directory, or elsewhere according to the settings in pixet.ini. See [[#logs]]
* '''Python interface''' - To run Python scripts, '''pypixet.pyd''' is needed in addition. And a '''pypxproc.pyd''' for Clustering and Spectral imaging objects.<br>
<br>
Basic files are in the API packages:
{{APIpackages}}

Alternatives to run the API using programs:
# Copy all need files to the Project directory.
# While running the program, change the operating directory to the Pixet main directory.
# Copy the binary executable or python script to the Pixet main directory and run it from here. Useful for occasional single test, but can do problems in more extensive cases.

= Special files =

=== Configuration XML files ===
The config file contains all detector settings and you can start and continue with the settings as it was while last program exit. The factory config is config saved afther low-level detector setup, finding of bad pixels, calibrations and other factory tests.<br>
<br>
'''Notes:'''
* '''The detector cannot work properly if proper config not loaded'''.
* The files must have proper names. “WidePIX-B04-W0535-10.xml” for example. If not, automatic load at start will not work. To optain proper config name, you can do the program exit and see saved filename in the configs directory.
'''See:'''
* [[#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>

== pixet.ini file ==
This is the main configuration file of the Pixet core. It has several sections beginning with a title in square brackets. Sections contain configuration lines formated as '''Name=value''' or '''Name=''' for default value. They can also contain comments, which start with a semicolon. This way you can also deactivate some configuration lines.<br>
Default version of the file conaining used options and all remaining options disabled + with =default. User can edit it and enable.<br>
<br>
'''Warning:'''<br>
Up to release 1.8.3 the [Hwlibs] section contains lines without the = symbol. This is not compliant with the INI standard. '''The file format will change''' soon. From the next version all data lines will starts with the name=.<br>
<br>
The default '''path where Pixet core looks for the pixet.ini''' file is the same as the path to the program that started the pxcore library. So the file should be next to it. Attention, '''all other paths''' are relative to the current directory, not to the position of the program.<br>
So if you run c:\program files\pixet\pixet.exe from c:\users\myname, pxcore will try to load c:\program files\pixet\pixet.ini and all other relative paths (including those listed in the pixet.ini) will start with c:\users\myname.

=== <nowiki>[Settings]</nowiki> ===
General settings of used directories, core and the Pixet program parameters:
* '''UseAppDataDir''' UseAppDataDir=true - Change default location of the configs and logs subdirs and ini files to the user data directory. It also allows different login users to have different settings of same devices in same programs.
: Note: This does not affects the factory directory.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIniInAppDataDir''' PixetIniInAppDataDir=true - Enable reading the pixet.ini file from the user data directory. Very usesful if the program is located in the Program files or at other location with no write rights. It also allows different users to have different pixet.ini. Note: Enabling this option means that the Pixet core first loads this file (from the program launch point) and, after detecting this option, loads it again from the user data directory. Other settings in the default pixet.ini are therefore ignored.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIni''' PixetIni=C:\myPixetAppData\myPixetIni1.ini - Change name and location of the pixet.ini file. Similar to the case of PixetIniInAppDataDir, when using PixetIni=, the initialization file will be loaded again and the contents of the original file will not affect the further operation of the software.
* '''AppDataDir''' AppDataDir=C:\myPixetAppData\group1 - Change location of the user data directory to specified path. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings.
* '''ConfigsDir''' ConfigsDir=C:\myPixetAppData\configsGroup1 - Change location od the configs dir to other location. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings of devices.
* '''FactoryDir''' FactoryDir=C:\myPixetAppData\factory - Change location od the factory dir to other location. Useful if user have many independent places of a programs, creating new programs and testing new devices. User can simply store all factory files in one location. Or it is possible to have such a directory on the company server, where users do not have the right to write.
* '''LogsDir''' LogsDir=C:\temp\pxCoreDebug - Change location of the logs directory. Useful if user have many independent places of a programs, typically if creating new programs. User can simply collect all logs to one directory so that he does not have to open another one every time.
* '''Splash''' Splash=true - Use a splash screen when the Pixet program starting. It does not affect programs using the API.
* '''FileDevice''' FileDevice=true - Enable virtual "file device" independent if physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''FileDeviceWhenNoDevs''' = FileDeviceWhenNoDevs=false - Disable virtual "file device" if no physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''SaveSettings''' SaveSettings=false - Disable automatic save device settings on exit pixet core. It affects Pixet as well as programs that use the API.
* '''MaxFrameMemory''' MaxFrameMemory=1024 - Change the frame memory limit for multiframe acquisitions. Reserved for future use, currently not used.
* '''MainUi''' MainUi=devcontrol - Change main user interface plugin of the Pixet program. User can programm your own plugins and one can be used instead of the Pixet main window.
* '''LogLeaveOldLogs''' LogLeaveOldLogs=false - Disable archiving old log files sets.
* '''LogRotateCount''' LogRotateCount=15 - Change number of archived log directories.
* '''HighDPI''' HighDPI=true - Enable AA_EnableHighDpiScaling feature in QT GUI environment. Disable can work only in very old versions of Pixet. Currently is deprecated and allways on.

=== <nowiki>[Hwlibs]</nowiki> ===
List of hardware library files/paths used in startup to search and connect a devices. See the hwlibs subdirectory description for details.<br>
'''Examples:''' Left is default Pixet configuration with hwlib files in the hwlibs subdirectory, right is simple arrangement with files in the program directory. Last line is disabled in both versions.
{|
|-
|colspan=2|    '''Hwlibs section example (dirs/flat structure)'''
|    
|colspan=2|    '''Hwlibs section (old format, before 2025/09)'''
|-
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
Hwlib=hwlibs\minipix.dll
Hwlib=hwlibs\widepix.dll
Hwlib=hwlibs\zem.dll
;Hwlib=hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
Hwlib=minipix.dll
Hwlib=widepix.dll
Hwlib=zem.dll
;Hwlib=zest.dll
</syntaxhighlight>
|          
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlibs\minipix.dll
hwlibs\widepix.dll
hwlibs\zem.dll
;hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
minipix.dll
widepix.dll
zem.dll
;zest.dll
</syntaxhighlight>
|}

User can disable some hwlibs using the ; symbol.<br><br>

'''Warning:'''
* The '''Hwlib=''' must be exactly Hwlib=, it '''case sensitive'''
<br>

'''List of HWLIB files:''' Windows / Linux
* '''Minipix''': minipix.dll / minipix.so
* '''Widepix with Eth''': zest.dll / zest.so
* '''Widepix with USB2''': widepix.dll / widepix.so
* '''Advapix''' or '''Widepix with USB3''': zem.dll (and aux. file okFrontPanel.dll - allways in the program directory) / zem.so + okFrontPanel.so
* '''Advapix new''': abrd-hwlib.dll / abrd-hwlib.so
* And customer-specific files for motor driving, x-ray sources, etc.

=== <nowiki>[Plugins]</nowiki> ===
List of Pixet plugins files/paths. All files is by default in the plugins subdirectory.
; Note
: Some plugins are not only for GUI Pixet
: Accessing specific files like as '''HDF5''', '''TIFF'''
: These plugins are also needed when using an API.

=== <nowiki>[PixelmanPlugins]</nowiki> ===
List of Pixet plugins files/paths with backward compatibility for old Pixelman program.<br>
'''Warning:'''<br>
This is very obsolette. Support for Pixelman related stuff (this ini section, file formats, etc) '''will be removed soon''' without replacement.

== Device configuration ini files ==
Some devices can has configuration file. Theese files are located in the program main directory or in the user data directory if the UseAppDataDir=true option used. Files have names identical to the names of the corresponding HWlibs, ending with .ini. For example, the Ethernet Widepix uses HWlib zest.dll (or zest.so on Linux) and the configuration is stored in zest.ini.<br>

There is usually no need to edit these files, you can find details about them in the device's manual.<br>

Only for network devices it is sometimes useful to define IP addresses on which Pixet core should search for devices. Either because the general search does not work on the given network, or so that the program does not "steal" a device in another room.
For example, in zest.ini, each device can has its own section and an IP address defined in it:
<syntaxhighlight line lang=ini>
[Device0]
IP=10.10.1.30

[Device1]
IP=10.10.1.31
</syntaxhighlight>

== Device firmware files ==
Some devices need firmware files to upload while initialization process. These files are allways located in the program directory. Names are typically composed from HWlib name and readout chip name (zemtpx3.rbf for example).<br>
List of this kind of files:<br>
zestwpx.bit, zemwpxf.rbf, zemtpx3.rbf, zemtpx3quad.rbf, zemtpx.rbf, cyptpx3pix.rbf<br>
Note: The standard Pixet distribution that comes with your device only contains the files for that device, so you usually won't see all of these files. And Minipix, for example, doesn't need any of it.

== Insidious complications with files/dirs ==
Let's have the following program and with it pypixet.pyd and other necessary files:
<syntaxhighlight lang="python" line>
import os
os.chdir("test-output")
import pypixet

print("pixet core init...")
pypixet.start()
pixet=pypixet.pixet
devices = pixet.devices()
dev = devices[0]

print("dev.doSimpleAcquisition (3 frames @ 1 sec) - start")
rc = dev.doSimpleAcquisition(3, 1, pixet.PX_FTYPE_AUTODETECT, "example.png")
print("dev.doSimpleAcquisition - end:", rc, "(0 is OK)")

pixet.exitPixet()
pypixet.exit()
</syntaxhighlight>
This program normally works with e.g. Minipix, but does not work with e.q. Advapix. Crashes at pypixet.start() or has not any detected devices.<br>
<br>
The problem is that hwlibs load their files eg firmware from the current directory. Minipix not need any other files, Advapix need a firmware .rbf file. Moving '''os.chdir''' after '''pypixet.start()''' solves the problem.

= Related =
* [[Pixet_SDK|Pixet SDK overview]]
* [[PIXet|The PIXet program]]
* [[File types]]

Files and directories of the Pixet and SDK

2026-04-24T14:01:34Z

HudecekP: /* Subdirectories of the Pixet program */

= Main directory of the Pixet program =
[[File:Directory-pixet.png|thumb|alt=Pixet main directory if all here|Pixet main directory if all here]]
Here are main program files, binary libraries, API files, licence file and the '''pixet.ini''' file. Here may also be hwlibs subdirectory, special files for some devices. Their location depends on the <nowiki>[Hwlibs]</nowiki> section of the pixet.ini file.<br>
There can also be subdirectories factory, configs and logs. They are there if '''UseAppDataDir''' is disabled in '''pixet.ini''', in the '''<nowiki>[Settings]</nowiki>''' section.<br>
If here are not located configs, inis and logs, this directory can be located in Program files, or in another location where the user cannot normally write.

; Warning
: It may be confusing that this directory contains device ini files, such as zest.ini, dummy.ini, ..., since installation, but if '''UseAppDataDir''' is enabled or '''AppDataDir'''= is set, in pixet.ini, the files located here have no effect on the devices.

= User data directory =
This is location of [[#The factory and the configs subdirectories|configuration]] and [[#logs|log]] files. The program must be able to write here.<br>
This is used, if in the '''[[Files_and_directories_of_the_Pixet_and_SDK#pixet.ini_file|pixet.ini]]''', in the '''<nowiki>[Settings]</nowiki>''' section is located '''UseAppDataDir=true''' (default state).
[[File:Directory-appdata.png|thumb|alt=AppData - user data directory|AppData - user data directory]]
<br>
Default location is in the user's system application data directory, like us:<br>
* '''Windows''' C:\Users\username\AppData\Local\PixetPro
* '''Linux''' ~/.config/PixetPro
* '''MacOS''' ~/Library/Application Support/PixetPro
<br>
; Notes
* Location of the directory can be changed anywhere, using the '''AppDataDir=''' line in the pixet.ini.
* Turning on '''UseAppDataDir''' does not affect the '''factory''' directory. If it is not changed using '''factoryDir=''', it is still expected beside the running program, or in the current directory, if different.

'''See''': [[#pixet.ini file]]

= Subdirectories of the Pixet program =

== The factory and the configs subdirectories ==
The factory directory should contain the factory default configuration XML files.
The Pixet core use it while starting, if the configuration file is not in the configs directory.
The configs directory contain configuration XML files.
The Pixet core try to use it while starting and save the current settings to it, if exiting.<br>
(This process works the same way when you start and quit the Pixet program or if you use C API functions pxcInit/pxcExit or Python API functions pypixet.start() / pixet.exitPixet()+pypixet.exit().)<br>
'''The detector cannot work properly if proper config not loaded'''.<br>
See [[#Configuration XML files]]<br>
<br>
Location of this subdirs can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file.<br>

=== factory ===
It should contain the factory default configuration XML files. The Pixet core use it while starting, if the configuration file is not in the configs directory or if user click the "Load factory config" or scripts can use it by the loadFactoryConfig() method.<br>
Location of this subdir can be in the main program directory or can be located anywhere using the '''FactoryDir=''' line in the pixet.ini file.<br>
Hint: If you frequently do experiments with more instances of Pixet, API-using programs or scripts and have more devices, you can use single location of the factory directory for all.

'''Notes:'''
* Location of this directory '''not affected by''' the '''UseAppDataDir=''' in pixet.ini.
* File '''names must be exact''', for example MiniPIX-D06-W0065.xml, AdvaPIX-C06-W0127-4.xml. It is the complete device name, where all spaces are replaced by minuses. If not exact, a load-factory like functions cannot find it.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

=== configs ===
Contain '''configuration XML files for devices'''. The Pixet core try to use it while starting the Pixet program or in pypixet.start() method in scripts, or if the C API function pxcInit() used. And automatically save the current settings to it, while exitting the Pixet program, or if the pypixet.exit() method is used in scripts, or if the pxcExit() function used via C API.<br>
<br>
In addition, this directory contains:
* '''Configuration XML files for filters''' - name format filtername_DevName ChipID.xml - for example "adaptiveff_MiniPIX D06-W0065.xml"
* '''Configuration INI files for plugins - dev specific''' - name format pluginname_ChipID.ini - for example "devcontrol_D06-W0065.ini"
* '''Configuration INI files for plugins''' - name format pluginname.ini - for example "pyscripting.ini"

Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''ConfigsDir=''' line in the pixet.ini file.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== logs ==
[[File:Directory-logs.png|thumb|alt=The logs directory|The logs directory]]
Here are log files from all hardware libraries, pixet core. Files are from last Pixet core run. While next run, the core archive last log files. Subdirectories logs1, logs2, ... contains backups for last 10 sessions.<br>
Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''LogsDir=''' line in the pixet.ini file.

* Main log file is the '''log.log'''. This is the main log of the Pixet core.
:: You can see here the attempts to load hwlibs, whether any device was found, whether hwlib was able to start, load the configuration, ...
* Hwlib logs are named by each hwlib, eq. '''minipix.log'''.
:: You can see here the hwlib messages. It contains detected device names, serial numbers and types.
* Device logs are named by hwlib and each device, eq. '''minipixtpx3_0144 A.log'''.
:: Here are the low-level informations. It can be helpful for our Technical support if the device is naughty.
* The '''runtime.log'''.
:: Simple list of init/exit times of the Pixet core.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Settings]</nowiki> section

== hwlibs ==
This is the usual place for hwlib libraries, designed to work with different types of devices. The actual location of the files is defined in the <nowiki>[hwlibs]</nowiki> section of the pixet.ini file. Default is the hwlibs subdirectory of the main program running directory. But here are a simple relative paths from the main program location and can be configured without subdirectory. It is commonly used in single-purpose programs using API.<br>
'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Hwlibs]</nowiki> section

== plugins ==
Default location of plugins to the Pixet program.<br>
Warning: Some plugins can be need for API too.

'''See:'''
* [[#pixet.ini file]] - <nowiki>[Plugins]</nowiki> section

== drivers ==
Installators of drivers for some devices.

== libs ==
Libraries for Python scripting plugin.

== scripts ==
* Sample scripts for using Python scripting plugin.
* The default place to search for imports used in scripts run from the Python scripting plugin.

== Other subdirs ==
* samples - Sample data for demo when using virtual file device.
* help - PDF manuals
* platforms, styles - System directories of QT.

= Main directory of the API-using programs, independent on the Pixet =
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio files installed|Directory of minimalistic program using binary API and working on computer with Visual Studio installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
User can write programs using our API. To operate them, need:
* '''Pixet core library''' - The core of the Pixet program. '''pxcore.dll''', or pxcore.so file.
* '''Pixel processing library''' - '''pxproc.dll''' or pxproc.so library - only for Clustering and Spectral imaging use
* '''Static linking libraries''' - To compile binary programs on Windows, user need the pxcore.lib (and pxproc.lib). Only in compile time. Compiler must be setup for using it.
* '''Auxilliary libraries of system''' - If program must working on computer without an IDE installed, can need some auxilliary libs, like as: msvcp140.dll, vcruntime140.dll, etc
* '''pixet.ini''' - configuration for the Pixet core. See [[#pixet.ini file]]
* '''HWlibs''' for the given hardware (and firmwares if devices need). See [[#hwlibs]] and [[#Device firmware files]]
* '''Device configuration files''' in the '''factory''' and '''configs''' directories, or elsewhere according to the settings in pixet.ini. See [[#The factory and the configs subdirectories]]
* '''Place for logs''' in the '''logs''' directory, or elsewhere according to the settings in pixet.ini. See [[#logs]]
* '''Python interface''' - To run Python scripts, '''pypixet.pyd''' is needed in addition. And a '''pypxproc.pyd''' for Clustering and Spectral imaging objects.<br>
<br>
Basic files are in the API packages:
{{APIpackages}}

Alternatives to run the API using programs:
# Copy all need files to the Project directory.
# While running the program, change the operating directory to the Pixet main directory.
# Copy the binary executable or python script to the Pixet main directory and run it from here. Useful for occasional single test, but can do problems in more extensive cases.

= Special files =

=== Configuration XML files ===
The config file contains all detector settings and you can start and continue with the settings as it was while last program exit. The factory config is config saved afther low-level detector setup, finding of bad pixels, calibrations and other factory tests.<br>
<br>
'''Notes:'''
* '''The detector cannot work properly if proper config not loaded'''.
* The files must have proper names. “WidePIX-B04-W0535-10.xml” for example. If not, automatic load at start will not work. To optain proper config name, you can do the program exit and see saved filename in the configs directory.
'''See:'''
* [[#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>

== pixet.ini file ==
This is the main configuration file of the Pixet core. It has several sections beginning with a title in square brackets. Sections contain configuration lines formated as '''Name=value''' or '''Name=''' for default value. They can also contain comments, which start with a semicolon. This way you can also deactivate some configuration lines.<br>
Default version of the file conaining used options and all remaining options disabled + with =default. User can edit it and enable.<br>
<br>
'''Warning:'''<br>
Up to release 1.8.3 the [Hwlibs] section contains lines without the = symbol. This is not compliant with the INI standard. '''The file format will change''' soon. From the next version all data lines will starts with the name=.<br>
<br>
The default '''path where Pixet core looks for the pixet.ini''' file is the same as the path to the program that started the pxcore library. So the file should be next to it. Attention, '''all other paths''' are relative to the current directory, not to the position of the program.<br>
So if you run c:\program files\pixet\pixet.exe from c:\users\myname, pxcore will try to load c:\program files\pixet\pixet.ini and all other relative paths (including those listed in the pixet.ini) will start with c:\users\myname.

=== <nowiki>[Settings]</nowiki> ===
General settings of used directories, core and the Pixet program parameters:
* '''UseAppDataDir''' UseAppDataDir=true - Change default location of the configs and logs subdirs and ini files to the user data directory. It also allows different login users to have different settings of same devices in same programs.
: Note: This does not affects the factory directory.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIniInAppDataDir''' PixetIniInAppDataDir=true - Enable reading the pixet.ini file from the user data directory. Very usesful if the program is located in the Program files or at other location with no write rights. It also allows different users to have different pixet.ini. Note: Enabling this option means that the Pixet core first loads this file (from the program launch point) and, after detecting this option, loads it again from the user data directory. Other settings in the default pixet.ini are therefore ignored.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIni''' PixetIni=C:\myPixetAppData\myPixetIni1.ini - Change name and location of the pixet.ini file. Similar to the case of PixetIniInAppDataDir, when using PixetIni=, the initialization file will be loaded again and the contents of the original file will not affect the further operation of the software.
* '''AppDataDir''' AppDataDir=C:\myPixetAppData\group1 - Change location of the user data directory to specified path. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings.
* '''ConfigsDir''' ConfigsDir=C:\myPixetAppData\configsGroup1 - Change location od the configs dir to other location. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings of devices.
* '''FactoryDir''' FactoryDir=C:\myPixetAppData\factory - Change location od the factory dir to other location. Useful if user have many independent places of a programs, creating new programs and testing new devices. User can simply store all factory files in one location. Or it is possible to have such a directory on the company server, where users do not have the right to write.
* '''LogsDir''' LogsDir=C:\temp\pxCoreDebug - Change location of the logs directory. Useful if user have many independent places of a programs, typically if creating new programs. User can simply collect all logs to one directory so that he does not have to open another one every time.
* '''Splash''' Splash=true - Use a splash screen when the Pixet program starting. It does not affect programs using the API.
* '''FileDevice''' FileDevice=true - Enable virtual "file device" independent if physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''FileDeviceWhenNoDevs''' = FileDeviceWhenNoDevs=false - Disable virtual "file device" if no physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''SaveSettings''' SaveSettings=false - Disable automatic save device settings on exit pixet core. It affects Pixet as well as programs that use the API.
* '''MaxFrameMemory''' MaxFrameMemory=1024 - Change the frame memory limit for multiframe acquisitions. Reserved for future use, currently not used.
* '''MainUi''' MainUi=devcontrol - Change main user interface plugin of the Pixet program. User can programm your own plugins and one can be used instead of the Pixet main window.
* '''LogLeaveOldLogs''' LogLeaveOldLogs=false - Disable archiving old log files sets.
* '''LogRotateCount''' LogRotateCount=15 - Change number of archived log directories.
* '''HighDPI''' HighDPI=true - Enable AA_EnableHighDpiScaling feature in QT GUI environment. Disable can work only in very old versions of Pixet. Currently is deprecated and allways on.

=== <nowiki>[Hwlibs]</nowiki> ===
List of hardware library files/paths used in startup to search and connect a devices. See the hwlibs subdirectory description for details.<br>
'''Examples:''' Left is default Pixet configuration with hwlib files in the hwlibs subdirectory, right is simple arrangement with files in the program directory. Last line is disabled in both versions.
{|
|-
|colspan=2|    '''Hwlibs section example (dirs/flat structure)'''
|    
|colspan=2|    '''Hwlibs section (old format, before 2025/09)'''
|-
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=hwlibs\minipix.dll
hwlib=hwlibs\widepix.dll
hwlib=hwlibs\zem.dll
;hwlib=hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=minipix.dll
hwlib=widepix.dll
hwlib=zem.dll
;hwlib=zest.dll
</syntaxhighlight>
|          
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlibs\minipix.dll
hwlibs\widepix.dll
hwlibs\zem.dll
;hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
minipix.dll
widepix.dll
zem.dll
;zest.dll
</syntaxhighlight>
|}

User can disable some hwlibs using the ; symbol.<br><br>
'''List of HWLIB files:''' Windows / Linux
* '''Minipix''': minipix.dll / minipix.so
* '''Widepix with Eth''': zest.dll / zest.so
* '''Widepix with USB2''': widepix.dll / widepix.so
* '''Advapix''' or '''Widepix with USB3''': zem.dll (and aux. file okFrontPanel.dll - allways in the program directory) / zem.so + okFrontPanel.so
* '''Advapix new''': abrd-hwlib.dll / abrd-hwlib.so
* And customer-specific files for motor driving, x-ray sources, etc.

=== <nowiki>[Plugins]</nowiki> ===
List of Pixet plugins files/paths. All files is by default in the plugins subdirectory.
; Note
: Some plugins are not only for GUI Pixet
: Accessing specific files like as '''HDF5''', '''TIFF'''
: These plugins are also needed when using an API.

=== <nowiki>[PixelmanPlugins]</nowiki> ===
List of Pixet plugins files/paths with backward compatibility for old Pixelman program.<br>
'''Warning:'''<br>
This is very obsolette. Support for Pixelman related stuff (this ini section, file formats, etc) '''will be removed soon''' without replacement.

== Device configuration ini files ==
Some devices can has configuration file. Theese files are located in the program main directory or in the user data directory if the UseAppDataDir=true option used. Files have names identical to the names of the corresponding HWlibs, ending with .ini. For example, the Ethernet Widepix uses HWlib zest.dll (or zest.so on Linux) and the configuration is stored in zest.ini.<br>

There is usually no need to edit these files, you can find details about them in the device's manual.<br>

Only for network devices it is sometimes useful to define IP addresses on which Pixet core should search for devices. Either because the general search does not work on the given network, or so that the program does not "steal" a device in another room.
For example, in zest.ini, each device can has its own section and an IP address defined in it:
<syntaxhighlight line lang=ini>
[Device0]
IP=10.10.1.30

[Device1]
IP=10.10.1.31
</syntaxhighlight>

== Device firmware files ==
Some devices need firmware files to upload while initialization process. These files are allways located in the program directory. Names are typically composed from HWlib name and readout chip name (zemtpx3.rbf for example).<br>
List of this kind of files:<br>
zestwpx.bit, zemwpxf.rbf, zemtpx3.rbf, zemtpx3quad.rbf, zemtpx.rbf, cyptpx3pix.rbf<br>
Note: The standard Pixet distribution that comes with your device only contains the files for that device, so you usually won't see all of these files. And Minipix, for example, doesn't need any of it.

== Insidious complications with files/dirs ==
Let's have the following program and with it pypixet.pyd and other necessary files:
<syntaxhighlight lang="python" line>
import os
os.chdir("test-output")
import pypixet

print("pixet core init...")
pypixet.start()
pixet=pypixet.pixet
devices = pixet.devices()
dev = devices[0]

print("dev.doSimpleAcquisition (3 frames @ 1 sec) - start")
rc = dev.doSimpleAcquisition(3, 1, pixet.PX_FTYPE_AUTODETECT, "example.png")
print("dev.doSimpleAcquisition - end:", rc, "(0 is OK)")

pixet.exitPixet()
pypixet.exit()
</syntaxhighlight>
This program normally works with e.g. Minipix, but does not work with e.q. Advapix. Crashes at pypixet.start() or has not any detected devices.<br>
<br>
The problem is that hwlibs load their files eg firmware from the current directory. Minipix not need any other files, Advapix need a firmware .rbf file. Moving '''os.chdir''' after '''pypixet.start()''' solves the problem.

= Related =
* [[Pixet_SDK|Pixet SDK overview]]
* [[PIXet|The PIXet program]]
* [[File types]]

Files and directories of the Pixet and SDK

2026-04-24T11:40:47Z

HudecekP: /* hwlibs */

= Main directory of the Pixet program =
[[File:Directory-pixet.png|thumb|alt=Pixet main directory if all here|Pixet main directory if all here]]
Here are main program files, binary libraries, API files, licence file and the '''pixet.ini''' file. Here may also be hwlibs subdirectory, special files for some devices. Their location depends on the <nowiki>[Hwlibs]</nowiki> section of the pixet.ini file.<br>
There can also be subdirectories factory, configs and logs. They are there if '''UseAppDataDir''' is disabled in '''pixet.ini''', in the '''<nowiki>[Settings]</nowiki>''' section.<br>
If here are not located configs, inis and logs, this directory can be located in Program files, or in another location where the user cannot normally write.

; Warning
: It may be confusing that this directory contains device ini files, such as zest.ini, dummy.ini, ..., since installation, but if '''UseAppDataDir''' is enabled or '''AppDataDir'''= is set, in pixet.ini, the files located here have no effect on the devices.

= User data directory =
This is location of [[#The factory and the configs subdirectories|configuration]] and [[#logs|log]] files. The program must be able to write here.<br>
This is used, if in the '''[[Files_and_directories_of_the_Pixet_and_SDK#pixet.ini_file|pixet.ini]]''', in the '''<nowiki>[Settings]</nowiki>''' section is located '''UseAppDataDir=true''' (default state).
[[File:Directory-appdata.png|thumb|alt=AppData - user data directory|AppData - user data directory]]
<br>
Default location is in the user's system application data directory, like us:<br>
* '''Windows''' C:\Users\username\AppData\Local\PixetPro
* '''Linux''' ~/.config/PixetPro
* '''MacOS''' ~/Library/Application Support/PixetPro
<br>
; Notes
* Location of the directory can be changed anywhere, using the '''AppDataDir=''' line in the pixet.ini.
* Turning on '''UseAppDataDir''' does not affect the '''factory''' directory. If it is not changed using '''factoryDir=''', it is still expected beside the running program, or in the current directory, if different.

'''See''': [[#pixet.ini file]]

= Subdirectories of the Pixet program =

== The factory and the configs subdirectories ==
The factory directory should contain the factory default configuration XML files.
The Pixet core use it while starting, if the configuration file is not in the configs directory.
The configs directory contain configuration XML files.
The Pixet core try to use it while starting and save the current settings to it, if exiting.<br>
(This process works the same way when you start and quit the Pixet program or if you use C API functions pxcInit/pxcExit or Python API functions pypixet.start() / pixet.exitPixet()+pypixet.exit().)<br>
'''The detector cannot work properly if proper config not loaded'''.<br>
See [[#Configuration XML files]]<br>
<br>
Location of this subdirs can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file.<br>

=== factory ===
It should contain the factory default configuration XML files. The Pixet core use it while starting, if the configuration file is not in the configs directory or if user click the "Load factory config" or scripts can use it by the loadFactoryConfig() method.<br>
Location of this subdir can be in the main program directory or can be located anywhere using the '''FactoryDir=''' line in the pixet.ini file.<br>
Hint: If you frequently do experiments with more instances of Pixet, API-using programs or scripts and have more devices, you can use single location of the factory directory for all.

'''Notes:'''
* Location of this directory '''not affected by''' the '''UseAppDataDir=''' in pixet.ini.
* File '''names must be exact''', for example MiniPIX-D06-W0065.xml, AdvaPIX-C06-W0127-4.xml. It is the complete device name, where all spaces are replaced by minuses. If not exact, a load-factory like functions cannot find it.

=== configs ===
Contain '''configuration XML files for devices'''. The Pixet core try to use it while starting the Pixet program or in pypixet.start() method in scripts, or if the C API function pxcInit() used. And automatically save the current settings to it, while exitting the Pixet program, or if the pypixet.exit() method is used in scripts, or if the pxcExit() function used via C API.<br>
<br>
In addition, this directory contains:
* '''Configuration XML files for filters''' - name format filtername_DevName ChipID.xml - for example "adaptiveff_MiniPIX D06-W0065.xml"
* '''Configuration INI files for plugins - dev specific''' - name format pluginname_ChipID.ini - for example "devcontrol_D06-W0065.ini"
* '''Configuration INI files for plugins''' - name format pluginname.ini - for example "pyscripting.ini"

Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''ConfigsDir=''' line in the pixet.ini file.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

== logs ==
[[File:Directory-logs.png|thumb|alt=The logs directory|The logs directory]]
Here are log files from all hardware libraries, pixet core. Files are from last Pixet core run. While next run, the core archive last log files. Subdirectories logs1, logs2, ... contains backups for last 10 sessions.<br>
Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''LogsDir=''' line in the pixet.ini file.

* Main log file is the '''log.log'''. This is the main log of the Pixet core.
:: You can see here the attempts to load hwlibs, whether any device was found, whether hwlib was able to start, load the configuration, ...
* Hwlib logs are named by each hwlib, eq. '''minipix.log'''.
:: You can see here the hwlib messages. It contains detected device names, serial numbers and types.
* Device logs are named by hwlib and each device, eq. '''minipixtpx3_0144 A.log'''.
:: Here are the low-level informations. It can be helpful for our Technical support if the device is naughty.
* The '''runtime.log'''.
:: Simple list of init/exit times of the Pixet core.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

== hwlibs ==
This is the usual place for hwlib libraries, designed to work with different types of devices. The actual location of the files is defined in the <nowiki>[hwlibs]</nowiki> section of the pixet.ini file. Default is the hwlibs subdirectory of the main program running directory. But here are a simple relative paths from the main program location and can be configured without subdirectory. It is commonly used in single-purpose programs using API.<br>
'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

'''See:'''
* [[#pixet.ini file]]

== plugins ==
Default location of plugins to the Pixet program.<br>
Warning: Some plugins can be need for API too.

== drivers ==
Installators of drivers for some devices.

== libs ==
Libraries for Python scripting plugin.

== scripts ==
* Sample scripts for using Python scripting plugin.
* The default place to search for imports used in scripts run from the Python scripting plugin.

== Other subdirs ==
* samples - Sample data for demo when using virtual file device.
* help - PDF manuals
* platforms, styles - System directories of QT.

= Main directory of the API-using programs, independent on the Pixet =
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio files installed|Directory of minimalistic program using binary API and working on computer with Visual Studio installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
User can write programs using our API. To operate them, need:
* '''Pixet core library''' - The core of the Pixet program. '''pxcore.dll''', or pxcore.so file.
* '''Pixel processing library''' - '''pxproc.dll''' or pxproc.so library - only for Clustering and Spectral imaging use
* '''Static linking libraries''' - To compile binary programs on Windows, user need the pxcore.lib (and pxproc.lib). Only in compile time. Compiler must be setup for using it.
* '''Auxilliary libraries of system''' - If program must working on computer without an IDE installed, can need some auxilliary libs, like as: msvcp140.dll, vcruntime140.dll, etc
* '''pixet.ini''' - configuration for the Pixet core. See [[#pixet.ini file]]
* '''HWlibs''' for the given hardware (and firmwares if devices need). See [[#hwlibs]] and [[#Device firmware files]]
* '''Device configuration files''' in the '''factory''' and '''configs''' directories, or elsewhere according to the settings in pixet.ini. See [[#The factory and the configs subdirectories]]
* '''Place for logs''' in the '''logs''' directory, or elsewhere according to the settings in pixet.ini. See [[#logs]]
* '''Python interface''' - To run Python scripts, '''pypixet.pyd''' is needed in addition. And a '''pypxproc.pyd''' for Clustering and Spectral imaging objects.<br>
<br>
Basic files are in the API packages:
{{APIpackages}}

Alternatives to run the API using programs:
# Copy all need files to the Project directory.
# While running the program, change the operating directory to the Pixet main directory.
# Copy the binary executable or python script to the Pixet main directory and run it from here. Useful for occasional single test, but can do problems in more extensive cases.

= Special files =

=== Configuration XML files ===
The config file contains all detector settings and you can start and continue with the settings as it was while last program exit. The factory config is config saved afther low-level detector setup, finding of bad pixels, calibrations and other factory tests.<br>
<br>
'''Notes:'''
* '''The detector cannot work properly if proper config not loaded'''.
* The files must have proper names. “WidePIX-B04-W0535-10.xml” for example. If not, automatic load at start will not work. To optain proper config name, you can do the program exit and see saved filename in the configs directory.
'''See:'''
* [[#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>

== pixet.ini file ==
This is the main configuration file of the Pixet core. It has several sections beginning with a title in square brackets. Sections contain configuration lines formated as '''Name=value''' or '''Name=''' for default value. They can also contain comments, which start with a semicolon. This way you can also deactivate some configuration lines.<br>
Default version of the file conaining used options and all remaining options disabled + with =default. User can edit it and enable.<br>
<br>
'''Warning:'''<br>
Up to release 1.8.3 the [Hwlibs] section contains lines without the = symbol. This is not compliant with the INI standard. '''The file format will change''' soon. From the next version all data lines will starts with the name=.<br>
<br>
The default '''path where Pixet core looks for the pixet.ini''' file is the same as the path to the program that started the pxcore library. So the file should be next to it. Attention, '''all other paths''' are relative to the current directory, not to the position of the program.<br>
So if you run c:\program files\pixet\pixet.exe from c:\users\myname, pxcore will try to load c:\program files\pixet\pixet.ini and all other relative paths (including those listed in the pixet.ini) will start with c:\users\myname.

=== <nowiki>[Settings]</nowiki> ===
General settings of used directories, core and the Pixet program parameters:
* '''UseAppDataDir''' UseAppDataDir=true - Change default location of the configs and logs subdirs and ini files to the user data directory. It also allows different login users to have different settings of same devices in same programs.
: Note: This does not affects the factory directory.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIniInAppDataDir''' PixetIniInAppDataDir=true - Enable reading the pixet.ini file from the user data directory. Very usesful if the program is located in the Program files or at other location with no write rights. It also allows different users to have different pixet.ini. Note: Enabling this option means that the Pixet core first loads this file (from the program launch point) and, after detecting this option, loads it again from the user data directory. Other settings in the default pixet.ini are therefore ignored.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIni''' PixetIni=C:\myPixetAppData\myPixetIni1.ini - Change name and location of the pixet.ini file. Similar to the case of PixetIniInAppDataDir, when using PixetIni=, the initialization file will be loaded again and the contents of the original file will not affect the further operation of the software.
* '''AppDataDir''' AppDataDir=C:\myPixetAppData\group1 - Change location of the user data directory to specified path. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings.
* '''ConfigsDir''' ConfigsDir=C:\myPixetAppData\configsGroup1 - Change location od the configs dir to other location. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings of devices.
* '''FactoryDir''' FactoryDir=C:\myPixetAppData\factory - Change location od the factory dir to other location. Useful if user have many independent places of a programs, creating new programs and testing new devices. User can simply store all factory files in one location. Or it is possible to have such a directory on the company server, where users do not have the right to write.
* '''LogsDir''' LogsDir=C:\temp\pxCoreDebug - Change location of the logs directory. Useful if user have many independent places of a programs, typically if creating new programs. User can simply collect all logs to one directory so that he does not have to open another one every time.
* '''Splash''' Splash=true - Use a splash screen when the Pixet program starting. It does not affect programs using the API.
* '''FileDevice''' FileDevice=true - Enable virtual "file device" independent if physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''FileDeviceWhenNoDevs''' = FileDeviceWhenNoDevs=false - Disable virtual "file device" if no physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''SaveSettings''' SaveSettings=false - Disable automatic save device settings on exit pixet core. It affects Pixet as well as programs that use the API.
* '''MaxFrameMemory''' MaxFrameMemory=1024 - Change the frame memory limit for multiframe acquisitions. Reserved for future use, currently not used.
* '''MainUi''' MainUi=devcontrol - Change main user interface plugin of the Pixet program. User can programm your own plugins and one can be used instead of the Pixet main window.
* '''LogLeaveOldLogs''' LogLeaveOldLogs=false - Disable archiving old log files sets.
* '''LogRotateCount''' LogRotateCount=15 - Change number of archived log directories.
* '''HighDPI''' HighDPI=true - Enable AA_EnableHighDpiScaling feature in QT GUI environment. Disable can work only in very old versions of Pixet. Currently is deprecated and allways on.

=== <nowiki>[Hwlibs]</nowiki> ===
List of hardware library files/paths used in startup to search and connect a devices. See the hwlibs subdirectory description for details.<br>
'''Examples:''' Left is default Pixet configuration with hwlib files in the hwlibs subdirectory, right is simple arrangement with files in the program directory. Last line is disabled in both versions.
{|
|-
|colspan=2|    '''Hwlibs section example (dirs/flat structure)'''
|    
|colspan=2|    '''Hwlibs section (old format, before 2025/09)'''
|-
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=hwlibs\minipix.dll
hwlib=hwlibs\widepix.dll
hwlib=hwlibs\zem.dll
;hwlib=hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=minipix.dll
hwlib=widepix.dll
hwlib=zem.dll
;hwlib=zest.dll
</syntaxhighlight>
|          
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlibs\minipix.dll
hwlibs\widepix.dll
hwlibs\zem.dll
;hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
minipix.dll
widepix.dll
zem.dll
;zest.dll
</syntaxhighlight>
|}

User can disable some hwlibs using the ; symbol.<br><br>
'''List of HWLIB files:''' Windows / Linux
* '''Minipix''': minipix.dll / minipix.so
* '''Widepix with Eth''': zest.dll / zest.so
* '''Widepix with USB2''': widepix.dll / widepix.so
* '''Advapix''' or '''Widepix with USB3''': zem.dll (and aux. file okFrontPanel.dll - allways in the program directory) / zem.so + okFrontPanel.so
* '''Advapix new''': abrd-hwlib.dll / abrd-hwlib.so
* And customer-specific files for motor driving, x-ray sources, etc.

=== <nowiki>[Plugins]</nowiki> ===
List of Pixet plugins files/paths. All files is by default in the plugins subdirectory.
; Note
: Some plugins are not only for GUI Pixet
: Accessing specific files like as '''HDF5''', '''TIFF'''
: These plugins are also needed when using an API.

=== <nowiki>[PixelmanPlugins]</nowiki> ===
List of Pixet plugins files/paths with backward compatibility for old Pixelman program.<br>
'''Warning:'''<br>
This is very obsolette. Support for Pixelman related stuff (this ini section, file formats, etc) '''will be removed soon''' without replacement.

== Device configuration ini files ==
Some devices can has configuration file. Theese files are located in the program main directory or in the user data directory if the UseAppDataDir=true option used. Files have names identical to the names of the corresponding HWlibs, ending with .ini. For example, the Ethernet Widepix uses HWlib zest.dll (or zest.so on Linux) and the configuration is stored in zest.ini.<br>

There is usually no need to edit these files, you can find details about them in the device's manual.<br>

Only for network devices it is sometimes useful to define IP addresses on which Pixet core should search for devices. Either because the general search does not work on the given network, or so that the program does not "steal" a device in another room.
For example, in zest.ini, each device can has its own section and an IP address defined in it:
<syntaxhighlight line lang=ini>
[Device0]
IP=10.10.1.30

[Device1]
IP=10.10.1.31
</syntaxhighlight>

== Device firmware files ==
Some devices need firmware files to upload while initialization process. These files are allways located in the program directory. Names are typically composed from HWlib name and readout chip name (zemtpx3.rbf for example).<br>
List of this kind of files:<br>
zestwpx.bit, zemwpxf.rbf, zemtpx3.rbf, zemtpx3quad.rbf, zemtpx.rbf, cyptpx3pix.rbf<br>
Note: The standard Pixet distribution that comes with your device only contains the files for that device, so you usually won't see all of these files. And Minipix, for example, doesn't need any of it.

== Insidious complications with files/dirs ==
Let's have the following program and with it pypixet.pyd and other necessary files:
<syntaxhighlight lang="python" line>
import os
os.chdir("test-output")
import pypixet

print("pixet core init...")
pypixet.start()
pixet=pypixet.pixet
devices = pixet.devices()
dev = devices[0]

print("dev.doSimpleAcquisition (3 frames @ 1 sec) - start")
rc = dev.doSimpleAcquisition(3, 1, pixet.PX_FTYPE_AUTODETECT, "example.png")
print("dev.doSimpleAcquisition - end:", rc, "(0 is OK)")

pixet.exitPixet()
pypixet.exit()
</syntaxhighlight>
This program normally works with e.g. Minipix, but does not work with e.q. Advapix. Crashes at pypixet.start() or has not any detected devices.<br>
<br>
The problem is that hwlibs load their files eg firmware from the current directory. Minipix not need any other files, Advapix need a firmware .rbf file. Moving '''os.chdir''' after '''pypixet.start()''' solves the problem.

= Related =
* [[Pixet_SDK|Pixet SDK overview]]
* [[PIXet|The PIXet program]]
* [[File types]]

Binary core API

2026-04-22T13:09:34Z

HudecekP: /* Frame measuring and related functions list */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 30;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Binary core API

2026-04-21T11:38:41Z

HudecekP: /* Data-driven special settings */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 3;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Binary core API

2026-04-21T11:37:49Z

HudecekP: /* Data-driven special settings */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 3;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Smaller blocks can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Binary core API

2026-04-21T11:18:19Z

HudecekP: /* Data-driven special settings */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 3;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: Testing feature, t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Binary core API

2026-04-21T11:11:57Z

HudecekP: /* Data-driven special settings */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 3;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|-
| '''trgTimeStamp'''<br>Store trigger events to data. If enabled, trigger events will stored to the data as pixel with Overflow=10. See [[File_types#T3PA_files_details|T3PA files_details]]<br>Note: t3pa-like ASCII line used in all file formats, including binary. || [bool]<br>default 0 || [bool]<br>default 0
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]

Files and directories of the Pixet and SDK

2026-04-21T08:53:55Z

HudecekP: /* factory */

= Main directory of the Pixet program =
[[File:Directory-pixet.png|thumb|alt=Pixet main directory if all here|Pixet main directory if all here]]
Here are main program files, binary libraries, API files, licence file and the '''pixet.ini''' file. Here may also be hwlibs subdirectory, special files for some devices. Their location depends on the <nowiki>[Hwlibs]</nowiki> section of the pixet.ini file.<br>
There can also be subdirectories factory, configs and logs. They are there if '''UseAppDataDir''' is disabled in '''pixet.ini''', in the '''<nowiki>[Settings]</nowiki>''' section.<br>
If here are not located configs, inis and logs, this directory can be located in Program files, or in another location where the user cannot normally write.

; Warning
: It may be confusing that this directory contains device ini files, such as zest.ini, dummy.ini, ..., since installation, but if '''UseAppDataDir''' is enabled or '''AppDataDir'''= is set, in pixet.ini, the files located here have no effect on the devices.

= User data directory =
This is location of [[#The factory and the configs subdirectories|configuration]] and [[#logs|log]] files. The program must be able to write here.<br>
This is used, if in the '''[[Files_and_directories_of_the_Pixet_and_SDK#pixet.ini_file|pixet.ini]]''', in the '''<nowiki>[Settings]</nowiki>''' section is located '''UseAppDataDir=true''' (default state).
[[File:Directory-appdata.png|thumb|alt=AppData - user data directory|AppData - user data directory]]
<br>
Default location is in the user's system application data directory, like us:<br>
* '''Windows''' C:\Users\username\AppData\Local\PixetPro
* '''Linux''' ~/.config/PixetPro
* '''MacOS''' ~/Library/Application Support/PixetPro
<br>
; Notes
* Location of the directory can be changed anywhere, using the '''AppDataDir=''' line in the pixet.ini.
* Turning on '''UseAppDataDir''' does not affect the '''factory''' directory. If it is not changed using '''factoryDir=''', it is still expected beside the running program, or in the current directory, if different.

'''See''': [[#pixet.ini file]]

= Subdirectories of the Pixet program =

== The factory and the configs subdirectories ==
The factory directory should contain the factory default configuration XML files.
The Pixet core use it while starting, if the configuration file is not in the configs directory.
The configs directory contain configuration XML files.
The Pixet core try to use it while starting and save the current settings to it, if exiting.<br>
(This process works the same way when you start and quit the Pixet program or if you use C API functions pxcInit/pxcExit or Python API functions pypixet.start() / pixet.exitPixet()+pypixet.exit().)<br>
'''The detector cannot work properly if proper config not loaded'''.<br>
See [[#Configuration XML files]]<br>
<br>
Location of this subdirs can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file.<br>

=== factory ===
It should contain the factory default configuration XML files. The Pixet core use it while starting, if the configuration file is not in the configs directory or if user click the "Load factory config" or scripts can use it by the loadFactoryConfig() method.<br>
Location of this subdir can be in the main program directory or can be located anywhere using the '''FactoryDir=''' line in the pixet.ini file.<br>
Hint: If you frequently do experiments with more instances of Pixet, API-using programs or scripts and have more devices, you can use single location of the factory directory for all.

'''Notes:'''
* Location of this directory '''not affected by''' the '''UseAppDataDir=''' in pixet.ini.
* File '''names must be exact''', for example MiniPIX-D06-W0065.xml, AdvaPIX-C06-W0127-4.xml. It is the complete device name, where all spaces are replaced by minuses. If not exact, a load-factory like functions cannot find it.

=== configs ===
Contain '''configuration XML files for devices'''. The Pixet core try to use it while starting the Pixet program or in pypixet.start() method in scripts, or if the C API function pxcInit() used. And automatically save the current settings to it, while exitting the Pixet program, or if the pypixet.exit() method is used in scripts, or if the pxcExit() function used via C API.<br>
<br>
In addition, this directory contains:
* '''Configuration XML files for filters''' - name format filtername_DevName ChipID.xml - for example "adaptiveff_MiniPIX D06-W0065.xml"
* '''Configuration INI files for plugins - dev specific''' - name format pluginname_ChipID.ini - for example "devcontrol_D06-W0065.ini"
* '''Configuration INI files for plugins''' - name format pluginname.ini - for example "pyscripting.ini"

Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''ConfigsDir=''' line in the pixet.ini file.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

== logs ==
[[File:Directory-logs.png|thumb|alt=The logs directory|The logs directory]]
Here are log files from all hardware libraries, pixet core. Files are from last Pixet core run. While next run, the core archive last log files. Subdirectories logs1, logs2, ... contains backups for last 10 sessions.<br>
Location of this subdir can be in the main program directory or in user data directory, depending on the '''UseAppDataDir=''' line in the pixet.ini file, or can be located anywhere using the '''LogsDir=''' line in the pixet.ini file.

* Main log file is the '''log.log'''. This is the main log of the Pixet core.
:: You can see here the attempts to load hwlibs, whether any device was found, whether hwlib was able to start, load the configuration, ...
* Hwlib logs are named by each hwlib, eq. '''minipix.log'''.
:: You can see here the hwlib messages. It contains detected device names, serial numbers and types.
* Device logs are named by hwlib and each device, eq. '''minipixtpx3_0144 A.log'''.
:: Here are the low-level informations. It can be helpful for our Technical support if the device is naughty.
* The '''runtime.log'''.
:: Simple list of init/exit times of the Pixet core.

'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

== hwlibs ==
This is the usual place for hwlib libraries, designed to work with different types of devices. The actual location of the files is defined in the <nowiki>[hwlibs]</nowiki> section of the pixet.ini file. Default is the hwlibs subdirectory of the main program running directory. But here are a simple relative paths from the main program location and can be configured without subdirectory. It is commonly used in single-purpose programs using API.<br>
'''Note:''' The default '''UseAppDataDir=''' in pixet.ini is '''enabled in Pixet''' installation, but '''disabled in API''' package.

See [[#pixet.ini file]]

== plugins ==
Default location of plugins to the Pixet program.<br>
Warning: Some plugins can be need for API too.

== drivers ==
Installators of drivers for some devices.

== libs ==
Libraries for Python scripting plugin.

== scripts ==
* Sample scripts for using Python scripting plugin.
* The default place to search for imports used in scripts run from the Python scripting plugin.

== Other subdirs ==
* samples - Sample data for demo when using virtual file device.
* help - PDF manuals
* platforms, styles - System directories of QT.

= Main directory of the API-using programs, independent on the Pixet =
[[File:Dirrectory-minimalistic-api-prg-2025.png|frame|right|alt=Directory of minimalistic program using binary API and working on computer with Visual Studio files installed|Directory of minimalistic program using binary API and working on computer with Visual Studio installed<br>(This is afther 2025.09 / for old see: [https://wiki.advacam.cz/wiki/File:Dirrectory-minimalistic-api-prg.png old version])]]
User can write programs using our API. To operate them, need:
* '''Pixet core library''' - The core of the Pixet program. '''pxcore.dll''', or pxcore.so file.
* '''Pixel processing library''' - '''pxproc.dll''' or pxproc.so library - only for Clustering and Spectral imaging use
* '''Static linking libraries''' - To compile binary programs on Windows, user need the pxcore.lib (and pxproc.lib). Only in compile time. Compiler must be setup for using it.
* '''Auxilliary libraries of system''' - If program must working on computer without an IDE installed, can need some auxilliary libs, like as: msvcp140.dll, vcruntime140.dll, etc
* '''pixet.ini''' - configuration for the Pixet core. See [[#pixet.ini file]]
* '''HWlibs''' for the given hardware (and firmwares if devices need). See [[#hwlibs]] and [[#Device firmware files]]
* '''Device configuration files''' in the '''factory''' and '''configs''' directories, or elsewhere according to the settings in pixet.ini. See [[#The factory and the configs subdirectories]]
* '''Place for logs''' in the '''logs''' directory, or elsewhere according to the settings in pixet.ini. See [[#logs]]
* '''Python interface''' - To run Python scripts, '''pypixet.pyd''' is needed in addition. And a '''pypxproc.pyd''' for Clustering and Spectral imaging objects.<br>
<br>
Basic files are in the API packages:
{{APIpackages}}

Alternatives to run the API using programs:
# Copy all need files to the Project directory.
# While running the program, change the operating directory to the Pixet main directory.
# Copy the binary executable or python script to the Pixet main directory and run it from here. Useful for occasional single test, but can do problems in more extensive cases.

= Special files =

=== Configuration XML files ===
The config file contains all detector settings and you can start and continue with the settings as it was while last program exit. The factory config is config saved afther low-level detector setup, finding of bad pixels, calibrations and other factory tests.<br>
<br>
'''Notes:'''
* '''The detector cannot work properly if proper config not loaded'''.
* The files must have proper names. “WidePIX-B04-W0535-10.xml” for example. If not, automatic load at start will not work. To optain proper config name, you can do the program exit and see saved filename in the configs directory.
'''See:'''
* [[#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>

== pixet.ini file ==
This is the main configuration file of the Pixet core. It has several sections beginning with a title in square brackets. Sections contain configuration lines formated as '''Name=value''' or '''Name=''' for default value. They can also contain comments, which start with a semicolon. This way you can also deactivate some configuration lines.<br>
Default version of the file conaining used options and all remaining options disabled + with =default. User can edit it and enable.<br>
<br>
'''Warning:'''<br>
Up to release 1.8.3 the [Hwlibs] section contains lines without the = symbol. This is not compliant with the INI standard. '''The file format will change''' soon. From the next version all data lines will starts with the name=.<br>
<br>
The default '''path where Pixet core looks for the pixet.ini''' file is the same as the path to the program that started the pxcore library. So the file should be next to it. Attention, '''all other paths''' are relative to the current directory, not to the position of the program.<br>
So if you run c:\program files\pixet\pixet.exe from c:\users\myname, pxcore will try to load c:\program files\pixet\pixet.ini and all other relative paths (including those listed in the pixet.ini) will start with c:\users\myname.

=== <nowiki>[Settings]</nowiki> ===
General settings of used directories, core and the Pixet program parameters:
* '''UseAppDataDir''' UseAppDataDir=true - Change default location of the configs and logs subdirs and ini files to the user data directory. It also allows different login users to have different settings of same devices in same programs.
: Note: This does not affects the factory directory.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIniInAppDataDir''' PixetIniInAppDataDir=true - Enable reading the pixet.ini file from the user data directory. Very usesful if the program is located in the Program files or at other location with no write rights. It also allows different users to have different pixet.ini. Note: Enabling this option means that the Pixet core first loads this file (from the program launch point) and, after detecting this option, loads it again from the user data directory. Other settings in the default pixet.ini are therefore ignored.
: See: [[#User data directory|'''User data directory''']]
* '''PixetIni''' PixetIni=C:\myPixetAppData\myPixetIni1.ini - Change name and location of the pixet.ini file. Similar to the case of PixetIniInAppDataDir, when using PixetIni=, the initialization file will be loaded again and the contents of the original file will not affect the further operation of the software.
* '''AppDataDir''' AppDataDir=C:\myPixetAppData\group1 - Change location of the user data directory to specified path. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings.
* '''ConfigsDir''' ConfigsDir=C:\myPixetAppData\configsGroup1 - Change location od the configs dir to other location. Useful if user have more programs using a Advacam devices and want divide it to some groups with different settings of devices.
* '''FactoryDir''' FactoryDir=C:\myPixetAppData\factory - Change location od the factory dir to other location. Useful if user have many independent places of a programs, creating new programs and testing new devices. User can simply store all factory files in one location. Or it is possible to have such a directory on the company server, where users do not have the right to write.
* '''LogsDir''' LogsDir=C:\temp\pxCoreDebug - Change location of the logs directory. Useful if user have many independent places of a programs, typically if creating new programs. User can simply collect all logs to one directory so that he does not have to open another one every time.
* '''Splash''' Splash=true - Use a splash screen when the Pixet program starting. It does not affect programs using the API.
* '''FileDevice''' FileDevice=true - Enable virtual "file device" independent if physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''FileDeviceWhenNoDevs''' = FileDeviceWhenNoDevs=false - Disable virtual "file device" if no physical devices connected.
: See: [[Devices_support#File_device|'''File device''']]
* '''SaveSettings''' SaveSettings=false - Disable automatic save device settings on exit pixet core. It affects Pixet as well as programs that use the API.
* '''MaxFrameMemory''' MaxFrameMemory=1024 - Change the frame memory limit for multiframe acquisitions. Reserved for future use, currently not used.
* '''MainUi''' MainUi=devcontrol - Change main user interface plugin of the Pixet program. User can programm your own plugins and one can be used instead of the Pixet main window.
* '''LogLeaveOldLogs''' LogLeaveOldLogs=false - Disable archiving old log files sets.
* '''LogRotateCount''' LogRotateCount=15 - Change number of archived log directories.
* '''HighDPI''' HighDPI=true - Enable AA_EnableHighDpiScaling feature in QT GUI environment. Disable can work only in very old versions of Pixet. Currently is deprecated and allways on.

=== <nowiki>[Hwlibs]</nowiki> ===
List of hardware library files/paths used in startup to search and connect a devices. See the hwlibs subdirectory description for details.<br>
'''Examples:''' Left is default Pixet configuration with hwlib files in the hwlibs subdirectory, right is simple arrangement with files in the program directory. Last line is disabled in both versions.
{|
|-
|colspan=2|    '''Hwlibs section example (dirs/flat structure)'''
|    
|colspan=2|    '''Hwlibs section (old format, before 2025/09)'''
|-
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=hwlibs\minipix.dll
hwlib=hwlibs\widepix.dll
hwlib=hwlibs\zem.dll
;hwlib=hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlib=minipix.dll
hwlib=widepix.dll
hwlib=zem.dll
;hwlib=zest.dll
</syntaxhighlight>
|          
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
hwlibs\minipix.dll
hwlibs\widepix.dll
hwlibs\zem.dll
;hwlibs\zest.dll
</syntaxhighlight>
| <syntaxhighlight line lang=ini highlight=10,11>
[Hwlibs]
minipix.dll
widepix.dll
zem.dll
;zest.dll
</syntaxhighlight>
|}

User can disable some hwlibs using the ; symbol.<br><br>
'''List of HWLIB files:''' Windows / Linux
* '''Minipix''': minipix.dll / minipix.so
* '''Widepix with Eth''': zest.dll / zest.so
* '''Widepix with USB2''': widepix.dll / widepix.so
* '''Advapix''' or '''Widepix with USB3''': zem.dll (and aux. file okFrontPanel.dll - allways in the program directory) / zem.so + okFrontPanel.so
* '''Advapix new''': abrd-hwlib.dll / abrd-hwlib.so
* And customer-specific files for motor driving, x-ray sources, etc.

=== <nowiki>[Plugins]</nowiki> ===
List of Pixet plugins files/paths. All files is by default in the plugins subdirectory.
; Note
: Some plugins are not only for GUI Pixet
: Accessing specific files like as '''HDF5''', '''TIFF'''
: These plugins are also needed when using an API.

=== <nowiki>[PixelmanPlugins]</nowiki> ===
List of Pixet plugins files/paths with backward compatibility for old Pixelman program.<br>
'''Warning:'''<br>
This is very obsolette. Support for Pixelman related stuff (this ini section, file formats, etc) '''will be removed soon''' without replacement.

== Device configuration ini files ==
Some devices can has configuration file. Theese files are located in the program main directory or in the user data directory if the UseAppDataDir=true option used. Files have names identical to the names of the corresponding HWlibs, ending with .ini. For example, the Ethernet Widepix uses HWlib zest.dll (or zest.so on Linux) and the configuration is stored in zest.ini.<br>

There is usually no need to edit these files, you can find details about them in the device's manual.<br>

Only for network devices it is sometimes useful to define IP addresses on which Pixet core should search for devices. Either because the general search does not work on the given network, or so that the program does not "steal" a device in another room.
For example, in zest.ini, each device can has its own section and an IP address defined in it:
<syntaxhighlight line lang=ini>
[Device0]
IP=10.10.1.30

[Device1]
IP=10.10.1.31
</syntaxhighlight>

== Device firmware files ==
Some devices need firmware files to upload while initialization process. These files are allways located in the program directory. Names are typically composed from HWlib name and readout chip name (zemtpx3.rbf for example).<br>
List of this kind of files:<br>
zestwpx.bit, zemwpxf.rbf, zemtpx3.rbf, zemtpx3quad.rbf, zemtpx.rbf, cyptpx3pix.rbf<br>
Note: The standard Pixet distribution that comes with your device only contains the files for that device, so you usually won't see all of these files. And Minipix, for example, doesn't need any of it.

== Insidious complications with files/dirs ==
Let's have the following program and with it pypixet.pyd and other necessary files:
<syntaxhighlight lang="python" line>
import os
os.chdir("test-output")
import pypixet

print("pixet core init...")
pypixet.start()
pixet=pypixet.pixet
devices = pixet.devices()
dev = devices[0]

print("dev.doSimpleAcquisition (3 frames @ 1 sec) - start")
rc = dev.doSimpleAcquisition(3, 1, pixet.PX_FTYPE_AUTODETECT, "example.png")
print("dev.doSimpleAcquisition - end:", rc, "(0 is OK)")

pixet.exitPixet()
pypixet.exit()
</syntaxhighlight>
This program normally works with e.g. Minipix, but does not work with e.q. Advapix. Crashes at pypixet.start() or has not any detected devices.<br>
<br>
The problem is that hwlibs load their files eg firmware from the current directory. Minipix not need any other files, Advapix need a firmware .rbf file. Moving '''os.chdir''' after '''pypixet.start()''' solves the problem.

= Related =
* [[Pixet_SDK|Pixet SDK overview]]
* [[PIXet|The PIXet program]]
* [[File types]]

Binary core API

2026-04-16T15:29:20Z

HudecekP: /* Data-driven special settings */

= Core/basic binary (C/C++) API introduction =

This API is part of the Advacam's [[Pixet SDK]] and allows access to functions of the Pixet Core.<br>
<br>
The binary API parts are:
# '''Binary core/basic API''' (this document)
# [[Binary_Clustering_API|Binary clustering API]]
# [[Binary_Spectral_Imaging_API|Binary spectral imaging API]]

'''See:''' [[Pixet SDK|Pixet SDK overview]]

== Usage overview ==
* Settings of the device
* Getting information about the device
* Single-frame measurement
* Multi-frame measurement
* Continuous frame measurement (endless repeats and without dead time on some devices, Mpx3 and Tpx2 for example)
* Data-driven (pixel mode) measurement (Tpx3 only)
* Synchronized measurement
* TDI imaging - Scanning linearly moving objects, for example on a conveyor belt.
* Basic image bad pixel correction
* Beam hardening correction (Xray imaging has a very non-linear relationship between the thickness of the material and the intensity of the transmitted radiation. First, low-energy radiation is captured, followed by components that are significantly more penetrating.)

== Libraries ==
The core API with the '''pxcore library''', allowing basic measurements and device settings.<br>
Files:
* '''pxcapi.h''' API header file
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using on Windows (compile time only)
* '''common.h''' common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

= Requirements =

== Hardware ==
This API requires computer with x86 compatible architecture or ARM with memory management features (no small MCU), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).<br>
<br>
'''Specialized functions have names with chip type included:'''
* pxcSet'''Timepix'''CalibrationEnabled – Timepix only (no Timepix3)
* pxcMeasure'''Tpx3'''DataDrivenMode – Timepix3 only
* pxcMeasureSingleFrame'''Mpx3''' – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.<br>
Return code is '''PXCERR_UNEXPECTED_ERROR'''.

== Software ==
All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.<br>
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.<br>
See '''[[#The Pixet core, additional libraries and other files|The Pixet core, additional libraries and other files]]'''
<br>
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.<br>
<br>
In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):<br>
[[File:VisualStudio-PrjSettings.png|frame|none|alt=Visual Studio Project Settings|Visual Studio Project Settings]]

=== The Pixet core, additional libraries and other files ===
Main files:
* '''pxcapi.h''' API header file for importing to C/C++
* '''pxcore.dll''' or '''pxcore.so''' binary libraries for Windows or Linux
* '''pxcore.lib''' static linging file for easier using in C/C++ on Windows

And need some auxiliary files and directories:<br>
* See [[Pixet SDK#Auxilliary files|Pixet SDK: Auxilliary files]]
* See [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]

==== Where to get these files? ====
: All need files except XML configs are located in the zip file with name like us:
::'''API_PIXet_Pro_1.8.2_Windows_x86_64.zip'''
::'''Download:''' [https://advacam.com/downloads/ Advacam download page]<br>
: Be careful about the correct libraries, we supply
:* Windows-x86-64b
:* Linux-x86-64b
:* Linux-ARM-32b
:* Linux-ARM-64b
<br>
:And all files except LIB files for Windows compilation are located in the Pixet directory:<br>
[[File:Files-usable-for-SDK-in-Pixet.png|frame|none|alt=All files except LIB files for Windows compilation are located in the Pixet directory|All files except LIB files for Windows compilation are located in the Pixet directory]]

==== Example of the project directory ====
[[File:Example-project-dirrectory.png|frame|right|alt=Example of the project dirrectory|Example of the project dirrectory]]
On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration
XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.<br>
<br>
The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.<br>
<br>
The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.<br>
<br>
Contents of the pixet.ini file:
[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)<br>
<br>
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.<br>
<br>
Tip: How to create the Windows CLR APP:<br>
[https://social.msdn.microsoft.com/Forums/windows/en-US/a9529502-6304-4aa6-90ee-0757ab258d87/create-c-windows-forms-application-in-visual-studio-2017?forum=winforms MSDN:create-c-windows-forms-application-in-visual-studio-2017]<br>

==== Example of the minimalistic program directory ====
[[File:dirrectory-minimalistic-api-prg.png|frame|center|alt=Example of the minimalistic project dirrectory|Example of the minimalistic project dirrectory]]<br>

= Hints =
Some hints how to avoid complications when using our API.

== Error handling ==
Always use error handling.
* Level 1: Allways check the return code
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {cout << "pxcMeasureContinuous: Error code:" << rc << endl; return rc;}
</syntaxhighlight>
|}
* Level 2: and show error messages
{|
|-
|          
|<syntaxhighlight lang="cpp">
int rc = pxcMeasureContinuous(devIdx, 10, 0.08);
if (rc!=0) {
char buff[500];
pxcGetLastError(buff, 500);
cout << "pxcMeasureContinuous: Error code:" << rc << " msg:" << buff << endl;
return rc;
}
</syntaxhighlight>
|}

== Device configuration ==
For proper operation, it is necessary that the device is correctly configured. There are quite a lot of settings and they all affect the measurement or other behavior of the device. During initialization, the configuration that was previously saved when exiting is used. <br>
Details: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]

Be aware of the '''differences between the default settings of the Pixet program and the API''' package:
* Pixet installed from the installation flash that came with the device contains the factory config for your device. The device will be properly configured at first start.
* PIxet uses AppDataDir. So if you start one Pixet, close it, and then start another one that is installed elsewhere, it will use the settings saved when closing the first one.
* The API package is set to use the configs and factory subdirectories. Configurations in all projects are independent. If you do not copy the factory config to the factory, the default settings will not be correct and, with the exception of Minipix, even the Load factory config function will not work. Also, the settings made in Pixet will not be reflected in your project.

'''Solutions:'''

* Use '''global factory directory''' on Your computer, like as C:/integration/advadam/factory-configs copy all factory configs to it, set it in all instances of Pixet and API-using programs, using '''FactoryDir=''' in it's '''pixet.ini''' files. All programs always starts with '''pxcLoadFactoryConfig''' and next configure every need to be changed (typicaly operation mode).
: Very usefull if developing software for industry integration and using more devices.
* '''Copy settings''' from the Pixet: Optimize all settings of the device in the Pixet program, exit Pixet and copy final config from AppDataDir/configs to the configs of Your project.
: Usesfull if You developping one project with one device and if the project workflow can be manually do in the Pixet.
* '''Load configuration''' using pxcLoadDeviceConfiguration from the AppDataDir or load copy of this file.
: Practically the same using as the previous solution.
* Set the '''UseAppDataDir=true''' in the '''pixet.ini''' in Your project. It will share all configurations with the Pixet program.
: Note the factory directory is not default/automatic subdirectory of the AppDataDir.
: Usesfull for simple tests, but it leads to interactions between projects, where they change each other's settings.

Some example
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcGetDevicesCount();
printf("pxcGetDevicesCount: %d (>=0 is count of devs)\n", rc);
if (rc<1) return rc;

rc = pxcLoadFactoryConfig(0);
printf("pxcLoadFactoryConfig: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0 to ToA+ToT
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
if (rc!=0) return rc;

rc = pxcSetTimepix3CalibrationEnabled(0, true); // enable calibration ToT in frames to Energy [keV]
printf("pxcSetTimepix3CalibrationEnabled: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
// do not change threshold if using calibration (ToT calibrated only for default threshold)

// do some measurements here

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
if (rc!=0) return rc;
}
</syntaxhighlight>

; Note
: Always make sure that the factory config is available in the expected location and with the correct name for automatic use.
: See: [[Files_and_directories_of_the_Pixet_and_SDK#Configuration_XML_files|Files and directories of the Pixet and SDK: Configuration XML files]]

(Thus section is under construction)

= Some examples =

== Simple C commandline example and build ==
See the measurement basics to understand examples:
* [[Binary_core_API#Frame-based_basic_measurement_flow|Frame-based basic measurement flow]]
* [[Binary_core_API#Data-driven_basic_measurement_flow|Data-driven basic measurement flow]]

=== Example code ===
----
This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.<br>
(Timepix3 only)
<syntaxhighlight lang="cpp">
#include "pxcapi.h"

int main() {
int rc; // return code

printf("Initializing...\n");
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)\n", rc);

rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);

// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);

// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);

rc = pxcExit();
printf("pxcExit: %d (0 is OK)\n", rc);
}
</syntaxhighlight>
Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.<br>

=== Building using cmake on Windows with Visual Studio installed ===
----
'''Example of CMakeLists.txt''' file for compiling this using cmake (C++ file is named "'''minipix1.cpp'''"):
<syntaxhighlight lang="cmake">
cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)
</syntaxhighlight>

'''Example of the Cmake building script:'''
<syntaxhighlight lang="bash">
rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..

msbuild /P:Configuration=Release ALL_BUILD.vcxproj

cd ..
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd
</syntaxhighlight>
User can finally run the '''run.cmd''' to run the program.<br>

=== Building on Linux using GCC ===
----
Example build.sh:
<syntaxhighlight lang="bash">
#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -ldl -lm -lc -g
</syntaxhighlight>

Example run.sh to run the output executable:
<syntaxhighlight lang="bash">
#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example
</syntaxhighlight>

;Troubleshooting:
* Be careful of '''library, platform and system compatibility'''.
: That is, 32/64 bit, Intel vs ARM architecture and the use of unusual Linux distributions.
: Example error message: '''skipping incompatible ./libpxcore.so when searching for -lpxcore'''
* Be careful of '''gcc and it's libraries versions'''.
: If too old, some errors will occur.
: Example error message: '''undefined reference to symbol '_Znam@@GLIBCXX_3.4'''

== C++ Windows CLR examples ==
=== AdvacamAPIexamples package ===
This is the package of example apps for all device types.
; Link
: https://advacam.com/examples/AdvacamAPIexamples.rar
: (MS Visual Studio 2017 Solution with C++ projects of Windows CLR programs)

=== Examples using std future ===
This is the package of 2 small examples with '''paralell measuring''' at more devices, using '''std::future'''. Timepix3 only.
: One is Windows '''CLR APP''', second is '''commandline'''
; Link
: https://advacam.com/examples/ExamplesUsingFuture.rar
: (MS Visual Studio 2022 Solution with 2 C++ projects)

== C# examples ==
'''Notes:'''
* Use the release/64 bit configuration
* Functions that have optional parameters in pxcapi.h (for example pxcInitialize) must be declared with all parameters and then called, for example, with zeros.
* The working directory is directory with the exe file. Typically project\bin\Release. Copy pixet.ini and other auxilliary files here.
* In the MS Visual studio 2022 (and may be other), project first not working. You must click Properties, change .NET version to old, save it, change .NET version back to actual and save. Now project can work.
* Our API can also be used to produce cross-platform software. In that case, be careful about the correct libraries, we supply Windows-x86-64b / Linux-x86-64b / Linux-ARM-32b / Linux-ARM-64b.

=== Dummy C# commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;

namespace ConsoleApp1 {
class Program {
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();
static void Main(string[] args) {
int rc;

Console.WriteLine("pxcInitialize ...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} (0 is OK)", rc);

Console.WriteLine("pxcGetDevicesCount...");
rc = pxcGetDevicesCount();
Console.WriteLine("rc={0:D}\n", rc);

if (rc > 0) {
// do something now
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D} Press any key to exit", rc);

Console.ReadKey();
}
}
}
</syntaxhighlight>
</div></div>

=== Some more complex C# imports for inspiration ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceChipID(UInt32 deviceIndex, UInt32 chipIndex, StringBuilder chipIDBuffer, UInt32 size);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceDimensions(UInt32 deviceIndex, ref UInt32 width, ref UInt32 height);

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureSingleFrameTpx3(UInt32 deviceIndex, double frameTime, [Out] double[] frameToaITot, [Out] UInt16[] frameTotEvent, ref UInt32 size, UInt32 trgStg = 0);
</syntaxhighlight>
</div></div>

=== C# data-driven commandline example ===
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="c#">
using System;
using System.Runtime.InteropServices;
using System.Text;

namespace ConsoleApp1 {
class Program {
//public static extern int pxcInitialize(Int32 a, UInt64 b); // before 1.8.5
//PXCAPI int pxcInitialize(const char *iniFile="pixet.ini");
public static extern int pxcInitialize(string iniFile = "pixet.ini");

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcExit();

[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDevicesCount();

//PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetLastError(StringBuilder errorMsgBuffer, UInt32 size);

//PXCAPI int pxcGetDeviceName(unsigned deviceIndex, char* nameBuffer, unsigned size);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetDeviceName(UInt32 deviceIndex, StringBuilder nameBuffer, UInt32 size);

//PXCAPI int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcMeasureTpx3DataDrivenMode(UInt32 deviceIndex, double measTime, string fileName, UInt32 trgStg = 0, IntPtr callback = default, IntPtr userData = default);

//PXCAPI int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3PixelsCount(UInt32 deviceIndex, out UInt32 pixelCount);

// typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
[StructLayout(LayoutKind.Sequential)]
public struct Tpx3Pixel
{
public double toa;
public float tot;
public UInt32 index;
};

//PXCAPI int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
[DllImport("pxcore.dll", CallingConvention = CallingConvention.Cdecl)]
public static extern int pxcGetMeasuredTpx3Pixels(UInt32 deviceIndex, [Out] Tpx3Pixel[] pixels, UInt32 pixelCount);

const UInt32 pixelBuffSize = 1000000;
static Tpx3Pixel[] pixelBuffer = new Tpx3Pixel[pixelBuffSize];

//typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
public delegate void AcqEventFunc(IntPtr eventData, IntPtr userData);

public static void AcqEventCallback(IntPtr eventData, IntPtr userData)
{
Console.WriteLine("*** AcqEventCallback evd={0} ud={1}", eventData, userData.ToInt64());
UInt32 pixelCount;
int rc = pxcGetMeasuredTpx3PixelsCount(0, out pixelCount);
Console.WriteLine(" pxcGetMeasuredTpx3PixelsCount rc={0:D} pixelCount={1} {2}", rc, pixelCount, pixelCount>pixelBuffSize ? "(data truncated)" : "");
if (pixelCount > 0)
{
rc = pxcGetMeasuredTpx3Pixels(0, pixelBuffer, (pixelCount<pixelBuffSize) ? pixelCount : pixelBuffSize);
Console.WriteLine(" pxcGetMeasuredTpx3Pixels rc={0:D}", rc);
for (int i = 0; i < Math.Min(10, pixelCount); i++)
{
Console.WriteLine(" i:{0} pxIdx={1} toa={2} tot={3}", i, pixelBuffer[i].index, pixelBuffer[i].toa, pixelBuffer[i].tot);
}
if (pixelCount>10) Console.WriteLine(" ...");
}
}

public static string GetErrorMessage(bool isErr)
{
if (isErr)
{
StringBuilder errBuff = new StringBuilder(256);
pxcGetLastError(errBuff, 256);
return "err:'" + errBuff.ToString() + "'";
}
else return "OK";
}

static void Main(string[] args) { // ===========================================================================
int rc;
StringBuilder errBuff = new StringBuilder(256);

Console.WriteLine("pxcInitialize...");
//rc = pxcInitialize(0, 0); // before 1.8.5
rc = pxcInitialize();
Console.WriteLine($"rc={rc:D} {GetErrorMessage(rc < 0)}");

Console.WriteLine("pxcGetDevicesCount...");
int devCnt = pxcGetDevicesCount();
Console.WriteLine($"rc={devCnt:D} {GetErrorMessage(devCnt < 0)}");

StringBuilder nameBuffer = new StringBuilder(256);
Console.WriteLine("pxcGetDeviceName...");
for (uint n = 0; n < devCnt; n++)
{
rc = pxcGetDeviceName(n, nameBuffer, 256);
Console.WriteLine(" n:{0} rc={1:D} nam:{2}\n", n, rc, nameBuffer.ToString());
}
if (devCnt > 0) {
Console.WriteLine("Note: A data measured immediatelly afther init can contain chip starting artifacts");
Console.WriteLine(" In real application add wait user response, feve seconds, dummy measurement or do sensor refresh");

Console.WriteLine("pxcMeasureTpx3DataDrivenMode...");
rc = pxcMeasureTpx3DataDrivenMode(0, 10.0, "", 0, Marshal.GetFunctionPointerForDelegate(new AcqEventFunc(AcqEventCallback)), IntPtr.Zero);
Console.WriteLine($"pxcMeasureTpx3DataDrivenMode end: rc={rc:D} {GetErrorMessage(rc < 0)}");
} else {
Console.WriteLine("No devices detected\n");
}

Console.WriteLine("pxcExit...");
rc = pxcExit();
Console.WriteLine("rc={0:D}");
}
}
}
</syntaxhighlight>
</div></div>

See: [[ C-sharp commandline examples]]

=== C# Windows desktop example ===

'''See:''' [[C-sharp windows example]]

== Python using Ctypes examples ==
(Inspirations if you really want to experience such harakiri)

Tip: Copy definition line from pxcapi.h to the bindings section as comment and start writing binding below it. The copilot usually completes it correctly.

<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-package"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0: doSomeFatalErrorHandling(rc)

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT) # set the operation mode
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")

devPixels = 65536 # Singlechip default
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)

# Do something with the data

print("pxcore exit...")
rc = px.pxcExit()
print("pxcExit rc:", rc, "(0 is OK)")
</syntaxhighlight>

=== Simple one frame measurement ===
(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL:
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None:
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int:
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc)
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)")
devWidth = c_uint()
devHeight = c_uint()
devPixels = 65536 # default val. for singlechip
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
size = ctypes.c_ulong(devPixels)

print("pxcMeasureSingleFrameTpx3...")
rc = px.pxcMeasureSingleFrameTpx3(pxIdx, 1.0, frameToaITot, frameTotEvent, byref(size), 0)
print("pxcMeasureSingleFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureSingleFrameTpx3 failed")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print("Frame stats: hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
<hr>
'''Commandline output:'''
<syntaxhighlight lang="bash">
pxcore init...
pxcInitialize rc: 0 (0 is OK)
Devices found: 6
n: 0 name: MiniPIX I08-W0060
n: 1 name: WidePIX D09-W0561-5
n: 2 name: WidePIX F10-W0547-5
n: 3 name: WidePIX F07-W0562-5
n: 4 name: WidePIX D09-W0558-5
n: 5 name: WidePIX G06-W0544-5
Selected device: 0 (if it isn't Tpx3, next code cannot work properly)
Dev dimensions: 256 x 256 pixels: 65536
pxcSetTimepix3Mode rc: 0 (0 is OK)
pxcMeasureSingleFrameTpx3...
pxcMeasureSingleFrameTpx3 rc: 0 (0 is OK) size: 65536
Frame stats: hits: 60 ToaIt min/max: 0.0 15523.0 TotEv min/max: 0 707
pxcore exit...
pxcExit rc: 0 (0 is OK)
Done
</syntaxhighlight>
</div></div>

=== Multi-frame with callback ===
See: [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]

(Tpx3 specific functions used in example, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

print("start...")

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***callback: acqCount:{acqCount}")

size = ctypes.c_uint(devPixels)

rc = px.pxcGetMeasuredFrameTpx3(pxIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
if rc != 0:
print(" pxcGetMeasuredFrameTpx3 rc:", rc, "(0 is OK) size:", size.value)
_showError(px)
ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

pxIdx = 0
print("Selected device:", pxIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(pxIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(pxIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

#px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_uint, c_void_p), c_void_p]
print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(pxIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Multi-frame and data-driven with callback ===
See:
* [[Binary_core_API#Multiple_frames_using_callbacks|#Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

(Tpx3 specific functions used, must be changed for other chip types)
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

px.OPM_TOATOT = 0
px.OPM_EVENT_ITOT = 2

#int pxcSetTimepix3Mode(unsigned deviceIndex, int mode);
px.pxcSetTimepix3Mode.argtypes = [c_uint, c_int]
px.pxcSetTimepix3Mode.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcMeasureSingleFrameTpx3(unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgStg = PXC_TRG_NO);
px.pxcMeasureSingleFrameTpx3.argtypes = [c_uint, ctypes.c_double, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint), c_uint]
px.pxcMeasureSingleFrameTpx3.restype = c_int

#int pxcMeasureMultipleFramesWithCallback(unsigned deviceIndex, unsigned frameCount, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
px.pxcMeasureMultipleFramesWithCallback.argtypes = [c_uint, c_uint, ctypes.c_double, c_uint, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcMeasureMultipleFramesWithCallback.restype = c_int

#int pxcGetMeasuredFrameCount(unsigned deviceIndex);
px.pxcGetMeasuredFrameCount.argtypes = [c_uint]
px.pxcGetMeasuredFrameCount.restype = c_int

#int pxcGetMeasuredFrameTpx3(unsigned deviceIndex, unsigned frameIndex, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size);
px.pxcGetMeasuredFrameTpx3.argtypes = [c_uint, c_uint, POINTER(ctypes.c_double), POINTER(ctypes.c_ushort), POINTER(c_uint)]
px.pxcGetMeasuredFrameTpx3.restype = c_int

#int pxcMeasureTpx3DataDrivenMode(unsigned deviceIndex, double measTime, const char* fileName, unsigned trgStg = PXC_TRG_NO, AcqEventFunc callback = 0, intptr_t userData = 0);
px.pxcMeasureTpx3DataDrivenMode.argtypes = [c_uint, ctypes.c_double, c_char_p, c_uint, ctypes.CFUNCTYPE(None, c_void_p, c_char_p), c_void_p]
px.pxcMeasureTpx3DataDrivenMode.restype = c_int

#int pxcGetMeasuredTpx3PixelsCount(unsigned deviceIndex, unsigned* pixelCount);
px.pxcGetMeasuredTpx3PixelsCount.argtypes = [c_uint, POINTER(c_uint)]
px.pxcGetMeasuredTpx3PixelsCount.restype = c_int

#int pxcGetMeasuredTpx3Pixels(unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount);
px.pxcGetMeasuredTpx3Pixels.argtypes = [c_uint, POINTER(clTpx3Pixel), POINTER(c_uint)]
px.pxcGetMeasuredTpx3Pixels.restype = c_int

def _showError(px: ctypes.CDLL) -> int: # ===============================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print("Err:", buf.value.decode("utf-8", errors="replace"))
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
_showError(px)
# ---------------------------------------------------------------------------------------

devPixels = 65536 # singlechip default
frameToaITot = None #(ctypes.c_double * devPixels)()
frameTotEvent = None #(ctypes.c_ushort * devPixels)()

# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def frameMeasuredCallback(acqCount, userData): # ========================================
print(f"***clb-frame: acqCount:{acqCount} usr:{userData}")

size = ctypes.c_uint(devPixels)
rc = px.pxcGetMeasuredFrameTpx3(devIdx, acqCount-1, frameToaITot, frameTotEvent, ctypes.byref(size))
_testShowError(" pxcGetMeasuredFrameTpx3", rc, f"size:{size.value}")

ToaItMin = min(frameToaITot)
ToaItMax = max(frameToaITot)
TotEvMin = min(frameTotEvent)
TotEvMax = max(frameTotEvent)

hits = 0
for n in range(devPixels):
if frameToaITot[n] != 0 | frameTotEvent[n] != 0: hits += 1

print(" Hits:", hits, "ToaIt min/max:", ToaItMin, ToaItMax, "TotEv min/max:", TotEvMin, TotEvMax)
# ---------------------------------------------------------------------------------------

tpx3PixelsBuffSize = 1000000
tpx3PixelsBuff = (clTpx3Pixel * tpx3PixelsBuffSize)()

# typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
PixelsMeasuredCllback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p)

@PixelsMeasuredCllback
def pixelsMeasuredCallback(eventData, userData): # ======================================
tag = userData.decode("utf-8", errors="replace") if userData else None
print(f"***clb-pixels: eventData:{eventData} usr:{tag}")
pxCnt = c_uint()
rc = px.pxcGetMeasuredTpx3PixelsCount(devIdx, byref(pxCnt))
_testShowError(" pxcGetMeasuredTpx3PixelsCount", rc, f"pxCnt:{pxCnt}")
print(" Pixels count:", pxCnt.value)

pixelsToRead = min(pxCnt.value, tpx3PixelsBuffSize)

rc = px.pxcGetMeasuredTpx3Pixels(devIdx, tpx3PixelsBuff, byref(c_uint(pixelsToRead)))
_testShowError(" pxcGetMeasuredTpx3Pixels", rc, f"pixelsToRead:{pixelsToRead}")

totMin = 1e10
totMax = -1
toaMin = 1e100
toaMax = -1
for n in range(pixelsToRead):
if tpx3PixelsBuff[n].tot < totMin: totMin = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].tot > totMax: totMax = tpx3PixelsBuff[n].tot
if tpx3PixelsBuff[n].toa < toaMin: toaMin = tpx3PixelsBuff[n].toa
if tpx3PixelsBuff[n].toa > toaMax: toaMax = tpx3PixelsBuff[n].toa
if n<10:
print(f" - Pixel {n}: index:{tpx3PixelsBuff[n].index} tot:{tpx3PixelsBuff[n].tot} toa:{tpx3PixelsBuff[n].toa/1e9} s")

print(" Tot min/max:", totMin, totMax, "Toa min/max:", toaMin, toaMax)
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devIdx = 0
print("Selected device:", devIdx, "(if it isn't Tpx3, next code cannot work properly)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)
frameToaITot = (ctypes.c_double * devPixels)()
frameTotEvent = (ctypes.c_ushort * devPixels)()
else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_EVENT_ITOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

print("pxcMeasureMultipleFramesWithCallback...")
rc = px.pxcMeasureMultipleFramesWithCallback(devIdx, 5, 1.0, 0, frameMeasuredCallback, None)
print("pxcMeasureMultipleFramesWithCallback rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureMultipleFramesWithCallback failed")

rc = px.pxcSetTimepix3Mode(devIdx, px.OPM_TOATOT)
print("pxcSetTimepix3Mode rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# userData can be used to transfer device info to callback in multi-device setup
user_tag = ctypes.create_string_buffer(name_buf.value) #f"devIdx:{devIdx}".encode("utf-8"))
print("pxcMeasureTpx3DataDrivenMode...")
rc = px.pxcMeasureTpx3DataDrivenMode(devIdx, 10.0, None, 0, pixelsMeasuredCallback, user_tag)
print("pxcMeasureTpx3DataDrivenMode rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
raise RuntimeError ("pxcMeasureTpx3DataDrivenMode failed")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

=== Other callbacks ===
Two callback types available:
# '''New frames''' measured: typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
# '''New pixels''' measured: typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
# '''Other events''': Use FrameMeasuredCallback too

<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand code parts examples -->'''</div>
<div class="mw-collapsible-content">
'''Bindings of registering/unregistering general events:'''
<syntaxhighlight lang="python">
px.PXC_ACQEVENT_ACQ_FAILED = b"AcqFailed"
px.PXC_ACQEVENT_MEAS_STARTED = b"AcqMeasStarted"
px.PXC_ACQEVENT_MEAS_FINISHED = b"AcqMeasFinished"

#int pxcRegisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcRegisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcRegisterAcqEvent.restype = c_int

#int pxcUnregisterAcqEvent(unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData);
px.pxcUnregisterAcqEvent.argtypes = [c_uint, c_char_p, ctypes.CFUNCTYPE(None, c_uint, c_void_p), c_void_p]
px.pxcUnregisterAcqEvent.restype = c_int
</syntaxhighlight>

'''Callback functions:'''
<syntaxhighlight lang="python">
# typedef void (*FrameMeasuredCallback)(intptr_t acqCount, intptr_t userData);
FrameMeasuredCallback = ctypes.CFUNCTYPE(None, ctypes.c_uint, ctypes.c_void_p)

@FrameMeasuredCallback
def acqStartCallback(acqCount, userData): # =============================================
print(f"***clb-acqStart: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqFinCallback(acqCount, userData): # ===============================================
print(f"***clb-acqFinish: acqCount:{acqCount} usr:{userData}")

@FrameMeasuredCallback
def acqErrCallback(val, userData): # ====================================================
print(f"***clb-acqErr: rc:{val-4294967295} usr:{userData}")
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else: print(" Err:", buf.value.decode("utf-8", errors="replace"))
</syntaxhighlight>

'''Registering/unregistering:'''
<syntaxhighlight lang="python">
rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcRegisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcRegisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcRegisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED , acqErrCallback, None)
print("pxcRegisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

# do something usesfill ---------------------------------------------------

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_STARTED, acqStartCallback, None)
print("pxcUnregisterAcqEvent (start) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_MEAS_FINISHED, acqFinCallback, None)
print("pxcUnregisterAcqEvent (finish) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)

rc = px.pxcUnregisterAcqEvent(devIdx, px.PXC_ACQEVENT_ACQ_FAILED, acqErrCallback, None)
print("pxcUnregisterAcqEvent (failed) rc:", rc, "(0 is OK)")
if rc!= 0: _showError(px)
</syntaxhighlight>
</div></div>

'''See:'''
* [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]]
* [[Binary_core_API#pxcUnregisterAcqEvent|pxcUnregisterAcqEvent]]
* [[Binary_core_API#Multiple_frames_using_callbacks|Multiple frames using callbacks]]
* [[Binary_core_API#API_data-driven_measuring_functions|API data-driven measuring functions]]

=== Beam-hardenning correction ===
This feature isn't in the Python API. Ctypes is usesfull way to using it from Python.

'''The process:'''
# Add reference images (masks) for more material tihicknesses. Very good is from thinner than thinnest part of the object to thicker than whole the imaged object.
# Do the correction of the image
# Try do the non-correctible (deviceAndBH) pixels interpolation
# If failed, try interpolate only device bad pixels

'''Be careful to:'''
* Reference images and images to correct are corresponding.
:* Device used for imaging is same.
:* Xray source voltage, current, distance and optional filter is same.
:* Integrated times are true and in same units.
:* No other changes then integrated time and frames count.

* Good data quality
:* High counts
:* No saturation in references.
:* Stable thickness and homogenous compound of references.
:* No saturation in interested area of image.
* Usesfull measuring mode/subframe. Use counts only.

'''Tips:'''
* The "Acq time" metadata item from a .dsc file can be used to autodetect integrated time.
* If the bad pixels correction needed and the device not available, use the dummy device created using config of the device.

'''See:'''
* [[#Beam_hardening_correction|#Beam hardening correction]]
* [[Devices_support#Dummy_device|Devices support: Dummy device]]

<div class="toccolours mw-collapsible mw-collapsed" style="width:100%;">
<div>'''Expand the example -->'''</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="python" line>
import os, sys, ctypes
from ctypes import byref, c_int, c_uint, c_char_p, c_char, c_void_p, POINTER, create_string_buffer

# Use apiPath "." for this .py in the API directory or some full path to API package in other location
#apiPath = "."
apiPath = "C:/Advacam/API-nightly"
thisPath = os.path.dirname(os.path.abspath(__file__))

def _load_pxcore(api_path: str) -> ctypes.CDLL: # =======================================
dll_path = os.path.join(api_path, "pxcore.dll")
if not os.path.isfile(dll_path):
raise FileNotFoundError(f"pxcore.dll not found at: {dll_path}")
return ctypes.WinDLL(dll_path)

# typedef struct _Tpx3Pixel {double toa; float tot; unsigned int index;} Tpx3Pixel;
class clTpx3Pixel(ctypes.Structure):
_fields_ = [("toa", ctypes.c_double), ("tot", ctypes.c_float), ("index", c_uint)]

def _bind_exports(px: ctypes.CDLL) -> None: # ===========================================
px.pxcInitialize.argtypes = [c_char_p]
px.pxcInitialize.restype = c_int

px.pxcExit.argtypes = []
px.pxcExit.restype = c_int

px.pxcGetDevicesCount.argtypes = []
px.pxcGetDevicesCount.restype = c_int

px.pxcGetDeviceName.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceName.restype = c_int

#int pxcGetDeviceDimensions(unsigned deviceIndex, unsigned* width, unsigned* height);
px.pxcGetDeviceDimensions.argtypes = [c_uint, POINTER(c_uint), POINTER(c_uint)]
px.pxcGetDeviceDimensions.restype

#int pxcAddBHMask(unsigned* data, unsigned size, double frameTime, double thickness);
px.pxcAddBHMask.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, ctypes.c_double]
px.pxcAddBHMask.restype = c_int

#int pxcBHMaskCount();
px.pxcBHMaskCount.argtypes = []
px.pxcBHMaskCount.restype = c_int

#int pxcRemoveBHMask(int index);
px.pxcRemoveBHMask.argtypes = [c_int]
px.pxcRemoveBHMask.restype = c_int

#int pxcApplyBHCorrection(unsigned* inData, unsigned size, double frameTime, double* outData);
px.pxcApplyBHCorrection.argtypes = [POINTER(c_uint), c_uint, ctypes.c_double, POINTER(ctypes.c_double)]
px.pxcApplyBHCorrection.restype = c_int

#int pxcGetDeviceBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceBadPixelMatrix.restype = c_int

#int pxcGetBHBadPixelMatrix(unsigned char* badPixelMatrix, unsigned size);
px.pxcGetBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetBHBadPixelMatrix.restype = c_int

#int pxcGetDeviceAndBHBadPixelMatrix(unsigned deviceIndex, unsigned char* badPixelMatrix, unsigned size);
px.pxcGetDeviceAndBHBadPixelMatrix.argtypes = [c_uint, POINTER(c_char), c_uint]
px.pxcGetDeviceAndBHBadPixelMatrix.restype = c_int

#int pxcInterpolateBadPixels(unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height);
px.pxcInterpolateBadPixels.argtypes = [POINTER(c_char), POINTER(ctypes.c_double), c_uint, c_uint]
px.pxcInterpolateBadPixels.restype = c_int

def _showError(px: ctypes.CDLL, prefix="") -> int: # ====================================
buf = create_string_buffer(4096)
rc = px.pxcGetLastError(buf, ctypes.sizeof(buf))
if rc != 0: print("(pxcGetLastError failed", rc, ")")
else:
s = buf.value.decode("utf-8", errors="replace")
print(f"{prefix}Err: '{s.strip()}'")
return rc

def _testShowError(name, rc, text=""): # ================================================
if rc < 0:
print(f"{name} failed - rc:{rc}", text)
spacesBeforeCnt = 0
if name[0]==" ": spacesBeforeCnt = len(name) - len(name.lstrip())
prefix = ' ' * spacesBeforeCnt
if name[0]=="\t": prefix="\t"
_showError(px, prefix)

def loadFrameDataTxt(filePath, width, height):
data = []
try:
with open(filePath, "r") as f:
for line in f:
row = [int(x) for x in line.strip().split()]
data.append(row)
if len(data) != height or any(len(row) != width for row in data):
raise ValueError(f"Data dimensions do not match: w:{len(data[0]) if data else -1} h:{len(data)} (expected w:{width} h:{height})")
return data
except Exception as e:
print(f"Error loading file:'{filePath}': {e}")
return None

def saveFrameDataTxt(filePath, data, width, height): # ==================================
try:
with open(filePath, "w") as f:
for y in range(height):
for x in range(width):
f.write(str(data[y*width + x]) + " ")
f.write("\n")
print(f"Saved:'{filePath}'")
except Exception as e:
print(f"Error saving file:'{filePath}': {e}")
# ---------------------------------------------------------------------------------------

if apiPath != ".": os.chdir(apiPath) # change dir to API root, otherwise some devices cannot be initialized

px = _load_pxcore(apiPath)
_bind_exports(px)

print("pxcore init...")
rc = px.pxcInitialize(b"pixet.ini")
print("pxcInitialize rc:", rc, "(0 is OK)")
if rc != 0:
_showError(px)
exit()

if apiPath != ".": os.chdir(thisPath) # change dir back or somewhere

try:
devCnt = px.pxcGetDevicesCount()
if devCnt < 0:
_showError(px)
raise RuntimeError ("pxcGetDevicesCount failed")

print("Devices found:", devCnt)
if devCnt <= 0: raise RuntimeError("No devices found")

name_buf = create_string_buffer(512)
for n in range(devCnt):
rc = px.pxcGetDeviceName(n, name_buf, ctypes.sizeof(name_buf))
if rc == 0:
print(" n:", n, "name:", name_buf.value.decode("utf-8", errors="replace"))
else:
print(" n: pxcGetDeviceName rc:", rc, end=" ")
_showError(px)

devPixels = -1
devIdx = 0
print("Selected device:", devIdx, "(if it isn't device that was origin of the data, bad pixels correction will not good)\n")
devWidth = c_uint()
devHeight = c_uint()
rc = px.pxcGetDeviceDimensions(devIdx, byref(devWidth), byref(devHeight))
if rc == 0:
devPixels = devWidth.value * devHeight.value
print("Dev dimensions:", devWidth.value, "x", devHeight.value, "pixels:", devPixels)

else:
print("pxcGetDeviceDimensions rc:", rc)
_showError(px)

wid = devWidth.value
hei = devHeight.value
print("Expected data dimmensions:", wid, hei)

dataPath = os.path.join(thisPath, "../test-data")
fnamFilesRef = [
["BH0mm_1000fr_0.01s_50kV_8mA.txt", 0, 0.01*1000], # timeIntegrated = singne frame * frames count [seconds]
["BH2mm_1000fr_0.01s_50kV_8mA.txt", 2, 0.01*1000], ["BH4mm_1000fr_0.01s_50kV_8mA.txt", 4, 0.01*1000],
["BH8mm_1000fr_0.01s_50kV_8mA.txt", 8, 0.01*1000], ["BH16mm_1000fr_0.01s_50kV_8mA.txt", 16, 0.01*1000]
]
# Be careful to reference images and images to correct are match.
# - Integrated times are true and in same units
# - Source voltage, current, distance and optional filter is same

for fileName, thickness, timeIntegrated in fnamFilesRef:
print(f" Add file:'{fileName}', tim:{timeIntegrated} s, thc:{thickness} mm")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is None: continue
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcAddBHMask(dataArray, len(flatData), timeIntegrated, thickness)
_testShowError("pxcAddBHMask", rc)
print("BH masks added:", px.pxcBHMaskCount())

fnamFilesData = [
["test_1fr0.0993333s50kev8mA.txt", 0.0993333], ["test_1000fr0.01s50kev8mA.txt", 1000*0.01]
]
badPixelsArr = (c_char * devPixels)()

for fileName, timeIntegrated in fnamFilesData:
print(f" File:'{fileName}' time sum:{timeIntegrated} s")
data = loadFrameDataTxt(os.path.join(dataPath, fileName), wid, hei)
if data is not None:
flatData = [pixel for row in data for pixel in row]
dataArray = (c_uint * len(flatData))(*flatData)
outDataArray = (ctypes.c_double * len(flatData))()
a = sum(flatData)/len(flatData)
print(" average:", a, "Warning too low counts (>50k recommended)" if a<50000 else "")
rc = px.pxcApplyBHCorrection(dataArray, len(flatData), timeIntegrated, outDataArray)
_testShowError("pxcApplyBHCorrection", rc)
# dataArray now containing BH corrected data, but with bad pixels
rc = px.pxcGetDeviceAndBHBadPixelMatrix(devIdx, badPixelsArr, devPixels)
_testShowError(" pxcGetDeviceAndBHBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
# badPixelsArr now containing device bad pixels and pixels that was has data useless for BHC
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13: # Too many bad pixels - try use only device bad pixels without BH useless pixels
print(" Too many bad pixels - try use only device bad pixels")
rc = px.pxcGetDeviceBadPixelMatrix(devIdx, badPixelsArr, devPixels)
print(" pxcGetDeviceBadPixelMatrix rc:", rc)
_testShowError(" pxcGetDeviceBadPixelMatrix", rc)
cnt = sum(1 for i in range(devPixels) if badPixelsArr[i] != b'\0')
print(" Bad pixels:", cnt)
rc = px.pxcInterpolateBadPixels(badPixelsArr, outDataArray, wid, hei)
print(" pxcInterpolateBadPixels rc:", rc)
_testShowError(" pxcInterpolateBadPixels", rc)
if rc==-13:
print(" Too many bad pixels - Is the device configured properly?")

opath = os.path.join(dataPath, fileName.replace(".txt", "-BHC.txt"))
saveFrameDataTxt(opath, outDataArray, wid, hei)
else:
print(" (no data readed)")

except Exception as e:
print("Exception:", e)

finally:
print("pxcore exit...")
rc2 = px.pxcExit()
print("pxcExit rc:", rc2, "(0 is OK)")
if rc2 != 0: _showError(px)
else: print("Done")
</syntaxhighlight>
</div></div>

= API header definition =
All API functions are defined in the pxcapi.h file. Each definition starting with the '''PXCAPI''' keyword:
<syntaxhighlight lang="C">
#ifndef WIN32 // Linux
#define PXCAPI extern "C" __attribute__ ((visibility("default")))
#else // Windows
#define PXCAPI extern "C" __declspec(dllexport)
#endif
</syntaxhighlight>

= API auxiliary functions =
This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring or processing data.

== Start-up, end, errors ==

{{ApiBinaryItem
| Nam = pxcInitialize
| HeSym = ===
| Sum = This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError. The init process of each device is:
# Initialize hardwrare and communication
# Try to load device XML config file from the "configs" dir
# If failed, try to load device XML config file from the "factory" dir<br>
: Warning: If the correct config is not loaded, the device will not work properly and may do strange things.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char *iniFile="pixet.ini"
| iniFile – name/path to pxcore main ini file.
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Change parameters since Pixet 1.8.5, previous pxcInitialize has (int argc = 0, char const* argv[] = NULL)
| War =
| Exa = int rc = pxcInitialize();
}}

{{ApiBinaryItem
| Nam = pxcExit
| HeSym = ===
| Sum = This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library. The exit process of each device is:
# Save actual device XML config file to the "configs" dir
# Deinitialization of the hardware and communication
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|The factory and the configs subdirectories]]<br>
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcExit();
}}

{{ApiBinaryItem
| Nam = pxcSetDirectories
| HeSym = ===
| Sum = Sets the configuration files directory and directory for log files. Has to be set before calling the pxcInitialize function. Use it to change its default locations defined by pixet.ini.<br>
'''See'''
: [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|Files and directories of the Pixet and SDK: The factory and the configs subdirectories]]
| DefH = PXCAPI int
| DefP = const char* configsDir, const char* logsDir
| configsDir – Path to the directory for loading/saving config files
| logsDir – Path to the directory for saving log files
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRefreshDevices
| HeSym = ===
| Sum = This function looks for newly connected devices and removed disconnected devices from the device list.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcRefreshDevices();
}}

{{ApiBinaryItem
| Nam = pxcReconnectDevice
| HeSym = ===
| Sum = If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
# Saves the device config to the “configs” directory
# Disconnects the device
# Connects the device
# Loads the device config
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcReconnectDevice(0); // reconnect device with index 0
}}

{{ApiBinaryItem
| Nam = pxcGetLastError
| HeSym = ===
| Sum = Returns text of last error. This function can be called even before pxcInitialize()
| DefH = PXCAPI int
| DefP = char* errorMsgBuffer, unsigned size
| errorMsgBuffer - buffer where text will be saved
| size - size of supplied buffer
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char msg[200];
pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);
}}
'''Example1 (console)'''
<br>
<syntaxhighlight lang="C" line>
#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
char errorMsg[ERRMSG_BUFF_SIZE];
pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
if (errorMsg[0]>0) {
printf("%s %d err: %s", fName, rc, errorMsg);
} else {
printf("%s %d err: ---", fName, rc);
}
if (enter) printf("\n");
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
</syntaxhighlight>
If mode set was suscessfull, result is:
: '''pxcSetTimepix3Mode 0 err: ---'''
If not, you can see some as:
: '''pxcSetTimepix3Mode -2 err: Invalid device index'''
<br>
'''Example2 (Windows CLR)'''
<br>
<syntaxhighlight lang="C" line>
const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
char errorMsg[cErrBufSize];
char cMsg[cErrBufSize];
String^ eMsg;
pxcGetLastError(errorMsg, cErrBufSize);
if (rc!=0) {
sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
eMsg = gcnew String(errorMsg);
} else {
sprintf(cMsg, "%s %d err: ---", fName, rc);
};
String^ sMsg = gcnew String(cMsg);
listMessages->Items->Add(sMsg);
return (rc!=0);
}
</syntaxhighlight>
Now you can use it:<br>
<syntaxhighlight lang="C" line>
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (errorToList("pxcSetTimepix3Mode", rc)) return rc;
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetIPixet
| HeSym = ===
| Sum = Returns a core pointer for processing libraries, Clustering or Spectral imaging for example.
| DefH = PXCAPI void*
| DefP = (void)
|
|
|
|
|
|
|
|
| Ret = core pointer
| Not =
| War =
| Exa =
}}

== Parameter Get/Set functions (direct) ==
Functions described in this chapter working directly, function name defines parameter name and type.<br>
<br>
'''For named parameters settings see:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]<br>
<br>

=== Example: Setting operation mode ===
----
<syntaxhighlight lang="C" line>
// Set the operating mode
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
printErrors("pxcSetTimepix3Mode", rc);
</syntaxhighlight>

=== Example: List of devices with parameters ===
----
<syntaxhighlight lang="C" line>
#include <stdio.h>
#include "pxcapi.h"
#define CHT_Si 0
#define CHT_CdTe 1
char chipType = CHT_Unknown;
int main(int argc, char const* argv[]) { // #######################################
int rc = pxcInitialize();
if (rc) {
printf("Could not initialize Pixet:\n");
printErrors("pxcInitialize", rc, ENTER_ON);
return -1;
}
int connectedDevicesCount = pxcGetDevicesCount();
printf("Connected devices: %d\n", connectedDevicesCount);
if (connectedDevicesCount == 0) return pxcExit();
for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
char deviceName[256];
memset(deviceName, 0, 256);
pxcGetDeviceName(devIdx, deviceName, 256);
char chipID[256];
memset(chipID, 0, 256);
pxcGetDeviceChipID(devIdx, 0, chipID, 256);
printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
}
double bias;
rc = pxcGetBias(devIdx, &bias);
if (bias < 0.0) {
if (devIdx == 0) chipType = CHT_CdTe;
printf("Chip material detected: CdTe\n");
} else if (bias == 0.0) {
printf("Chip material not detected!\n");
} else {
if (devIdx == 0) chipType = CHT_Si;
printf("Chip material detected: Si\n");
}
printf("=================================================================\n");

// here can be working code (calling some example function from this manual)

return pxcExit();
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDevicesCount
| HeSym = ===
| Sum = This function returns number of connected and initialized devices.
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of devices, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa = printf("Connected devices count: %d\n", pxcGetDevicesCount());
}}

{{ApiBinaryItem
| Nam = pxcListNetworkDevices
| HeSym = ===
| Sum = Searches for available network devices and store basic information about it to arrary. This is special function, independent of the Pixet Core. Can be used for listing devices without the PXcore initialized to prevent "steal" of other devices on the network. The output is usesfull to browse/testing network devices, it's IPs and availability on the network subnets.
| DefH = PXCAPI int
| DefP = NetworkDevInfo* devInfos, unsigned* size
| devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
| size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
|
|
|
|
|
|
| Ret = Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)
| Not = 1. Can be used independent of the Pixet core.<br>2. A related feature is planned, allowing you to select devices to be used by PXcore. Currently you can write to the zest.ini instead.
| War =
| Exa = NetworkDevInfo ndi[256];
unsigned ndiSize = 256;
int rc;
msgToList("pxcListNetworkDevices...");
//pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);
rc = pxcListNetworkDevices(ndi, &ndiSize);
errorToList("pxcListNetworkDevices", rc);
if (rc != 0 && rc != PXCERR_BUFFER_SMALL) return;
for (int n=0; n < ndiSize; n++) {
msgToList(String::Format(" IP: {0}\t Name: {1}\t SN: {2}", gcnew String(ndi[n].ip), gcnew String(ndi[n].name), ndi[n].serial));
}
if (ndiSize == 0) msgToList(" (no devs found)");
else if (rc == PXCERR_BUFFER_SMALL) msgToList(" (and more devs than ndi array size)");
}}

'''Network device info details:'''
<syntaxhighlight lang="C">
struct NetworkDevInfo{
char ip[15];
char name[20];
int serial;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceInfo
| HeSym = ===
| Sum = Gets device info structure and returns devType. If *devInfo is NULL, only returns devType.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, CDevInfo *devInfo
| deviceIndex – index of the device, starting from zero
| devInfo – pointer to CDevInfo struct
|
|
|
|
|
|
| Ret = Device type number
| Not =
| War =
| Exa = // simple use:
if (pxcGetDeviceInfo(devIdx, NULL) != TPX3) errorMsg("The device is not Timepix3");
// Advanced use:
CDevInfo devInfo[20];
const char *dtStrings[] = {"Tpx", "Mpx3", "Tpx3", "Tpx2"};
for (int n=0; n<pxcGetDevicesCount(); n++) {
pxcGetDeviceInfo(n, devInfo[n]);
printf("DevIdx %d: Name: %s, SN: %d, DevType: %s", n, devInfo[n].name, devInfo[n].serial, dtStrings[devInfo[n].type-1]);
}
}}
'''Device info details:'''
<syntaxhighlight lang="C">
enum DevType{
TPX = 1, MPX3, TPX3, TPX2,
};
struct CDevInfo{
char name[20];
int serial;
DevType type;
};
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetDeviceName
| HeSym = ===
| Sum = This function returns the full name of the selected device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, char* nameBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| nameBuffer – buffer where the name of the device will be saved. Cannot be NULL
| size – size of the supplied name buffer
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char name[100];
pxcGetDeviceName(deviceIndex, name, 100);
printf("Dev %d name: %s\n", deviceIndex, name);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipCount
| HeSym = ===
| Sum = This function returns number of chips in the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Number of chips if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceChipID
| HeSym = ===
| Sum = This function returns the ID of chip of the detector connected to the readout device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip in the device, starting from zero
| chipIDBuffer – buffer where the chipID of the detector will be saved. Cannot be NULL
| size - size of the supplied chipID buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = char id[50];
int rc = pxcGetDeviceChipID(deviceIndex, 0, id, 50);
if (rc==0) printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, id);
else printf("pxcGetDeviceChipID failed, code: %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceSerial
| HeSym = ===
| Sum = This function returns the devise serial number.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex - index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceDimensions
| HeSym = ===
| Sum = This function gets pixel width and height of the device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned *w, unsigned *h
| deviceIndex - index of the device, starting from zero
| w – pointer to unsigned variable where the width of the device will be returned
| h – pointer to unsigned variable where the height of the device will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned w, h;
int rc = pxcGetDeviceDimensions(deviceIndex, &w, &h);
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);
else printf("pxcGetDeviceDimensions failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBias
| HeSym = ===
| Sum = This function gets the bias voltage (high voltage) of the sensor chip.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* bias
| deviceIndex – index of the device, starting from zero
| bias – pointer to double variable where current bias will be returned
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double bias;
int rc = pxcGetBias(deviceIndex, &bias);
if (rc==0) printf("Bias: %f V\n", bias);
else printf("pxcGetBias failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetBiasRange
| HeSym = ===
| Sum = This function gets the range of the allowed minimal and maximal bias values.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* minBias, double* maxBias
| deviceIndex - index of the device, starting from zero
| minBias – pointer to double variable where minimum allowed bias will be returned
| maxBias – pointer to double variable where maximum allowed bias will be returned
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetBiasRange(deviceIndex, &min, &max);
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);
else printf("pxcGetBiasRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetBias
| HeSym = ===
| Sum = This function sets the high voltage (bias) of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double bias
| deviceIndex - index of the device, starting from zero
| bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcGetThreshold
| HeSym = ===
| Sum = This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double* threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double thl;
int rc = pxcGetThreshold(deviceIndex, &thl);
if (rc==0) printf("Threshold: %f\n", thl);
else printf("pxcGetThreshold failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetThresholdRange
| HeSym = ===
| Sum = This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| minThreshold – pointer to double variable where the minimal allowed threshold will be returned
| maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = double min, max;
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);
else printf("pxcGetThresholdRange failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetThreshold
| HeSym = ===
| Sum = This function sets the threshold of the detector in KeV.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned thresholdIndex, double threshold
| deviceIndex - index of the device, starting from zero
| thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
| threshold – detector threshold in keV.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Too low thl value cause many noising pixels with all related problems.
| Exa = int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.
}}

{{ApiBinaryItem
| Nam = pxcGetDAC
| HeSym = ===
| Sum = This function gets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – pointer to output value be stored
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned short val;
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);
else printf("pxcGetDAC failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetDAC
| HeSym = ===
| Sum = This function sets a single DAC value of the detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value
| deviceIndex – index of the device, starting from zero
| chipIndex – index of the chip, starting from zero
| dacIndex – index of the DAC, starting from zero
| value – new DAC value
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixClock
| HeSym = ===
| Sum = This function gets the current value of measurement clock for Timepix detector (in MHz).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* clock
| deviceIndex – index of the device, starting from zero
| clock – pointer to double variable where the clock will be saved
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| War =
| Exa = double val;
int rc = pxcGetTimepixClock(deviceIndex, &val);
if (rc==0) printf("Timepix clock: %f MHz\n", val);
else printf("pxcGetTimepixClock failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixClock
| HeSym = ===
| Sum = This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock
| deviceIndex – index of the device, starting from zero
| clock – desired value of the measurement clock for Timepix detector
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.
| Exa = int rc = pxcSetTimepixClock(deviceIndex, 25.0);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepixMode
| HeSym = ===
| Sum = This function gets the current value of the Timepix mode (Counting, Energy,…)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
: Timepix mode can be:
: PXC_TPX_MODE_MEDIPIX – counting mode
: PXC_TPX_MODE_TOT – energy mode
: PXC_TPX_MODE_TIMEPIX – timepix mode if successful.<br>
: Otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcGetTimepixMode(deviceIndex);
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", deviceIndex, rc);
else printf("pxcGetTimepixMode failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixMode
| HeSym = ===
| Sum = This function sets the value of Timepix mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix mode. One of the values:<br>
: PXC_TPX_MODE_MEDIPIX – counting mode<br>
: PXC_TPX_MODE_TOT – energy mode<br>
: PXC_TPX_MODE_TIMEPIX – timepix mode
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| War =
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| Exa = int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX
}}

{{ApiBinaryItem
| Nam = pxcSetTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0
}}

{{ApiBinaryItem
| Nam = pxcIsTimepixCalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code
| Not = Only for the Timepix devices, not usable on Timepix3 and other TimepixN.
| War =
| Exa = int rc = pxcIsTimepixCalibrationEnabled(0);
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetTimepix2Clock
| HeSym = ===
| Sum = This function gets the current clocks settings in the Timepix2 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double* totClock, double* toaClock, unsigned* divider
| deviceIndex – index of the device, starting from zero
| totClock – pointer to double variable where the ToT clock (in MHz) will be saved
| toaClock – pointer to double variable where the ToA clock (in MHz) will be saved
| divider – pointer to unsigned int variable where the divider value will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed
clock of 40 MHz.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Clock
| HeSym = ===
| Sum = This function sets Timepix2 detector clocks settings.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double clock, unsigned divider
| deviceIndex – index of the device, starting from zero
| clock – desired new value of the ToT clock (in MHz) for the Timepix2 detector. The real frequency will be nearest possible division by 2’s power from the 50 MHz. Min is 1.5625 MHz.
| divider – value of the ToA divider index.
:Values means 0: disable, 1: no division, 2-30: div. by 2<sup>n-1</sup>.
:The ToA clock will be divided from the ToT clock.
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix. Timepix3 have a fixed clock of 40 MHz.
| War = The factory energy calibration is only for the 50 MHz ToT clock. Do not change ToT clock if using calibration or if you plan to post-calibrate the data.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2Mode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – new value of the Timepix2 mode. One of the values:
:PXC_TPX2_OPM_TOT10_TOA18
:PXC_TPX2_OPM_TOT14_TOA14
:PXC_TPX2_OPM_CONT_TOT10_CNT4
:PXC_TPX2_OPM_CONT_TOT14
:PXC_TPX2_OPM_CONT_TOA10
:PXC_TPX2_OPM_CONT_TOA14
:PXC_TPX2_OPM_CONT_CNT10
:PXC_TPX2_OPM_CONT_CNT14
:PXC_TPX2_OPM_ITOT10_TOA18
:PXC_TPX2_OPM_ITOT14_TOA14
:PXC_TPX2_OPM_CONT_ITOT10_CNT4
:PXC_TPX2_OPM_CONT_ITOT14
:;Modes desctiption
::TOT – time over threshold in ToT ticks, or energy in keV if calibrated
::TOA – time of arrival in ToA ticks
::CNT – count of hits
::ITOT – integrated time over threshold in the pixel, or estimate energy if calibrated
::CONT – continual mode: One counter set counting while reading data from other counter set
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AdaptiveGainMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool adaptiveGainOn
| deviceIndex – index of the device, starting from zero
| adaptiveGainOn – enable the adaptive gain feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2AnalogueMaskingMode
| HeSym = ===
| Sum = This function sets the value of Timepix2 mode
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool analogMaskOn
| deviceIndex – index of the device, starting from zero
| analogMaskOn – enable the analogue masking feature
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function enables or disables the calibration of Timepix ToT counts to energy in keV
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if the calibration is enabled or disable
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix2CalibrationEnabled
| HeSym = ===
| Sum = This function returns if the calibration of Timepix ToT counts to energy in keV is enabled
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Different acquisition or frame reading functions needed if calibration is on or off.
:Only for the Timepix2 devices, not usable on Timepix3 and other Timepix.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3Mode
| HeSym = ===
| Sum = Sets the operation mode of Timepix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int mode
| deviceIndex – index of the device, starting from zero
| mode – mode of the detector PXC_TPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Enables/disables the calibration of Timepix3 ToT counts to energy in keV. If enabled, output of a frame maesurements on the device will be calibrated.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if calibraiton is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Calibration working properly only if the device has loaded proper config.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsTimepix3CalibrationEnabled
| HeSym = ===
| Sum = Gets if the calibration of Timepix3 ToT counts to energy in keV is enabled. See [[#pxcSetTimepix3CalibrationEnabled|pxcSetTimepix3CalibrationEnabled]] for details.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = enabled > 0, disabled = 0, error < 0 – the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3OperationMode
| HeSym = ===
| Sum = Sets the operation mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int opMode
| deviceIndex – index of the device, starting from zero
| opMode – mode of the detector PXC_MPX3_OPM_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3GainMode
| HeSym = ===
| Sum = Sets the gain mode of Medipix3 detector
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int gain
| deviceIndex – index of the device, starting from zero
| gain – mode of the detector PXC_MPX3_GAIN_MOD_XXX values
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3AcqParams
| HeSym = ===
| Sum = Sets acquisition parameters for Medipix3
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool colorMode, bool csm, int gain, bool equalize
| deviceIndex – index of the device, starting from zero
| colorMode – if color mode is enabled
| csm – if charge sharing mode is enabled
| gain – gain settings (PXC_MPX3_GAIN_XXX values)
| equalize – if equalization bit in Medipix3 is enabled
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepixes or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetMedipix3MatrixParams
| HeSym = ===
| Sum = Sets parameters of the Meidpix3 pixel matrix
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, int depth, int counter, int colBlock, int rowBlock
| deviceIndex – index of the device, starting from zero
| depth – depth of the counters PXC_MPX3_CNTD_XXX values
| counter – selected counter (PXC_MPX3_CNT_XXX values)
| colBlock – region of interest readout (PXC_MPX3_COLB_XXX values)
| rowBlock – region of interest readout (PXC_MPX3_ROWB_XXX values)
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

== Pixel matrix and masks management ==
This section contains:
* Management of pixel matrix configuration (low-level settings of each pixel)
* Management of masking bad/noisy pixels

'''New''': Since version 1.8.5 there are '''two masks''':
# '''Device mask''' - Confirmed bad pixels to be normally masked.
# '''User mask''' - Additional mask - User experiments playground. Can be simply cleared without lost of normal mask.

See also: [[#Interpolating_of_bad_pixels|#Interpolating of bad pixels]]

{{ApiBinaryItem
| Nam = pxcSetPixelMatrix
| HeSym = ===
| Sum = Sets the pixel matrix configuration. This is low level function for advanced users.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* pixCfgData, unsigned size
| deviceIndex – index of the device, starting from zero
| pixCfgData – pixel configuration data - TPXPixCfg, MPX3PixCfg, TPX3PixCfg, ... encoded bytes
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetPixelMaskMatrix
| HeSym = ===
| Sum = Gets the Device Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetUserMaskMatrix
| HeSym = ===
| Sum = Sets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – matrix setting which pixels are masked (PXC_PIXEL_MASKED = 0) and not masked (PXC_PIXEL_UNMASKED = 1)
| size – size of the mask matrix
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetUserMaskMatrix
| HeSym = ===
| Sum = Gets the User Mask Matrix.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned char* maskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| maskMatrix – buffer where the mask matrix will be stored. 0 masked, 1 unmasked
| size – size of the mask matrix
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcClearUserMask
| HeSym = ===
| Sum = Clears the User Mask (unmasks all pixels in user mask).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcFindNoisyPixels
| HeSym = ===
| Sum = Finds noisy pixels
:* Can optionally mask found pixelt in User mask (doMaskNoisyPixels)
:* Can optionally save mask matrix to pointed array (noisyPixelsMatrix != NULL)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double limitNoisy = 50, double limitSatur = 50, bool doMaskNoisyPixels = false, unsigned* noisyPixelsMatrix = nullptr, unsigned matrixSize = 65536
| deviceIndex – index of the device, starting from zero
| limitNoisy – limit [hits] to mask noisy pixels. It goes from 1 to max count value (currently only 1022), where 1 is the most strongest masking and max is the weakest.
| limitSatur – limit [%] to mask saturated pixels. The iToT is used, if the device has this feature. It goes from 0 to 100, where 0 is the most strongest masking and 100 is the weakest.
| doMaskNoisyPixels – check to mask noisy pixels within the process. Default is false alias do not mask.
| noisyPixelsMatrix – mask/positions of noisy pixels.
| matrixSize – size of the matrix.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Currently '''Tpx3 only'''.
| War = Must be run only when the device is in environment WITHOUT radiation background.
| Exa =
}}

== Metadata ==
Various devices, readout chips, detector chips and measurement methods have various metadata. To obtain informations about all relevant metadata for your purphose, set-up and run the testmeasurement with file-saving (using test code or Pixet program). Now you can read the accompanying DSC/INFO files, that contains all metadata for this combination of device/detector/measurement.<br>
[[File:Frames and description files screenshot.png|frame|right|alt=Frames and description files screenshot|Frames and description files screenshot]]
;Example DSC records
:"Chips layout" ("Order of chips in matrix"):
:i32[5]
:4 3 0 1 2
:
:"Start time" ("Acquisition start time"):
:double[1]
:1659611081.595321
:
:"Start time (string)" ("Acquisition start time (string)"):
:char[64]
:Thu Aug 4 13:04:41.595321 2022

{{ApiBinaryItem
| Nam = pxcGetMetaDataValue
| HeSym = ===
| Sum = This function gets measured data meta data value. Output value is converted to char*.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned dataIndex, const char* metaDataName, char* valueBuffer, unsigned* size
| deviceIndex – index of the device, starting from zero
| dataIndex - index of the measured data (frame), starting from zero
| metaDataName – name of the metadata to get, "Start time" for example.
| valueBuffer – buffer where the value of the meta data as string will be stored
| size – pointer to size of the supplied buffer
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = '''Metadata names''' obtaining: Save some frame to file and see the avalilable metadata to a .dsc file saved with the image. Some image formats do not store metadata externally. Use e.g. txt, pmf, bmf.
| War =
| Exa = char mdb[200]; // metadata buffer
unsigned mdbs = 200; // metadata buffer size
char mdn[] = "Start time"; // metadata name

int rc = pxcGetMetaDataValue(deviceIndex, frameLastIndex, mdn, mdb, &mdbs);
if (rc != 0) errorToList("pxcGetMetaDataValue", rc);
else msgToList("Acquisition start time: " + gcnew String(mdb));
}}

== Parameter Get/Set functions (using text paramName) ==
In this chapter are a functions that working with named parameters. Alias '''readout parameters''': Because originally it was only about the parameters of the readout chips. Later, the setting of other device and software parameters was also added.<br>
<br>
'''For dirrect setting functions see:''' [[#Parameter_Get/Set_functions_(direct)|Parameter Get/Set functions (direct)]]<br>
<br>
'''Example:'''
<syntaxhighlight lang="C">
// Data Driven Block Size [B], default 66000
rc = pxcSetDeviceParameter(deviceIndex, "DDBlockSize", 6000);
printf("pxcSetDeviceParameter %d", rc);
</syntaxhighlight>
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''

{{ApiBinaryItem
| Nam = pxcGetDeviceParameter
| HeSym = ===
| Sum = Returns the value of integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameter
| HeSym = ===
| Sum = Sets a value of the integer device parameter (e.g. settings of trigger)
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, int parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterDouble
| HeSym = ===
| Sum = Returns the value of device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to double variable where the parameter value will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterDouble
| HeSym = ===
| Sum = Sets a value of the device double parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, double parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceParameterString
| HeSym = ===
| Sum = Returns the value of device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue, unsigned size
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – pointer to string buffer where the parameter value will be saved
| size – size of the passed buffer
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetDeviceParameterString
| HeSym = ===
| Sum = Sets a value of the device string parameter
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* parameterName, const char* parameterValue
| deviceIndex – index of the device, starting from zero
| parameterName – name of the device parameter
| parameterValue – new value of the parameter
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

=== Tpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_DUMMYACQ "DummyAcqNegativePolarity"
#define PAR_TEMP "Temperature"
#define PAR_TEMP_CHIP "TemperatureChip"
#define PAR_TEMP_CPU "TemperatureCpu" // mimipix/tpx3 only
#define PAR_TEMP_CHIP_CPU "TemperatureChipCpu" // mimipix/tpx3 only
#define PAR_TEMP_READ_ACQSERIE "TemperatureReadBeforeAcqSerie" // mimipix/tpx3 only
#define PAR_TEMP_READ_EVERYACQ "TemperatureReadBeforeEachAcq" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_SW "CheckMaxTempInSW" // mimipix/tpx3 only
#define PAR_TEMP_CHECK_IN_CPU "CheckMaxChipTempInCPU" // mimipix/tpx3 only
#define PAR_TEMP_MAX_ALLOWED_TEMP "MaxAllowedChipTemp" // mimipix/tpx3 only
#define PAR_DAC_BANGAP "DacBandGap"
#define PAR_DAC_TEMP "DacTemp"
#define PAR_BIAS_SENSE_VOLT "BiasSenseVoltage"
#define PAR_BIAS_SENSE_CURR "BiasSenseCurrent"
#define PAR_DD_BUFF_SIZE "DDBuffSize"
#define PAR_DD_BLOCK_SIZE "DDBlockSize"
#define META_SHUTTER_TIME "Shutter open time" // mimipix/tpx3 only
#define PAR_CHAN_MASK "ChanMask" // no net/tpx3
#define PAR_READOUT_CLOCK "ReadoutClock" // no net/tpx3
#define PAR_TRG_STG "TrgStg"
#define PAR_TRG_TIMESTAMP "TrgTimestamp"
#define PAR_TRG_T0SYNC_RESET "TrgT0SyncReset"
#define PAR_TRG_READY "TrgReady" // no net/tpx3
#define PAR_TRG_OUTLEVEL "TrgOutLevel" // mimipix/tpx3 only
#define PAR_TRG_OUT_ENABLE "TrgOutEnable" // mimipix/tpx3 only
#define PAR_TRG_IS_MASTER "IsMaster"
#define PAR_MOTOHOURS "Motohours" // mimipix/tpx3 only
#define PAR_MTX "MTX" // mimipix/tpx3 only
#define PAR_SEND_TOA_PIXELS "SendDummyToaPixels" // mimipix/tpx3 only
#define PAR_DUMMYSPEED "DDDummyDataSpeed" // no mimipix/tpx3
#define PAR_BLOCKCOUNT "BlockCount" // no mimipix/tpx3
#define PAR_PROCESSDATA "ProcessData" // no mimipix/tpx3
#define PAR_TRG_MULTI "TrgMulti" // no mimipix/tpx3
#define PAR_ADVAPIX_ADC "AdvaPixADC" // no mimipix/tpx3
#define PAR_TRG_READY "TrgReady" // zem only
#define PAR_TRG_CMOS "TrgCmos" // zem only
#define PAR_READOUT_CLOCK "ReadoutClock" // zem only
</syntaxhighlight>

=== Tpx2 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_BIAS_SENSE_VOLT = "BiasSenseVoltage";
const static char* PAR_BIAS_SENSE_CURR = "BiasSenseCurrent";
const static char* PAR_READOUT_CLOCK = "ReadoutClock";
const static char* PAR_TRG_STG = "TrgStg";
const static char* PAR_TRG_IS_MASTER = "IsMaster";
const static char* PAR_MOTOHOURS = "Motohours";
const static char* PAR_TEMP_CPU = "TemperatureCpu";
const static char* PAR_TEMP_MAX_ALLOWED_TEMP = "MaxAllowedChipTemp";
const static char* PAR_POWER_VOLT = "PowerSupplyVoltage";
const static char* PAR_CPU_SUPPLY_VOLT = "CPUSupplyVoltage";
const static char* PAR_CHIP_LDO_VOLT = "ChipLDOVoltage";
const static char* PAR_INPUT_CURRENT = "DeviceInputCurrent";
const static char* PAR_CHIP_CURRENT = "ChipCurrent";
</syntaxhighlight>

=== Mpx2 (Timepix) parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer" // all, include minipixes
#define PAR_DEBUGLOG "DebugLog" // all, include minipixes
#define CFG_BINPIXCFG "BinaryPixelCfg" // fei-minipix only
#define PAR_FIRMWARE "Firmware" //widepix only
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_TEMP "Temperature" // no zem
#define PAR_BIASINCPU "BiasInCpu" // widepix only
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_ALTERNATIVE "TriggerAlternative" // fitpix only
#define PAR_TRG_TWODEVS "TriggerTwoDevs" // fitpix only
#define PAR_BURST_DISABLE "BurstDisable" // fitpix only
#define PAR_CPU_BIAS_SET "*BiasSet" // widepix only
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt" // widepix only
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr" // widepix only
#define PAR_CPU_TEMP_DET "TempDet" // widepix only
#define PAR_FASTACQ "FastAcq" // zem only
#define PAR_BURST_FRAME_COUNT "BurstFrameCount" // zem only
#define PAR_PIXEL_BUFFSIZE "PixelBuffSize" // zem only
</syntaxhighlight>

=== Mpx3 parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_TEMP "Temperature"
#define PAR_TRG_STG "TriggerStg"
#define PAR_TRG_WAITREADY "TriggerWaitForReady"
#define PAR_TRG_MASTER "TriggerMaster"
#define PAR_TRG_OUTLEVEL "TriggerOutLevel"
#define PAR_TRG_SERIES "TriggerTdiSeries"
#define PAR_TDI_ROWCOUNT "TdiRowCount"
#define PAR_BIASINCPU "BiasInCpu"
#define PAR_BIAS_DISCHARGE "BiasDischarge"
#define PAR_CPU_BIAS_SET "*BiasSet"
#define PAR_CPU_BIAS_VOLTSENSE "BiasVolt"
#define PAR_CPU_BIAS_CURRSENSE "BiasCurr"
#define PAR_CPU_TEMP_DET "TempDet"
</syntaxhighlight>

=== Zest-wpxdev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
const static char* PAR_LIBVER = "HwLibVer";
const static char* PAR_FIRMWARE = "Firmware";
const static char* PAR_FIRMWARE_CPU = "FirmwareCpu";
const static char* PAR_DEBUGLOG = "DebugLog";
const static char* PAR_TEMP = "Temperature";
const static char* PAR_TRG_STG = "TriggerStg";
const static char* PAR_TRG_WAITREADY= "TriggerWaitForReady";
const static char* PAR_TRG_MASTER = "TriggerMaster";
const static char* PAR_TRG_OUTLEVEL = "TriggerOutLevel";
const static char* PAR_BIAS_DISCHARGE = "BiasDischarge";
</syntaxhighlight>

=== Zem-wpx7dev parameter names list ===
----
'''Warning: Most parameters are for testing purposes only and you will not need them in normal use.'''
<syntaxhighlight lang="C">
#define PAR_LIBVER "HwLibVer"
#define PAR_DEBUGLOG "DebugLog"
#define PAR_PS_COUNT "PreShutterClockCount"
#define PAR_PS_DIVIDER "PreShutterClockDivider"
#define PAR_PS_DELAY "PreShutterDelayClockCount"
#define PAR_ENC_PULSE_CNT "EncoderPulseCount"
#define PAR_ENC_PULSE_DIR "EncoderDirection"
#define PAR_ENC_PULSE_COUNTER "EncoderPulseCounter"
</syntaxhighlight>

== Other auxilliary functions ==
{{ApiBinaryItem
| Nam = pxcLoadFactoryConfig
| HeSym = ===
| Sum = This function loads device factory configuration. If the device has no intermal config memory, need the factory config file (with default config filename) in the factory directory. Use it if he measurement results or device behavior are strange, or allways by default.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = int rc = pxcLoadFactoryConfig(deviceIndex);
if (rc!=0) errorToList("pxcLoadFactoryConfig", rc);
}}

{{ApiBinaryItem
| Nam = pxcLoadDeviceConfiguration
| HeSym = ===
| Sum = This function loads device configuration from xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveDeviceConfiguration
| HeSym = ===
| Sum = This function saves device configuration to xml file
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| filePath – path to xml configuration file
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetupTestPulseMeasurement
| HeSym = ===
| Sum = Enables / Disables and setups parameters of the test pulse measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool tpEnabled, double height, double period, unsigned count, unsigned spacing
| deviceIndex – index of the device, starting from zero
| tpEnabled – enables/disables test pulse measurement (in functions Measure..Frame(s))
| height – test pulse height (0 – 1.5 V)
| period – single test pulse period (1 – 256 us)
| count – number of test pulses (1 – 10000)
| spacing – spacing that is used during measurement (sub acquisition), good value is 4
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRegisterAcqEvent
| HeSym = ===
| Sum = Registers an acquisition event callback that is called when corresponding event occurs
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqEventFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqEventFunc
| userData – user data that are passed to callback function. Use this as pointer or as 32/64bit integer, depending on system pointer size. The callback function will receive the userData value.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

The AcqEventFunc definition:
<syntaxhighlight lang="C">
typedef void (*AcqEventFunc)(intptr_t eventData, intptr_t userData);
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcUnregisterAcqEvent
| HeSym = ===
| Sum = Unregisters the acquisition event callback
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, const char* event, AcqFunc func, intptr_t userData
| deviceIndex – index of the device, starting from zero
| event – event name (PXC_ACQEVENT_XXX values)
| func – callback function of type AcqFunc
| userData – user data pointer that was used in pxcRegisterAcqEvent, for proper indetify the event
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSetSensorRefresh
| HeSym = ===
| Sum = Sets the sensor refresh sequence text. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes. Suitable values depend on chip manufacturing technology details.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
| refreshString – sensor refresh string
: refresh string defines steps with pairs of times <nowiki>[sec] and bias coefficients [1=100%]</nowiki>
: (physical bias values limited to min/max chip properties, see pxcGetBiasRange)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Special function for scientific or device developing using. Normally it not usesfull, normally use the default refresh parameters loaded from factory config.
| Exa = // (devIdx, "time1, coef1; time2, coef2; time3, coef3; ...")
int rc = pxcSetSensorRefresh(0, "5, 2; 3, 1.5; 1, 1.2; 1, 1");
printErrors("pxcSetSensorRefresh", rc, ENTER_ON);
}}

{{ApiBinaryItem
| Nam = pxcDoSensorRefresh
| HeSym = ===
| Sum = Performs the sensor refresh. The sensor refresh is used to clean the sensor of free charges. Process containing sequence of bias changes and may take several seconds.
:Useful for devices with '''CdTe or CZT chip''':
# Before the measurement, which should start right after the initialization.
# To improve the repeatability of measurements
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableSensorRefresh
| HeSym = ===
| Sum = Enables automatic sensor refresh before each acquisition series and at periodic intervals.
: For more details see: pxcDoSensorRefresh
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled, double refreshTime
| deviceIndex – index of the device, starting from zero
| enabled – if automatic sensor refresh is enabled
| refreshTime – sensor refresh is performed repeatedly after this time in seconds.
:If thime is 0, then the refresh is done only once before the measurement
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This is an '''analog part refresh''', not a recovery from a digital failure.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcEnableTDI
| HeSym = ===
| Sum = Enables TDI (Time Delayed Integration) measurement (if device supports it, single line Mpx3 for example). Usesful for scanning of linearly moving objects.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, bool enabled
| deviceIndex – index of the device, starting from zero
| enabled – if TDI is enabled
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = It is not advisable to combine TDI and pxcMeasureContinuous.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcIsReadyForSoftwareTrigger
| HeSym = ===
| Sum = Checks if the device is ready to accept software trigger.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 1 if ready, 0 if not ready, and negative if error, PXCERR_XXX code.
| Not = If you want to use this immediately after a function for starting acquisition, wait until it's ready by using pxcIsReadyForSoftwareTrigger.
| War =
| Exa = int rc = pxcIsReadyForSoftwareTrigger(deviceIndex);
if (rc==1) msgToList("Dev is ready to SW trigger");
else if (rc==0) msgToList("Dev is not ready to SW trigger");
else errorToList("pxcIsReadyForSoftwareTrigger", rc);
}}

{{ApiBinaryItem
| Nam = pxcDoSoftwareTrigger
| HeSym = ===
| Sum = Sends the software trigger: Start of acquisition with trgStg=PXC_TRG_SWSTART used.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-based measuring functions =
[[File:Basic-measuring-example.png|frame|none|alt=Basic frame measuring example|Basic frame measuring example]]
The functions described in this chapter are used for frame-based measurements. Suitable for imaging, for example. After acquisition ends, you can read all the frame data (65536 pixels from every chip) to your buffer or save to the file. Acquisition can start by software (afther call a function, for example), or by HW trigger. Data types depends on chip technology and the operation mode.<br>
<br>
Chip can generate one or two data blocks (event count and integrated times over threshold, for example) in one acquisition. Do not forget to set the operation mode. If mode not set, some devices measure something, but some other devices measure something else in this case.<br>

;Example projects
:MiniPixTpx3-Frames – mode set, single frame, multiple frames with/without callback, continuous measuring

== Frame-based basic measurement flow ==

=== Prereguirements ===
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: (pxcSet...Mode '''by the chip type''' - [[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] for example)
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition

=== Single frame measurement ===
Run the measuring function pxcMeasureSingleFrame... '''by the chip type''' - [[Binary_core_API#pxcMeasureSingleFrameTpx3|'''pxcMeasureSingleFrameTpx3''']] for example, for measure and get the data to Your buffer.
* Simple
* Slow if more frames needed

Notes:
* The '''pxcMeasureSingleFrame''' is for '''obsolette''' first generation Timepix chips only.
* The '''Calibrated''' variants requires proper config including calibration table and threshold + other related settings in factory defaults (or values used in custom calibration).

=== Multiple frames without callback ===
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFrames|'''pxcMeasureMultipleFrames''']]
# Optional get count of measured frames: [[Binary_core_API#pxcGetMeasuredFrameCount|'''pxcGetMeasuredFrameCount''']]
# Optional save some measured frame: [[Binary_core_API#pxcSaveMeasuredFrame|'''pxcSaveMeasuredFrame''']]
# Optional get some measured frame to Your buffer using pxcGetMeasuredFrame...'''by the chip type'''. [[Binary_core_API#pxcGetMeasuredFrameTpx2|'''pxcGetMeasuredFrameTpx2''']] for example.

:* Simple
:* Faster than single frame
:* The data is only available after the measurement is finished.
:* Can allocate large memory if too much frames measured.

=== Multiple frames using callbacks ===
# Optional register other callbacks using [[Binary_core_API#pxcRegisterAcqEvent|'''pxcRegisterAcqEvent''']]
# Run the measuring function [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|'''pxcMeasureMultipleFramesWithCallback''']]
# While the measurement is running, callbacks are comingin. There, save the frames to a file or to buffer fot the online processing.
# Optional unregister all first registered callbacks using [[Binary_core_API#pxcUnegisterAcqEvent|'''pxcUnegisterAcqEvent''']]

:* More complex
:* Faster than single frame
:* The data is available while measuring.
:* Can allocate large memory if too much frames measured because the data remains in memory just like without the callback.

=== Multiple frames using callbacks and circular buffer ===
Same as [[Binary_core_API#pxcMeasureMultipleFramesWithCallback|pxcMeasureMultipleFramesWithCallback]] but the [[Binary_core_API#pxcMeasureContinuous|'''pxcMeasureContinuous''']].

* Non-blocking function
* Unlimited number of frames, using circular buffer
* Supports HW-based continuous measurement

== Frame measuring and related functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureSingleFrame
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned short* frameData, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData – pointer to buffer where data will be saved. For single detector size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameMpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Medipix3 chips
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from first counter will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from second counter will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Medipix3 devices, not usable on Timepix or other Medipixes.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx3
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix3 detector.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameToaITot, unsigned short* frameTotEvent, unsigned* size, unsigned trgstg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =void pxcMeasureSingleFrameTpx3Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(di, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx3(di, time, frameToaITot, frameTotEvent, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx3", rc, ENTER_ON);
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame and returns its data. This is only for Timepix2 detector and '''only if calibration is disabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, unsigned* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is disabled.
| War =
| Exa =void pxcMeasureSingleFrameTpx2Test(unsigned di) { // di – device index ========
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned frameData1[cSize]; // frame data - ToT data
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureSingleCalibratedFrameTpx2
| HeSym = ===
| Sum = Performs a measurement of single frame, calibrate ToT to energy and returns data. This is only for Timepix2 detector and '''only if calibration is enabled'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double frameTime, double* frameData1, unsigned* frameData2, unsigned* size, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameTime – time of the measurment in seconds
| frameData1 – pointer to buffer where data from the first counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single detector chip, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
: Only if Timepix2 calibration is enabled.
| War =
| Exa =void pxcMeasureSingleCalibratedFrameTpx2Test(unsigned di) { // di – device index =====
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
double frameData1[cSize]; // frame data - ToT data = calibrated to energy
unsigned frameData2[cSize]; // frame data - ToA data
double time = 1.0; // frame acquisition time
unsigned size = cSize; // buffer size and measured data size
int mode = PXC_TPX2_OPM_TOT10_TOA18;
rc = pxcSetTimepix2Mode(di, mode);
printErrors("pxcSetTimepix2Mode", rc, ENTER_ON);
rc = pxcMeasureSingleCalibratedFrameTpx2(di, time, frameData1, frameData2, &size, PXC_TRG_NO);
printErrors("pxcMeasureSingleCalibratedFrameTpx2", rc, ENTER_ON);
showFrameDual(frameData1, frameData2, mode);
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFrames
| HeSym = ===
| Sum = Performs a measurement of several frames to memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesTpx3Test() { // =========================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
double frameTime = 1.0; // frame acquisition time
unsigned frameCount = 5; // frame count
unsigned size = cSize; // buffer size and measured data size

int mode = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(0, mode);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

printf("measuring %d frames...\n", frameCount);

pxcMeasureMultipleFrames(0, frameCount, frameTime, PXC_TRG_NO);
printErrors("pxcMeasureMultipleFrames", rc, ENTER_ON);
for (unsigned n=0; n<frameCount; n++) {
rc = pxcGetMeasuredFrameTpx3(0, n, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_ON);
size = cSize;
showFrameDual(frameTotEvent, frameToaITot, mode);
}
}
}}

{{ApiBinaryItem
| Nam = pxcMeasureMultipleFramesWithCallback
| HeSym = ===
| Sum = Performs a measurement of several frames to memory. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameCount, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameCount – numeber of frames to measure
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void pxcMeasureMultipleFramesWithCallbackTestTpx3(unsigned deviceIndex) { // ==============
int rc; // return codes
double frameTime = 1;
unsigned frameCount = 5;
tMmfClbData usrData;
usrData.di = deviceIndex;
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);
rc = pxcMeasureMultipleFramesWithCallback
(deviceIndex, frameCount, frameTime, PXC_TRG_NO, mmfCallback, (intptr_t)&usrData);
printErrors("pxcMeasureMultipleFramesWithCallback", rc, ENTER_ON);
// Measure function ends, after all callbacks are serviced
}

void mmfCallback(intptr_t acqCount, intptr_t userData) { // =================================
int rc; // return codes
const unsigned cSize = 65536; // chip pixels count
unsigned short frameTotEvent[cSize]; // frame data - event count
double frameToaITot[cSize]; // frame data - integrated time over threshold
unsigned size = cSize; // buffer size and measured data size
tMmfClbData usrData = *((tMmfClbData*)userData); // data transferred from start function
printf("mmfCallback acqCount=%d, di=%d\n", (unsigned)acqCount, usrData.di);
rc = pxcGetMeasuredFrameTpx3
(usrData.di, (unsigned)acqCount - 1, frameToaITot, frameTotEvent, &size);
printErrors("pxcGetMeasuredFrameTpx3", rc, ENTER_OFF); printf(", size=%d\n", size);
if (rc == 0) {
printf("Measured frame index %lu, ", (unsigned)acqCount - 1);
printf("count %d\n", pxcGetMeasuredFrameCount(usrData.di));
showFrameDual(frameTotEvent, frameToaITot, usrData.opm);
}
}
//The acqCount contains count of measured frames that are currently waiting in memory.
// You can use acqCount-1 as frame index to read.
// The userData is 64b number used to transfer some data from starting function to callback function.
// You can use it as data pointer like in this example, or simply as number with some overtyping.
typedef struct { // structure for userData, that is using in mmfCallback
unsigned di; // device index
int opm; // operation mode
} tMmfClbData;
}}

{{ApiBinaryItem
| Nam = pxcMeasureContinuous
| HeSym = ===
| Sum = Performs an “endless” measurement of several frames to memory. The measurement is run until it’s aborted by pxcAbortMeasurement function. When each frame is measured, the supplied callback function is called and the userData parameter is passed as argument.<br>
: If the readot chip supposrt it, this function starts the HW continous mode (MPX3, TPX2). This means that the counters are alternating and at the same time measurement is being made with one and measurement data is being sent from the other. Therefore, up to a certain FPS, measurement is taking place 100% of the time.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameBufferSize, double frameTime, unsigned trgStg, FrameMeasuredCallback callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| frameBufferSize – number of frames in circular buffer
| frameTime – time of the measurment in seconds
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO.
| callback – pointer to function of FrameMeasuredCallback type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =''' '''
* This function, differently to other multi-frame measurements, not waiting for process end. It simply start measurement and program continue next.
* You can set-up the callback by 2 ways:
# Simply use pointer to callback function in the '''pxcMeasureContinuous''' function. After do it, the commandline program must not leave the function in which pxcMeasureContinuous was used until the measurement is canceled.
# First use the '''pxcRegisterAcqEvent''' to set-up the callback, second use pxcMeasureContinuous without callback pointer or with NULL. Now it is possible to leave the superior function and measuring continue working independent. Afther cancel of the measurement, may be needed use the '''pxcUnregisterAcqEvent''' before other use of the Acq event.
| War =''' '''
* Aborting measuremet from its callback (like as in commandline example bellow) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
* This function may cause problems if combined with TDI. Recommend use the pxcMeasureMultipleFramesWithCallback.
| Exa =void pxcMeasureContinuousTestTpx3(unsigned deviceIndex) { // ==============================
int rc; // return codes
double frameTime = 2;
unsigned buffrerFrames = 3;
tMmfClbData usrData;
usrData.di = deviceIndex;

usrData.cnt = 0; // num of frames to stop in callback (0 endless)
usrData.opm = PXC_TPX3_OPM_EVENT_ITOT;
rc = pxcSetTimepix3Mode(deviceIndex, usrData.opm);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

// method 1 (single step):
//rc = pxcMeasureContinuous (deviceIndex, buffrerFrames, frameTime, PXC_TRG_NO, mcCallback, (intptr_t)&usrData);
//printErrors("pxcMeasureContinuous", rc, ENTER_ON);
// method 2 (2 steps):
// register event
pxcRegisterAcqEvent(0, PXC_ACQEVENT_ACQ_FINISHED, mcCallback, (intptr_t)&usrData);
printErrors("pxcRegisterAcqEvent", rc, ENTER_ON);

// start continuous measuring (method 2, step 2)
rc = pxcMeasureContinuous(deviceIndex, buffrerFrames, frameTime);
printErrors("pxcMeasureContinuous", rc, ENTER_ON);

printf("waiting for callbacks...\n");
getchar(); // waiting so that callbacks can come
printf("pxcMeasureContinuousTest: user end\n");
}
/*The callback function is some as used in pxcMeasureMultipleFramesWithCallback example, but usrData structure contains
extra member, the cnt.This can be used to stop, whitch is additional in the callback: */

static unsigned cnt = 0;
cnt++;
if (usrData.cnt > 0 && cnt >= usrData.cnt) {
// stop continuous measuring on user defined number of frames
printf("pxcAbortMeasurement...");
rc = pxcAbortMeasurement(usrData.di);
printErrors("pxcAbortMeasurement", rc, ENTER_ON);
printf("Press enter to exit the program.\n");
}
}}

{{ApiBinaryItem
| Nam = pxcAbortMeasurement
| HeSym = ===
| Sum = Stopts the currently running measurement on the indexed device.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War = Aborting measuremet from its callback (like as in commandline example in pxcMeasureContinuous) can cause lags for tens of seconds. If the pxcAbortMeasurement called by other way (Button event in GUI for example), abort is fast.
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameCount
| HeSym = ===
| Sum = Returns number of measured frames in memory. Usesful with pxcMeasureMultipleFrames.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex
| deviceIndex – index of the device, starting from zero
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcSaveMeasuredFrame
| HeSym = ===
| Sum = Saves the measured frame to a file on the harddrive. This can be used instead of the pxcGetMeasuredFrame.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, const char* filePath
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| filePath – path to the file where frame will be saved
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =void someCallback(intptr_t acqCount, intptr_t userData) { // ======================
int rc; // return codes
tMmfClbData usrData = *((tMmfClbData*)userData);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.txt");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
rc = pxcSaveMeasuredFrame(usrData.di, (unsigned)acqCount - 1, "testFile.png");
printErrors("pxcSaveMeasuredFrame-txt", rc, ENTER_ON);
/* List of file extensions (format automatically detected by extension in filename):
#define PX_EXT_ASCII_FRAME "txt"
#define PX_EXT_BINARY_FRAME "pbf"
#define PX_EXT_MULTI_FRAME "pmf"
#define PX_EXT_BINARY_MULTI_FRAME "bmf"
#define PX_EXT_COMP_TPXSTREAM "pcts"
#define PX_EXT_TPX3_PIXELS "t3p"
#define PX_EXT_TPX3_PIXELS_ASCII "t3pa"
#define PX_EXT_TPX3_RAW_DATA "t3r"
#define PX_EXT_FRAME_DESC "dsc"
#define PX_EXT_INDEX "idx"
#define PX_EXT_CLUSTER_LOG "clog"
#define PX_EXT_PIXEL_LOG "plog"
#define PX_EXT_PNG "png"
#define PX_EXT_PIXET_RAW_DATA "prd"
(t3.. formats not frames - cannot be used with pxcSaveMeasuredFrame) */
}
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrame
| HeSym = ===
| Sum = Gets data of specified measured frame from memory
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, unsigned short* frameData, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData – pointer to buffer where data will be saved. For single chip detector size is 65536.
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable.
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =This function have only one framebuffer. This is fully sufficient for single-output devices and modes. In combined modes (ToA+ToT, Event+IToT, dual threshold) only first data are available (ToA, Event, Threshold0). To take both outputs from the combined modes, it is necessary to use specialized functions for the given type of detector.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame from memory.
:For Timepix2 chip only and only if '''calibration disabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, unsigned* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration disabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredCalibratedFrameTpx2
| HeSym = ===
| Sum = Gets data of specified measured frame with calibration from memory.
:For Timepix2 chip only and only if '''calibration enabled'''.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned frameIndex, double* frameData1, unsigned* frameData2, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameData1 – pointer to buffer where calibrated ToT->Energy data from the first counter (based on set operationmode) will be saved. For single detector chip size is 65536
| frameData2 – pointer to buffer where data from the second counter (based on set operation mode) will be saved. For single chip detector size is 65536
| size - pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix2 devices, not usable on other Timepixes or Medipixes.
:For Timepix2 chip only and only if '''calibration enabled'''.
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredFrameTpx3
| HeSym = ===
| Sum = Gets data of specified measured frame from memory. For Timepix3 chip only.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned fameIndex, double* frameToaITot, unsigned short* frameToTEvent, unsigned* size
| deviceIndex – index of the device, starting from zero
| frameIndex – index of the frame, starting from zero
| frameToaITot – pointer to buffer where data from ToA or iToT counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| frameTotEvent – pointer to buffer where data from ToT or Event counter (based on set operation mode) will be saved. For single chip detector, size is 65536
| size – pointer to varible with the size of the buffer. The actual size will be output to this variable
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Only for the Timepix3 devices, not usable on other Timepixes or Medipixes.
| War =
| Exa =
}}

= API data-driven measuring functions =
[[File:Cluster-example.png|right|300px|alt=Data-driven: Cluster example|Data-driven: Cluster example]]
The functions described in this chapter can be used if frame-based measurement is not good choice, in particle collision research, for example.<br>
<br>
'''Data-driven "frameless" in comparsion with frames:'''<br>
:;Advantages
::It is possible to continual measure for any length of time and repeated pixel hits are not lost.
:;Disadvantages
::Each pixel is transmitted as a separate packet, including its position. Therefore, this mode is significantly more demanding on the transmission speed.
<br>
Afther measurement start, data from every event is stored in the buffer. Pixels has structures (defined in the pxcapi.h):
<syntaxhighlight lang="C">
typedef struct _Tpx3Pixel {
double toa; // time of arrival [1 ns]
float tot; // time over threshold [25 ns] or energy [keV] if calibrated
unsigned int index; // pixel position index on device frame
} Tpx3Pixel;

#pragma pack(push, 1)
typedef struct _RawTpx3Pixel {
u32 index: 24; // pixel index on device frame or data lost start/end tags if overflow==1
u64 toa: 64; // time of arrival [25 ns] lower 14b from chip and extension from FPGA+computer *
byte overflow: 1; // overflow sign
byte ftoa: 5; // fast ToA [1/0.64 ns] expanded from 4 to 5 bits as part of phase correction
u16 tot: 10; // time over threshold [25 ns]
} RawTpx3Pixel;
#pragma pack(pop) // * or data lost start/end time if overflow==1
</syntaxhighlight>

Use the RawTpx3Pixel only if it is really necessary.
See warning: [[The_RawTpx3Pixel_structure_in_memory|'''Warning for the RawTpx3Pixel structure in memory''']]<br>

<br>
The Pixet core has a circular buffer in memory. For '''MiniPIX''': The default size is 100 MB. There are blocks in the buffer. The default block size is 66000 bytes. Incoming data is stored in a block. The “new data” event (that can start the callback or save the blockt to file) occurs if:
* The data size reaches the block size
* Some data is in block over the timeout (500 ms)
* The measurement ends
If you need to process data more often, you can set smaller block size. But if blocks are too small, data transfer speed can fall and some data can be lost. This can occurs if block size is less than approximately 5000 bytes (minipix, depends on computer speed and other circumstances).

; Data-driven buffers settings
: Buffer parameters: DDBuffSize, DDBlockSize
: See [[Binary_core_API#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]
; AdvaPIX note
: Has DDBuffSize, DDBlockSize and DDBlockSizeDivider.
: Unlike MiniPIX, BlockSize is in megabytes, as is BufferSize. Smaller Block can be created using Divider.

;Example projects
:'''MiniPixTpx3-DataDriven''', commandline example – Set the parameters, use the callback and display the data, some auxiliary things and data convert. Save data to files. Without threads.
:'''AdvacamAPIexamples/Tpx3''', Windows GUI CLR app – All common functions including data-driven measurements. Using threads.

; Notes
: Data-driven measurements are compatible with the '''TOATOT operation mode only'''.
: Functions in this chapter is '''only for the Timepix3 devices''', not usable on other Timepixes or Medipixes.

== Data-driven special settings ==
{|
|- style="vertical-align:top;"
| <br>
The Pixet core has a circular buffer in memory to receiving new pixels.
* Size of whole buffer is named '''buffer size'''.
* Buffer is divided to blocks with '''block size'''.
Received data is continuously stored to the buffer.
* Every reaching next block, the callback New data occurs or data saved to file.
* At a low event rate, the callback is also called regularly, e.g. 500 ms on MiniPIX, or more on AdvaPIX (1.7 s with defaults).
* When the buffer runs out, the measurement ends with an error.
* If file saving is used, data is not accumulated in the buffer, callbacks do not occur, the buffer never runs out and measurement may by very long.

Default values are optimized for maximum performance on developper's computer. Normally, it is enough to leave these values, but it is possible that by changing them you will speed up the measurement a little or reduce the CPU load on Your computer.

See: [[Binary_core_API#pxcSetDeviceParameter|'''pxcSetDeviceParameter''']], [[Binary_core_API#pxcGetDeviceParameter|'''pxcGetDeviceParameter''']]
|
{| class="wikitable"
|+ DD settings in named (readout) parameters
|-
! Parameter name / description !! MiniPIX Tpx3 !! AdvaPIX Tpx3
|-
| '''DDBuffSize'''<br>Size of whole buffer || [MB]<br>default 100 || [MB]<br>default 2000
|-
| '''DDBlockSize'''<br>Size of each block || [B]<br>default 66000 || [MB]<br>default 5
|-
| '''DDBlockDivider'''<br>Unit divider for smaller blocks on AdvaPIX<br>Divider can shorten the timeout downto ~500 ms. || (has no) || [/MB]<br>default 1
|-
| '''DDDummyDataSpeed'''<br>Virtual data speed of dummy device || (has no) || 24831
|-
| '''DataOverflowCheck'''<br>If an overflow occurs and the check is on, the measurement is immediately terminated with an error. If it is off, the overflow is displayed in the data and the measurement continues to the normal end. || [bool]<br>default 0 || (has no)
|-
| '''BlockCount'''<br>Count of occupied blocks after measurement.<br>(zeroed at start and updated at the end of the measurement) || (has no) || (read)
|}
|}

== Data-driven basic measurement flow ==
'''Required first''' - Use one of options:
* Ensure that pxcInitialize automatically loads the correct device configuration that you received from us or saved after changes. See [[Files_and_directories_of_the_Pixet_and_SDK#The_factory_and_the_configs_subdirectories|'''The factory and the configs subdirectories''']]
* Or load the factory config using [[Binary_core_API#pxcLoadFactoryConfig|'''pxcLoadFactoryConfig''']]
* Or load Your somewhere saved config using [[Binary_core_API#pxcLoadDeviceConfiguration|'''pxcLoadDeviceConfiguration''']]
<br>
'''Second''' or before measurement(s):
* Now change some settings as needed, Operation mode for example: ([[Binary_core_API#pxcSetTimepix3Mode|'''pxcSetTimepix3Mode''']] Only PXC_TPX3_OPM_TOATOT supported for data-driven.
* Change advanced setting like as bias voltage or threshold. Do this only if you know what you need it for and be aware of possible side effects. In data-driven measurement be careful if setting lower than default thresholds, it can cause noising pixels.
<br>
If running in a '''commandline without wait for user''' response - Wait for the sensor chip to stabilize. It prevents unwanted artifacts in the first measurement.
* Wait feve seconds
* Or do sensor refresh
* Or do dummy acquisition
<br>
'''The measurement flow:'''
# Run the measuring function [[Binary_core_API#pxcMeasureTpx3DataDrivenMode|'''pxcMeasureTpx3DataDrivenMode''']]
# Get count of measured pixels: [[Binary_core_API#pxcGetMeasuredTpx3PixelsCount|'''pxcGetMeasuredTpx3PixelsCount''']]
# Get measured data by [[Binary_core_API#pxcGetMeasuredTpx3Pixels|'''pxcGetMeasuredTpx3Pixels''']] to Your buffer.
# Optional [[Binary_core_API#pxcCalibrateTpx3PixelsAndFilter|'''pxcCalibrateTpx3PixelsAndFilter''']] (working properly only if proper configuration with calibration loaded and data measured with default threshold and other related settings)

Note: A "get" steps can be after measurement end (Short measurements only), or in a callback ACQ_NEW_DATA (recommended).

== DD functions list ==
{{ApiBinaryItem
| Nam = pxcMeasureTpx3DataDrivenMode
| HeSym = ===
| Sum = Performs a measurement with Timepix3 detector in Data Driven Mode (event by event mode, when stream of pixels is sent). '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, double measTime, const char* filename, unsigned trgStg, AcqEventFunc callback, intptr_t userData
| deviceIndex – index of the device, starting from zero
| measTime – the total time of the measurement in seconds. Use 0 for infinite.
| filename – output file name and path (extensions must be *.t3pa, *.t3p, *.t3r)
| trgStg – settings of external trigger - one of the PXC_TRG_XXX values. Default PXC_TRG_NO
| callback – pointer to function of acqEventFunc type
| userData – pointer to some user object/memory that is passed in callback function
: See [[Binary_core_API#pxcRegisterAcqEvent|pxcRegisterAcqEvent]] for userData details
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use with callbacks can be combined with a file.
| War =
| Exa = int rc = pxcMeasureTpx3DataDrivenMode(0, 15, "testfile.t3pa");
// Measure for 15 seconds on device 0 with saving to the "testfile.t3pa" file
}}
;Example for online processing
<syntaxhighlight lang="C">
void timepix3DataDrivenGetPixelsTest(unsigned deviceIndex) { // ============================
int rc; // return codes
double measTime = 30;
int devIdx = deviceIndex; // transmitted over pointer for use in the callback function

// working with TOA, TOATOT, TOT_NOTOA, not working with EVENT_ITOT
rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOA);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BLOCK_SIZE, 6000); // block [B]
printErrors("pxcSetDeviceParameter", rc, ENTER_OFF);
rc = pxcSetDeviceParameter(deviceIndex, PAR_DD_BUFF_SIZE, 100); // buffer [MB]
printf(", %d", rc);

rc = pxcMeasureTpx3DataDrivenMode(deviceIndex, measTime, "", PXC_TRG_NO, onTpx3Data, (intptr_t)&devIdx);
printErrors("pxcMeasureTpx3DataDrivenMode", rc, ENTER_ON);
}

// * Data consistency check level : Detection level of ToA data inconsistency.
// If the chip is overloaded due too many partickes in time, clock can freezeand a ToA inconsistency occurrs.
// If it is detedted, measuring immediately stopand error “Acquisition failed(Data flow corrupted !!)“ occurrs.
// Level 50 is some like OFF, level 150 is highest sensitivity.

void onTpx3Data(intptr_t eventData, intptr_t userData) { // ================================
int deviceIndex = *((unsigned*)userData);
unsigned pixelCount = 0;
int rc; // return codes

rc = pxcGetMeasuredTpx3PixelsCount(deviceIndex, &pixelCount);
printErrors("getMeasuredTpx3PixelsCount", rc, ENTER_OFF);
printf(" PixelCount: %u\n", pixelCount);

auto result = new Tpx3Pixel[pixelCount];
rc = pxcGetMeasuredTpx3Pixels(deviceIndex, result, pixelCount);
printErrors("pxcGetMeasuredTpx3Pixels", rc, ENTER_ON);

dataUsingFunction(&result, pixelCount);
delete[] result;
}
</syntaxhighlight>

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3PixelsCount
| HeSym = ===
| Sum = Gets the number of measured Timepix3 pixels in data driven mode. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* pixelCount
| deviceIndex – index of the device, starting from zero
| pixelCount – pointer to output variable for number of pixels
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa = unsigned int cnt;
int rc = pxcGetMeasuredTpx3PixelsCount(0, &cnt);
if (rc==0) printf("%d pixels from device idx 0 are waiting in memory\n", cnt);
else printf("pxcGetMeasuredTpx3PixelsCount failed, code %d\n", rc);
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
: ToT in output data are ToT in 25ns ticks or energy in keVs, depending on Timepix3CalibrationEnabled
: See pxcSetTimepix3CalibrationEnabled, pxcIsTimepix3CalibrationEnabled
| pixelCount – size of the supplied array as number of pixels
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetMeasuredRawTpx3Pixels
| HeSym = ===
| Sum = Gets the measured Timepix3 pixels data in raw format. '''Timepix3 only.'''
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, RawTpx3Pixel* pixels, unsigned pixelCount
| deviceIndex – index of the device, starting from zero
| pixels – buffer where pixels will be saved
| pixelCount – size of pixels buffer (number of pixels to save)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not = Use the pxcGetMeasuredRawTpx3Pixels only in special, exceptional cases.
| War = See: [[The_RawTpx3Pixel_structure_in_memory|The RawTpx3Pixel structure in memory]]
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcCalibrateTpx3PixelsAndFilter
| HeSym = ===
| Sum = Calibrate the pixel data and filter them by energy range
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, Tpx3Pixel* pixels, unsigned* pixelCount, double minEnergy, double maxEnergy
| deviceIndex – index of the device, starting from zero
| pixels – pointer to array of Tpx3Pixels that will be filled with measured pixels
| pixelCount – size of pixels buffer (number of pixels). It will be filled with the number of pixel remaining after filtration
| minEnergy – minimal allowed energy of each pixel
| maxEnergy – maximal allowed energy of each pixel
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

= API frame-data processing functions =
{|
|+
|-
| [[File:Beam-hardening-bh2c.png|left|frame|alt=Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation|Left: raw image, mid: After beam hardening correction, right: after BHC and bad pixels interpolation]]
|}
The functions described in this chapter can be used to compensate the beam hardening effect, uneven distribution of irradiation, bad pixels and chip sensitivity uneven to get the data with true thickness of measured material.

Process summary:
# Measure the correction data to be used in BHC
# Measure the main data
# Apply the Beam hardenning correction
# Apply the Bad pixel correction

== Beam hardening correction ==
First step is adding set of the reference images (masks). Dirrect beam (or beam with filter that will be used in all the process) and flat plates with different thicknesses, optimally in whole range that you want measuring. Use the '''pxcAddBHMask'''. Reference images contains unsigned 32bit pixels. To create the reference pictures, recommended fold more acquired images to achieve pixel values aproximatelly tens of thousands or more (50,000 is good start). Don’t forget corectly set their thickness.<br>
<br>
If 2 or more reference images have been added, it is possible to determine which pixels are not usable. Check this using the '''pxcGetBHBadPixelMatrix''' function. If there are too many of these pixels, the '''pxcApplyBHCorrection''' function may lose accuracy and the '''pxcInterpolateBadPixels''' function will not work. In this case you can check:
* If the set-up is correct (condition of the reference plates; Is the whole area of the chip good irradiated and covered by the reference plates? Is there an obstacle in the beam?)
* If there is too much contrast between the references - a common problem, especially between the free beam and the first reference plate - you can use a filter throughout the process
* If some areas have too low values with high noise - increase the number of integrated frames, beam intensity, or acquisition time
* If exist areas with overexposition – decrease the time or beam intensity
* If the instability of the CdTe chip has manifested itself - increase the time by integrating the reference images
* If using CdTe and measuring start too soon afther chip init
* Try use other beam energy
After add sufficient number of reference images, you can measure image of the sample and use the '''pxcApplyBHCorrection''' function. Output is array of double, in units from reference thicknesses.<br>
<br>
Now you can use the '''pxcGetDeviceAndBHBadPixelMatrix''' to get array of bad and other unusable pixels. Use this data with the '''pxcInterpolateBadPixels'''. If it doesn't work, you can use only device bad pixels from the '''pxcGetDeviceBadPixelMatrix''' function.<br>
<br>
;Example projects
: '''MiniPixTpx3-Thickness-auto''' – Acquision time auto tuning for easy first experiments.
:: Interactive control in console, text histograms and preview of images. But the code is relatively complex.
: '''MiniPixTpx3-Thickness-bath''' – Bath process, using text config file.
:: Simple code, but you need to set usable acquisition times.

{{ApiBinaryItem
| Nam = pxcAddBHMask
| HeSym = ===
| Sum = Adds a new mask (frame) for Beam-Hardening calibration.
| DefH = PXCAPI int
| DefP = unsigned* data, unsigned size, double frameTime, double thickness
| data – data of the frame tat will be used as BH mask
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the frame in seconds
| thickness – thickness of the measured data
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcBHMaskCount
| HeSym = ===
| Sum = Returns number of inserted Beam-Hardening masks (frames)
| DefH = PXCAPI int
| DefP =
|
|
|
|
|
|
|
|
| Ret = Number of masks if successful, otherwise the return value is a PXCERR_XXX code
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcRemoveBHMask
| HeSym = ===
| Sum = Removes Beam-Hardening mask (frame)
| DefH = PXCAPI int
| DefP = int index
| index – index of the mask to remove
|
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcApplyBHCorrection
| HeSym = ===
| Sum = Applies the Beam-Hardening correction to supplied frame
| DefH = PXCAPI int
| DefP = unsigned* inData, unsigned size, double frameTime, double* outData
| inData – data of the frame that will be corrected
| size – size of the data - number of pixels (width * height)
| frameTime – acquisition time of the measured frame in seconds
| outData – output data buffer where corrected data will be saved
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

== Interpolating of bad pixels ==
During BHC, pixels are found that did not work properly. For example, defective, saturated in the main image, saturated in some of the reference images, or are unusable for correction for another reason.<br>
If they do not form continuous areas, they can be compensated by interpolation from the surroundings,

{{ApiBinaryItem
| Nam = pxcInterpolateBadPixels
| HeSym = ===
| Sum = Interpolates bad pixels in the image. Uses badPixelsMatrix as bad pixels (badPixel = 1, good = 0)
| DefH = PXCAPI int
| DefP = unsigned char* badPixelsMatrix, double* data, unsigned width, unsigned height
| badPixelMatrix – matrix of the bad pixels
| data – data to be interpolated
| width – width of the image
| height – height of the image
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceBadPixelMatrix
| HeSym = ===
| Sum = Gets the devices's matrix of bad pixels (bad = 1, good = 0). Bad pixels are pixels that are masked.
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceUserMaskMatrix
| HeSym = ===
| Sum = Gets the device's matrix of user-masked pixels (masked = 1, not masked = 0).
| DefH = PXCAPI int
| DefP = unsigned deviceIndex, unsigned* userMaskMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| userMaskMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the bad pixel matrix from Beam Hardening correction - pixels that cannot be corrected. (bad pixel = 1, good = 0). Must be called after all BH masks are added.
| DefH = PXCAPI int
| DefP = unsigned* badPixelMatrix, unsigned size
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

{{ApiBinaryItem
| Nam = pxcGetDeviceAndBHBadPixelMatrix
| HeSym = ===
| Sum = Gets the combined bad pixel matrix from the device and BeamHardening (badpixel = 1, good = 0).
| DefH = PXCAPI int
| DefP = unsigned devIndex, unsigned* badPixelMatrix, unsigned size
| deviceIndex – index of the device, starting from zero
| badPixelMatrix – output data buffer where bad pixel matrix will be saved
| size – size of the data - number of pixels (width * height)
|
|
|
|
|
| Ret = 0 if successful, otherwise the return value is a PXCERR_XXX code.
| Not =
| War =
| Exa =
}}

'''See: [[Binary_core_API#pxcGetDeviceBadPixelMatrix|pxcGetDeviceBadPixelMatrix]], [[Binary_core_API#pxcInterpolateBadPixels|pxcInterpolateBadPixels]]'''

<br>
=== Example ===
----
'''See:'''
* [[Beam_hardening_correction:_Bath_example|Beam hardening correction: Bath example]]
<br>
<br>

=== Some images ===
----
{|
|+
|-
|
[[File:CdTe vs Si.png|none|alt=CdTe vs Si|CdTe vs Si]]
|| '''1. CdTe 2 mm (left) vs Si 0,3 mm (right)'''<br>
<br>
'''CdTe advantages:''' More sensitive, orders of magnitude shorter acquisition times or lower beam intensities. Have lower energy consumption and and it less warming.<br>
imgs:<br>
CdTe: integrated 3.43 sec (25,6 ms subframes)<br>
Si: integrated 27.7 sec (625 ms subframes)
|}
----
{|
|+
|-
|
[[File:CdTe artefacts.png|none|alt=CdTe artefacts|CdTe artefacts]]
|| '''CdTe disadvantages:''' Uneven distribution of chip sensitivity. Slow instability can cause the need for a long total measurement time.<br>
Specialy thick chips have a easily visible image distortion. Afther start-up, CdTe contains lot of free charges, they can cause problems duringearly measurements (use '''pxcDoSensorRefresh''').<br>
<br>
Si and CdTe have opposite bilas polarity.
|}

----
{|
|+
|-
|
[[File:Beam hardening setup Bh1a.jpg|thumb|none|alt=beam hardening experimental setup|beam hardening experimental setup]]
|| '''2. The beam hardening experimental setup'''<br>
1 – The sensor<br>
2 – Pb shielding of electronics (for sure, large intensities were tested in this experiment)<br>
3 – several thin sheets, a total of 0.3 mm to reduce free beam / first ref. plate contrast<br>
4 – 0.6 mm reference plates<br>
|}
----
{|
|+
|-
|
[[File:Beam hardening Bh1c.png|none]]
|| [[File:Beam hardening Bh2c.png|none]]
|| '''3. Test images'''<br>
Left is Fe bearing, used reference plates and the setup from img. 2<br>
<br>
Right is Al plates, 3 and 8 mm, reference plates was several 3mm sheets<br>
<br>
Up – original images<br>
Mid – afther pxcApplyBHCorrection<br>
Down – mid afther pxcInterpolateBadPixels <br>
(range in all images auto-resized to grayscale 0-255)
|}
----
{|
|+
|-
|
[[File:Beam_hardening_Bh2a.jpg|thumb|none]]
|| '''4. The Al plates experimental setup'''<br>
<br>
1 – Cooler - Si chip used<br>
2 – The Minipix<br>
3 – Imaged aluminium plates<br>
4 – Thin Al sheet to reduce free beam / first ref. plate contrast
|}

= The synchronizing =
{|
|+
|-
|
[[File:The synchronizing-Widepix.jpg|200px|none]]
|| Sometimes it is necessary to synchronized with an external event. Or some instruments, Widepix-L for example, can be organized as set of more than 1 device in 1 box and more than 1 data cable go out. If you want start acquisition on whole instrument at exactly the same time, must use synchronization by the hardware trigger.
|}

== Synchronizing basics ==
The acquisition functions have the TrgStg parameter. The 4th argument "trigger settings" of the pxcMeasureTpx3DataDrivenMode(), for example. This have options:<br>
<br>
{|
|+
|-
| '''PXC_TRG_NO''' || No sync. Normally start immediatelly and stop after acqTime.
|-
| '''PXC_TRG_HWSTART''' || Slave wait and start the acq. on HW signal, master can wait for slave ready.
|-
| '''PXC_TRG_HWSTOP'''<br>  || Start the acq. immediatelly and stop on HW signal or after acqTime.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_HWSTARTSTOP'''<br>  || Wait and start the acq. on HW signal and stop at next HW signal.<br>(Available only in specific devices, see sync. manual.)
|-
| '''PXC_TRG_SWSTART''' || Wait and start the acq. on SW signal = [[Binary_core_API#pxcDoSoftwareTrigger|pxcDoSoftwareTrigger()]].
|}
<br>
Additionally, you must use the named parameters. You can read if the device is ready, is it master, etc and write some parameters. Details depends on the device type. Some devices allow reset the ToA counter without restart acquisition or start acquisition without reset the ToA counter.<br>
<br>
'''See:''' [[#Parameter_Get/Set_functions_(using_text_paramName)|Parameter Get/Set functions (using text paramName)]]

== Synchronizing with an external source ==
Sync with the external source can depends on the device type. See the synchronization manual of your device type for hardware details.<br>
<br>
'''Example:''' Way to use the external HW sync with the Advapix-Tpx3<br>

1. Set some synchronization parameters: "TrgTimestamp", "TrgT0SyncReset", "TrgOutLevel", "TrgOutEnable" using function to write the named parameters: pxcSetDeviceParameter.<br>
2. Read some synchronization parameters: "TrgReady", "IsMaster" using the pxcGetDeviceParameter.<br>
3. Start the pxcMeasure... with some PXC_TRG_HW...<br>
4. Apply the sync signal to the input.<br>

== Synchronizing in multi-device instruments ==
(This text is primary about the WIdepix-L with 2 ethernet cables, if using other device, see the Synchronization manual of your device)<br>
<br>
'''Decision which device is master'''<br>
<syntaxhighlight lang="C">
isMaster = pxcGetDeviceParameter(devIdx, "TriggerMaster");
</syntaxhighlight>

Output is 0 for slave, 1 for master or single, <0 if the device not supports param name/type.<br>
; Note
: Some devices has '''IsMaster''' and some other has '''TriggerMaster'''.
: Some devices has output '''bool''' (read as int 0/1) and some other has '''string''' (read as char[] "Yes"/"No")
: In universal software, expect all 4 combinations to exist.

<br>
'''Master Setup'''
# Set the parameter TriggerStg = 0
# Set the parameter TriggerWaitForReady = 1
# Set the parameter TriggerOutLevel = 1

'''Slave setup'''
# Set the parameter TriggerStg = 2
# Set the parameter TriggerWaitForReady = 1

'''The measurement'''<br>
This can be simple if the continuous acquisition is used: This API function starts in separate thread:<br>

<syntaxhighlight lang="C">
rcs = pxcMeasureContinuous(slvIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)slvIdx);
rcm = pxcMeasureContinuous(masIdx, bufCnt, acqTime, PXC_TRG_HWSTART, callback, (intptr_t)masIdx);
errorToList("pxcMeasureContinuous s,m", rcs, rcm);
</syntaxhighlight>

But if using other acq. functions, you must start slave acq. in separate thread manually.<br>
(see the Visual Studio example “Mpx3-2-sync”)<br>

'''Note Widepix-L'''
: If the acquisition time is long, approximately from 100 ms, the run is irregular and there may be long pauses (1 to 5 * acqTime) between acquisitions. This can be suppressed if master acqTime is approximately over 10 % longer.

'''Widepix-L: The TriggerStg and TriggerOutLevel are linked in the following way:'''

{| class="wikitable"
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Sync 1:1 || 0 || 0 || 3 || X
|-
| Alternating sync || 0 || 0 || 2 || X
|-
| Alternating sync || 0 || 1 || 3 || X
|-
| Sync 1:1 || 0 || 1 || 2 || X
|}
X - the value doesn't matter

== Synchronizing a multi-device with an external source ==

Set the device normally for synchronizing in multi-device (See chapter above for details), but in the master settings set the TriggerStg alias TrgStg to 2 or 3 by the used edge of trigger signal. Be carefull if using 0 or 1.

{| class="wikitable"
|+ Example setting for double-device external sync on rising edge
|-
! Function !! Master TriggerStg !! Master TriggerOutLevel !! Slave TriggerStg !! Slave TriggerOutLevel
|-
| Ext and 1:1 || 2 || 1 || 2 || X
|}
X - the value doesn't matter

== Multi-device synchronizing examples ==
These samples are derived from the Mpx3 project from the AdvacamAPIexamples collection.<br>
<br>
Global variables of the example:
<syntaxhighlight line lang=C>
unsigned *collectDevFrameD1 = NULL, *collectDevFrameD2 = NULL; // collected devs all frame data
unsigned collectDevFramePxCnt = 0; // collectDevFrameDx size = devWid * devHei * devCnt * collectImgCnt
unsigned devcollectDevsIdx[256]; // list of devs to collect imgs
int collectDevsCnt = -1; // count of devs to be collected (>0 to enable)
int collectDevsMasterIdx = -1; // index of master position in devcollectDevsIdx[]
unsigned collectDevWidth = -1, collectDevHeight = -1; // size of collected image
unsigned collectImgsMax = 0; // =textColImgsMax->Text; vertical count of images to be collected
int collectDevCntCallbacks, collectDevCntOK, collectDevCntFail; // callbacks img collect status

double acqTime = 1.0; // time for acq. functions
int frameCount = 0; // frames count for pxcMeasureMultipleFrames
// or cilcular buffer frames count for pxcMeasureContinuous
int deviceMaxIdx = -1; // maximal connected dev idx (count-1)
int deviceIndex = -1; // index of the single device to be used
int frameLastIndex = -1; // index of the frame that was viewed and for saving
</syntaxhighlight>

=== Preparing setup for synchronized Mpx3 multi-device example ===
Decision if the dev is master (all dev types with internal synchronization):
<syntaxhighlight lang="cpp">
int isDevMaster(unsigned di) {
int rc = pxcGetDeviceParameter(di, "TriggerMaster");
if (rc == 0 || rc == 1) return rc;

rc = pxcGetDeviceParameter(di, "IsMaster");
if (rc == 0 || rc == 1) return rc;

char val[] = " ";
rc = pxcGetDeviceParameterString(di, "TriggerMaster", val, 4);
if (rc!=0) pxcGetDeviceParameterString(di, "IsMaster", val, 4);
if (rc == 0) {
if (strcmp(val, "Yes") == 0) return 1;
else if (strcmp(val, "No") == 0) return 0;
else return MY_ERR_CODE;
}
return rc;
}
</syntaxhighlight>
<br>
Setup devices, the textCollectDevsOrd contains device indexes order string, like as "102", primary used to joining images side by side in the desired order (Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
collectDevsCnt = textCollectDevsOrd->Text->Length;
int trgMastCnt = 0;
for (int n = 0; n < collectDevsCnt; n++) {
devcollectDevsIdx[n] = Convert::ToInt32(textCollectDevsOrd->Text[n] - '0');
if (devcollectDevsIdx[n] > deviceMaxIdx) { // deviceMaxIdx = global, set after init pxcore
collectDevsCnt = -1;
msgToList(String::Format("Collect devs: devIdx out of range {0}", devcollectDevsIdx[n]));
}

int isMast = isDevMaster(devcollectDevsIdx[n]);
if (isMast < 0) {
errorToList("pxcGetDeviceParameter TriggerMaster", isMast);
isMast = 0;
}
if (isMast == 1) {
trgMastCnt++;
collectDevsMasterIdx = n;
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 0);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 1);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
} else {
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerStg", 2);
errorToList("pxcSetDeviceParameter TriggerStg", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerWaitForReady", 1);
errorToList("pxcSetDeviceParameter TriggerWaitForReady", rc);
rc = pxcSetDeviceParameter(devcollectDevsIdx[n], "TriggerOutLevel", 0);
errorToList("pxcSetDeviceParameter TriggerOutLevel", rc);
}
}
if (trgMastCnt != 1 || collectDevsCnt < 2) {
msgToList("Err: 2 or more devs incl. 1 TriggerMaster needed for collect");
collectDevsCnt = -1;
collectDevsMasterIdx = -1;
} else {
msgToList(String::Format("Collect devs setup complete. Master idx/devIdx:{0}/{1}",
collectDevsMasterIdx, devcollectDevsIdx[collectDevsMasterIdx]));
}
</syntaxhighlight>

=== Starting acquisitions for synchronized Mpx3 multi-device example ===
This section using the callbacks to get actual data. The userData parameter is used to inform the callback function about source device index in the devcollectDevsIdx[]. Based on the index into devcollectDevsIdx[] and the frame index, a place in the buffer is selected and read from the device is called.<br>
<br>
Setup and start the synchronized measurement with using continuous acquisition.<br>
Note: Continuous mode is not usable with TDI.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight lang="cpp">
rc = initMeasParams("Continuous acq. with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;

if (collectDevsCnt > 0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip the master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];

rc = pxcMeasureContinuous(di, frameCount, acqTime, PXC_TRG_HWSTART, clbContinuousAcq,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
msgToList(String::Format("n:{0} di:{1} pxcMeasureContinuous {2} {3}",
n, di, rc, (rc==0)? "OK": "failed"));
if (rc != 0) return;
}
} else {
// pxcMeasureContinuous(unsigned deviceIndex, unsigned frameBufferSize, double frameTime, unsigned trgStg = PXC_TRG_NO, FrameMeasuredCallback callback = 0, intptr_t userData = 0);
rc = pxcMeasureContinuous(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbContinuousAcq, NULL);
errorToList("pxcMeasureContinuous", rc);
}
</syntaxhighlight>
<br>

Setup and start the synchronized measurement with using multi-acquisition.<br>
A bit more complicated, but works with TDI as well.<br>
(Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
int rc;
DWORD dwThrID;
HANDLE h;

int rc = initMeasParams("More frames with callback test", true, true); // set-up buffers, operation mode and other measurement settings
if (rc!=0) return;
if (collectDevsCnt>0) {
for (int n = 0; n <= collectDevsCnt; n++) {
if (n == collectDevsMasterIdx) continue; // skip master and start it at end
int di = devcollectDevsIdx[n];
if (n == collectDevsCnt) di = devcollectDevsIdx[collectDevsMasterIdx];
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(di, frameCount, acqTime, PXC_TRG_HWSTART, clbFramesWC,
(n < collectDevsCnt) ? n : collectDevsMasterIdx);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList(String::Format("n:{0} di:{1} CreateThread {2} OK", n, di, (int)dwThrID));
if (h == NULL) {
msgToList(String::Format("n:{0} di:{1} CreateThread {2} failed", n, di, (int)dwThrID));
return;
}
}
} else {
sMeasureMultFrsCallbackPars* thrData = new sMeasureMultFrsCallbackPars(deviceIndex, frameCount, acqTime, PXC_TRG_NO, clbFramesWC, NULL);
h = CreateThread(NULL, 0, MeasureMultFrsCallbackThrFn, (void*)thrData, 0, &dwThrID);
msgToList("pxcMeasureMultipleFramesWithCallback - thread " + System::Convert::ToString((int)dwThrID));
if (h == NULL) return;
}
</syntaxhighlight>

=== Callbacks for synchronized Mpx3 multi-device example ===
Collecting the image data, called from callbacks (Tested with Widepix, ethernet or USB):
<syntaxhighlight line lang=C>
// idx of devcollectDevsIdx, frame idx
void collectDevImgs(unsigned ndi, unsigned fIdx) {
int rc;

size_t adrAdd = static_cast<size_t>(devPixels * (ndi + (fIdx % collectImgsMax) * collectDevsCnt));
unsigned *cd1 = collectDevFrameD1 + adrAdd;
unsigned *cd2 = collectDevFrameD2 + adrAdd;
unsigned bs = collectDevFramePxCnt - adrAdd;

if (bs < 0x80000000) {
rc = pxcGetMeasuredFrameMpx3(devcollectDevsIdx[ndi], fIdx, cd1, cd2, &bs);
} else rc = MY_ERROR_CODE;

collectDevCntCallbacks++;
if (rc == 0) {
collectDevCntOK++;
} else {
collectDevCntFail++;
}
}
</syntaxhighlight>
<br>

The callbacks:
<syntaxhighlight line lang=C>
// callback function for "frames with callback"
void clbFramesWC(intptr_t acqCount, intptr_t userData) {
frameLastIndex = acqCount-1;
clbCnt++;
if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}

// callback function for continuous acquisition
void clbContinuousAcq(intptr_t acqCount, intptr_t userData) {
if (acqCount<0) {
clbError = acqCount;
return;
}
frameLastDevIdx = (int)userData;
clbCnt++;

if (acqCount<frameCount) {
frameLastIndex = acqCount - 1;
} else {
if (++frameLastIndex>=acqCount) frameLastIndex = 0;
}

if (collectDevsCnt > 0) {
collectDevImgs((unsigned)userData, frameLastIndex);
return;
}
}
</syntaxhighlight>
<br>

<syntaxhighlight line lang=C>
</syntaxhighlight>

=== Rearranging measured data to complete image ===
When all measurements are complete, the data is arranged in memory so that each frame from each device occupies a contiguous area. In order for images to be connected when displaying, each line of the resulting image must contain lines from individual neighboring devices.

{| class="wikitable"
|+ Rearranging data from two adjacent sub-devices and three images
|-
! Measured data in memory !! style="width:50px;" rowspan=7 | !! colspan=2| Rearranged data in memory
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 0
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 0
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 1
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 1
|-
| style="height:30px; width:400px; text-align:center;" |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 0 / frame 2
| style="height:60px; width:200px; text-align:center;" rowspan=2 |device 1 / frame 2
|-
| style="height:30px; width:400px; text-align:center;" |device 1 / frame 2
|}

<syntaxhighlight line="" lang="C">
compiledFr1 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));
//compiledFr2 = (unsigned*)malloc(collectDevFramePxCnt * sizeof(unsigned));

compiledImgData1 = (int*)malloc(collectDevFramePxCnt * sizeof(int));
//compiledImgData2 = (int*)malloc(collectDevFramePxCnt * sizeof(int));

if (!compiledFr1 || !compiledImgData1) {
msgToList("viewCollectedDevsFrs: Memory allocation failed");

if (compiledFr1) free(compiledFr1);
if (compiledFr2) free(compiledFr2);
if (compiledImgData1) free(compiledImgData1);
if (compiledImgData2) free(compiledImgData2);
return;
}

size_t adrAddIn = 0, adrAddOut = 0;
// adrAdd = devPixels * ndi + collectDevsCnt * devPixels * (fIdx % collectImgsMax);
for (size_t fi = 0; fi < collectImgsMax; fi++) { // frames
for (size_t lin = 0; lin < collectDevHeight; lin++) { // lines of single frame
for (size_t ndi = 0; ndi < collectDevsCnt; ndi++) { // subdevices idxs in collectDevsCnt
adrAddIn = collectDevsCnt * devPixels * fi + devPixels * ndi + devWidth * lin;

if (checkCollectReverseLines->Checked) {
for (size_t x = 0; x < devWidth; x++) {
(compiledFr1 + adrAddOut)[x] = (collectDevFrameD1 + adrAddIn)[devWidth - x];
//(compiledFr2 + adrAddOut)[x] = (collectDevFrameD2 + adrAddIn)[devWidth - x];
}
} else {
memcpy(compiledFr1 + adrAddOut, collectDevFrameD1 + adrAddIn, devWidth * sizeof(unsigned));
//memcpy(compiledFr2 + adrAddOut, collectDevFrameD2 + adrAddIn, devWidth * sizeof(unsigned));
}
adrAddOut += (size_t)devWidth;
}
}
}

colorizeData(compiledFr1, compiledImgData1, collectDevFramePxCnt);
Bitmap^ bmp1c = gcnew Bitmap(collectDevWidth, collectDevHeight * collectImgsMax, collectDevWidth * 4, System::Drawing::Imaging::PixelFormat::Format32bppRgb, (IntPtr)compiledImgData1);
pictureBox3->SizeMode = PictureBoxSizeMode::StretchImage;
pictureBox3->Image = bmp1c;
</syntaxhighlight>

= Related =
* [[Pixet SDK]]
* [[Files and directories of the Pixet and SDK#Main directory of the API-using programs, independent on the Pixet|Files and directories: Main directory of the API-using programs]]
* [[File types]]