Binary core API
Core/basic binary (C) API introduction
The PIXet is a multi-platform software developed in ADVACAM company. It is a basic software that allows measurement control and saving of measured data with Medipix detectors. It supports Medipix2, Medipix3, Timepix and Timepix3 detectors and all the readout-devices sold by ADVACAM company such as FitPIX, AdvaPIX, WidePIX, etc. It is written in C++ language and uses multi-platform Qt libraries.
This document describes a developer interface of the PIXet software. This developer interface consists of dynamic linked library pxcore.dll (Windows) or libpxcore.so (Mac or Linux), the corresponding header file for the library pxcapi.h and few other supporting libraries (fitpix.dll, Visual Studio runtime libraries, etc.)
The core API with the pxcore library, allowing basic measurements and device settings.
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:
Requirements
Hardware
This API requires computer with x86 compatible architecture (no ARM), 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).
Specialized functions have names with chip type included:
- pxcSetTimepixCalibrationEnabled – Timepix only (no Timepix3)
- pxcMeasureTpx3DataDrivenMode – Timepix3 only
- pxcMeasureSingleFrameMpx3 – Medipix3 only
The attempt to use the function if compatible hardware (in initialized state) not present, end with error.
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.
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.
See The Pixet core, additional libraries and other files
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.
In Microsoft visual studio, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):
The Pixet core, additional libraries and other files
Main 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)
And need some auxiliary files and directories:
Where to get these files?
All need files except hwlibs and configs are located in the zip file with name like us:
PIXet SDK 1.6.4 (Build 765) Win.zip
And all files except LIB files for Windows compilation are located in the Pixet directory:
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.
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.
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.
Contents of the pixet.ini file:
[hwlibs] minipix.dll
(x64, Myform... and TPx3-1... are from the MS Visual studio project)
Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.
Tip: How to create the Windows CLR APP:
MSDN:create-c-windows-forms-application-in-visual-studio-2017
API Functions
Simple commandline example
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.
(Timepix3 only)
#include "pxcapi.h"
int main() {
int rc; // return code
rc = pxcInitialize();
printf("pxcInitialize: %d (0 is OK)", rc;
rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
printf("pxcSetTimepix3Mode: %d (0 is OK)", rc;
// pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
printf("pxcMeasureMultipleFrames: %d (0 is OK)", rc;
// pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
printf("pxcSaveMeasuredFrame 0: %d (0 is OK)", rc;
rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
printf("pxcSaveMeasuredFrame 1: %d (0 is OK)", rc;
rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
printf("pxcSaveMeasuredFrame 2: %d (0 is OK)", rc;
rc = pxcExit();
printf("pxcExit: %d (0 is OK)", rc;
}
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.
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"):
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)
Example of the Cmake building script:
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
User can finally run the run.cmd to run the program.
Building on Linux using GCC
Example build.sh:
#!/bin/bash gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -lminipix -ldl -lm -lc -g
Example run.sh to run the output executable:
#!/bin/bash LD_LIBRARY_PATH=. ./build-out # run last compiled example
Auxiliary functions
Start-up and end
pxcInitialize
{{{HeSym}}} {{{Nam}}} {{{HeSym}}}
- This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError.
- Definition
{{{DefH}}} {{{Nam}}}({{{DefP}}});
Parameters
- argc – number of program command line arguments (optional parameter)
- argv – command line program arguments (optional parameter)
- {{{3}}}
- {{{4}}}
- {{{5}}}
- {{{6}}}
- {{{7}}}
- {{{8}}}
- Return value
- 0 if successful, otherwise the return value is a PXCERR_XXX code.
Note
- {{{Not}}}
Warning
- {{{War}}}
Example
int rc = pxcInitialize();
pxcExit
{{{HeSym}}} {{{Nam}}} {{{HeSym}}}
- This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library.
- Definition
{{{DefH}}} {{{Nam}}}({{{DefP}}});
Parameters
- argc – number of program command line arguments (optional parameter)
- argv – command line program arguments (optional parameter)
- {{{3}}}
- {{{4}}}
- {{{5}}}
- {{{6}}}
- {{{7}}}
- {{{8}}}
- Return value
- 0 if successful, otherwise the return value is a PXCERR_XXX code.
Note
- {{{Not}}}
Warning
- {{{War}}}
Example
int rc = pxcInitialize();