Документация API

XRayDetect XRay DLL - Справочник программиста

Обзор

API XRayDetect XRay DLL предоставляет полный доступ к функциональности рентгеновских детекторов. Библиотека разработана для операционных систем Windows и обеспечивает высокопроизводительное взаимодействие с оборудованием.

Системные требования

  • Windows 7 или выше
  • 64-битная операционная система
  • Соответствующие драйверы оборудования
  • USB 2.0 или Ethernet подключение

Кросс-платформенная поддержка

Хотя стандартная поставка включает DLL для Windows, API может быть скомпилирован для Linux (.so) и других платформ по запросу.

Начало работы

Для начала работы с API выполните следующие шаги:

  1. Загрузите и подключите библиотеку XRay DLL
  2. Инициализируйте плагин с помощью xrayPluginLoad()
  3. Подключитесь к устройству с помощью xrayBoardConnect()
  4. Настройте обратные вызовы для получения данных
  5. Запустите захват данных
#include "xray_api.h"

int main() {
    // Инициализация плагина
    struct pluginInfo info;
    int result = xrayPluginLoad(&info);
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка инициализации: %d\n", result);
        return -1;
    }
    
    // Подключение к устройству
    struct boardInfo boardInfo;
    result = xrayBoardConnect("USB", &boardInfo);
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка подключения: %d\n", result);
        return -1;
    }
    
    printf("Подключено к: %s %s\n", boardInfo.vendor, boardInfo.model);
    
    // Завершение работы
    xrayBoardDisconnect();
    xrayPluginUnload();
    
    return 0;
}

Функции управления плагином

xrayPluginLoad

int __stdcall xrayPluginLoad(struct pluginInfo *info);

Инициализирует плагин и возвращает информацию о нем.

Параметры:

Параметр Тип Описание
info struct pluginInfo* Указатель на структуру для получения информации о плагине

Возвращаемые значения:

  • XRAYPLUGIN_ALLOK (0) - успешное выполнение
  • Отрицательный код ошибки при неудаче
struct pluginInfo info;
int result = xrayPluginLoad(&info);
if (result == XRAYPLUGIN_ALLOK) {
    printf("API версия: %d\n", info.apiVersion);
    printf("Версия плагина: %s\n", info.version);
    printf("Описание: %s\n", info.description);
}

xrayPluginUnload

int __stdcall xrayPluginUnload(void);

Выгружает плагин и освобождает все ресурсы.

Возвращаемые значения:

  • XRAYPLUGIN_ALLOK (0) - успешное выполнение
  • Отрицательный код ошибки при неудаче
Примечание: Эта функция должна быть вызвана перед выгрузкой DLL для корректной очистки ресурсов.

Функции логирования

xraySetPrintCallback

int __stdcall xraySetPrintCallback(xrayLogCallbackFn fn, void *userData);

Устанавливает функцию обратного вызова для получения сообщений журнала.

Параметры:

Параметр Тип Описание
fn xrayLogCallbackFn Указатель на функцию обратного вызова
userData void* Пользовательские данные для передачи в callback
void __stdcall logCallback(
    int logLevel,
    const char *fileName,
    const char *funcName,
    unsigned int line,
    long long threadId,
    const char *threadName,
    const char *msg,
    void *userData
) {
    printf("[%s:%d] %s\n", funcName, line, msg);
}

// Установка callback
xraySetPrintCallback(logCallback, NULL);

xraySetLogLevel

int __stdcall xraySetLogLevel(int logLevel);

Устанавливает уровень детализации логирования.

Уровни логирования:

  • 0 - Только ошибки
  • 1 - Предупреждения и ошибки
  • 2 - Информационные сообщения
  • 3 - Отладочная информация

Обработка ошибок

xrayGetErrorMessage

int __stdcall xrayGetErrorMessage(int *errorNum, char *errorStr, int errorStrSize);

Получает код и описание последней произошедшей ошибки.

Параметры:

Параметр Тип Описание
errorNum int* Указатель для получения кода ошибки
errorStr char* Буфер для получения описания ошибки
errorStrSize int Размер буфера errorStr
int errorCode;
char errorMessage[256];
int result = xrayGetErrorMessage(&errorCode, errorMessage, sizeof(errorMessage));
if (result == XRAYPLUGIN_ALLOK) {
    printf("Ошибка %d: %s\n", errorCode, errorMessage);
}

Подключение устройств

xrayBoardConnect

int __stdcall xrayBoardConnect(const char *connectString, struct boardInfo *info);

Устанавливает соединение с платой сбора данных XRay.

Параметры:

Параметр Тип Описание
connectString const char* Строка подключения ("USB", "COM3", IP-адрес)
info struct boardInfo* Структура для получения информации о плате

Возвращаемые значения:

  • XRAYPLUGIN_ALLOK - успешное подключение
  • XRAYPLUGIN_ALREADY_CONNECTED - уже подключено
  • XRAYPLUGIN_NOT_FOUND - устройство не найдено
struct boardInfo info;
int result = xrayBoardConnect("USB", &info);
if (result == XRAYPLUGIN_ALLOK) {
    printf("Подключено к: %s %s\n", info.vendor, info.model);
    printf("Каналов: %d\n", info.channelsCount);
    printf("Серийный номер: %s\n", info.serialNumber);
}

xrayBoardDisconnect

int __stdcall xrayBoardDisconnect(void);

Закрывает соединение с текущей подключенной платой.

Внимание: Перед отключением убедитесь, что захват данных остановлен.

Захват данных

xraySetImageLineCallback

int __stdcall xraySetImageLineCallback(xrayImageLineCallbackFn fn, void *userData);

Устанавливает функцию обратного вызова для получения строк изображения.

void __stdcall imageLineCallback(
    const struct imageLine *line,
    void *userData
) {
    printf("Получена строка: %d пикселей\n", line->pixelCount);
    // Обработка данных изображения
    for (int i = 0; i < line->pixelCount; i++) {
        printf("Пиксель %d: %d\n", i, line->pixels[i]);
    }
}

// Установка callback
xraySetImageLineCallback(imageLineCallback, NULL);

xrayStartCapture

int __stdcall xrayStartCapture(void);

Запускает процесс захвата данных с детекторов.

xrayStopCapture

int __stdcall xrayStopCapture(void);

Останавливает процесс захвата данных.

// Запуск захвата
int result = xrayStartCapture();
if (result == XRAYPLUGIN_ALLOK) {
    printf("Захват запущен\n");
    
    // Ожидание данных...
    Sleep(5000);
    
    // Остановка захвата
    xrayStopCapture();
    printf("Захват остановлен\n");
}

Калибровка

xrayStartCalibration

int __stdcall xrayStartCalibration(int calibrationType);

Запускает процедуру калибровки детекторов.

Типы калибровки:

  • 0 - Калибровка темнового тока
  • 1 - Калибровка усиления
  • 2 - Полная калибровка
// Запуск полной калибровки
int result = xrayStartCalibration(2);
if (result == XRAYPLUGIN_ALLOK) {
    printf("Калибровка запущена\n");
    
    // Ожидание завершения калибровки
    int status;
    do {
        Sleep(1000);
        xrayGetCalibrationStatus(&status);
        printf("Статус калибровки: %d%%\n", status);
    } while (status < 100);
    
    printf("Калибровка завершена\n");
}

Полные примеры

Базовый пример захвата данных

#include "xray_api.h"
#include 
#include 

// Глобальные переменные
int g_lineCount = 0;

// Callback для получения строк изображения
void __stdcall onImageLine(const struct imageLine *line, void *userData) {
    g_lineCount++;
    printf("Строка %d: %d пикселей, время: %lld\n", 
           g_lineCount, line->pixelCount, line->timestamp);
    
    // Сохранение данных в файл или обработка
    // ...
}

// Callback для логирования
void __stdcall onLogMessage(int logLevel, const char *fileName, 
                           const char *funcName, unsigned int line,
                           long long threadId, const char *threadName,
                           const char *msg, void *userData) {
    printf("[LOG] %s\n", msg);
}

int main() {
    printf("Инициализация XRay API...\n");
    
    // 1. Инициализация плагина
    struct pluginInfo pluginInfo;
    int result = xrayPluginLoad(&pluginInfo);
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка инициализации плагина: %d\n", result);
        return -1;
    }
    
    printf("Плагин загружен: %s v%s\n", 
           pluginInfo.description, pluginInfo.version);
    
    // 2. Настройка логирования
    xraySetPrintCallback(onLogMessage, NULL);
    xraySetLogLevel(2); // Информационные сообщения
    
    // 3. Подключение к устройству
    struct boardInfo boardInfo;
    result = xrayBoardConnect("USB", &boardInfo);
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка подключения к устройству: %d\n", result);
        xrayPluginUnload();
        return -1;
    }
    
    printf("Подключено к: %s %s\n", boardInfo.vendor, boardInfo.model);
    printf("Каналов: %d, Серийный номер: %s\n", 
           boardInfo.channelsCount, boardInfo.serialNumber);
    
    // 4. Настройка callback для данных
    result = xraySetImageLineCallback(onImageLine, NULL);
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка установки callback: %d\n", result);
        goto cleanup;
    }
    
    // 5. Запуск захвата
    printf("Запуск захвата данных...\n");
    result = xrayStartCapture();
    if (result != XRAYPLUGIN_ALLOK) {
        printf("Ошибка запуска захвата: %d\n", result);
        goto cleanup;
    }
    
    // 6. Ожидание данных
    printf("Захват данных в течение 10 секунд...\n");
    Sleep(10000);
    
    // 7. Остановка захвата
    printf("Остановка захвата...\n");
    xrayStopCapture();
    
    printf("Получено строк: %d\n", g_lineCount);
    
cleanup:
    // 8. Отключение и очистка
    xrayBoardDisconnect();
    xrayPluginUnload();
    
    printf("Завершение работы\n");
    return 0;
}

Структуры данных

struct pluginInfo

struct pluginInfo {
    int apiVersion;           // Версия API
    char version[64];         // Версия плагина
    char description[256];    // Описание плагина
    char buildDate[32];       // Дата сборки
    char buildTime[32];       // Время сборки
};

struct boardInfo

struct boardInfo {
    char vendor[64];          // Производитель
    char model[64];           // Модель платы
    char serialNumber[64];    // Серийный номер
    int channelsCount;        // Количество каналов
    int maxPixelsPerChannel;  // Максимум пикселей на канал
    int supportedModes;       // Поддерживаемые режимы
};

struct imageLine

struct imageLine {
    int lineNumber;           // Номер строки
    long long timestamp;      // Временная метка
    int pixelCount;           // Количество пикселей
    unsigned short *pixels;   // Данные пикселей
    int channelId;            // ID канала
    int energyLevel;          // Уровень энергии (для двухэнергетических)
};

Коды ошибок

Код Константа Описание
0 XRAYPLUGIN_ALLOK Успешное выполнение
-1 XRAYPLUGIN_ERROR Общая ошибка
-2 XRAYPLUGIN_NOT_INITIALIZED Плагин не инициализирован
-3 XRAYPLUGIN_ALREADY_CONNECTED Устройство уже подключено
-4 XRAYPLUGIN_NOT_CONNECTED Устройство не подключено
-5 XRAYPLUGIN_NOT_FOUND Устройство не найдено
-6 XRAYPLUGIN_INVALID_PARAMETER Неверный параметр
-7 XRAYPLUGIN_TIMEOUT Превышено время ожидания
-8 XRAYPLUGIN_CAPTURE_ACTIVE Захват уже активен
-9 XRAYPLUGIN_CAPTURE_NOT_ACTIVE Захват не активен
-10 XRAYPLUGIN_CALIBRATION_FAILED Ошибка калибровки