Всем привет, на днях возникла необходимость использования камеры Xphase Pro без официального приложения, и я столкнулся с тем, что в интернете особо‑то этим никто не занимался. О том, что делать с файлами типа ori и о FFI на Rust читайте под катом.
О самой камере
Камера представляет собой многолинзовую вундервафлю, конкретно у меня в руках оказалась модель Xphase Pro X2, хвалебные оды которой можно прочитать в интернете. Я по камерам не специалист, и толком тут ничего сказать не могу — разрешение высокое, цветопередача вроде нормальная.
Перво‑наперво, разберемся с тем, что вообще можно сделать с камерой. Она хостит WI‑FI сеть с одноименным названием, спокойно к ней подключаемся. Тут у нас есть несколько вариантов действий — можно скачать приложение на телефон и все сделать в графическом интерфейсе, а можно обратиться к камере по апи на хост 192.168.6.1 Именно второй вариант я и выбрал, в силу независящих от меня обстоятельств.
API камеры
В апи по адресу 192.168.6.1:8080 у нас есть несколько методов, таких как:
get_list
get_file - этот метод расположен на отдельном 8081 порте
delete_file
do_capture
get_thumb
Я наивно полагал, что одним только апи получится реализовать данную задачу. С виду все кажется просто - вызвали do_capture, камера сделала снимок, посмотрели его имя в get_list, вывели тамбнейл через get_thumb, если захотели полный снимок - попросили get_file. И тут на последнем этапе мы можем обнаружить, что get_file возвращает нам вовсе не картинку, а странный файл с расширением ori.
Поначалу я подумал, что это какой-то формат, близкий к raw, но все оказалось куда сложнее. Ori - это некий бинарный файл, который хранит в себе несколько снимков, с каждой линзы. На каждую линзу несколько снимков с разной выдержкой. Можно ли вытащить эти снимки из ori? Можно, на гитхабе есть репозиторий, где Entropy512 написал соответствующий скрипт.
Однако что делать с этими снимками дальше? Собирать панораму вручную через Hugin? Использовать какой-нибудь feature extractor и сшивать скриптами? Неужели разработчики не подумали о каком-нибудь готовом решении, ведь в приложении они как-то это делают?..
Открываем номикон и кастуем черную магию
Итак, наконец мы переходим к практической части статьи. Разработчики предоставляют библиотеку libPanoMaker.so, в которой есть нужная нам функция - превращение ori в jpg.
Разберемся с функциями, которые нам предоставляет библиотека:
ProInitRawFileReader
ProUpdateRawFileReader
ProCleanRawFileReader
ProMakePanoramaBuf
На бумаге все выглядит просто - создаем структуру, хранящую буфер с данными, вызываем ProMakePanoramaBuf , и волшебным мановением руки все само получается. Но реальность, как всегда, куда сложнее.
Для начала следует понять, что мы не обойдемся без ProUpdateRawFileReader. Она указывает, на какую длину заполнен буфер. Дело в том, что ProInitRawFileReader только создает структуру, которая хранит в себе буфер ori файла и его максимальную длину. По умолчанию считается, что этот буфер пустой.
Сделано это потому, что разработчики позволяют параллельно читать ori файл с их камеры и выполнять склейку панорамы из той части буфера, которая заполнена сейчас. В моем случае ori файл уже лежал локально, поэтому мне было нужно лишь заполнить буфер, создать из него RawFileReader и вызвать ProUpdateRawFileReader, чтобы библиотека "поняла", что буфер полон нужной информации.
Ну что ж, с чего начинать? Во-первых, нам нужно сделать так, чтобы libPanoMaker.so линковалась к нашему Rust приложению. Можно положить эту либу в место, которое считывается как папка для библиотек, например /usr/local/lib, можно написать build.rs, который будет искать эту библиотеку где-то поблизости с исходниками, тут кому как удобнее и понятнее.
Когда мы уверены, что линковщик найдет нужную библиотеку, начинаем писать наш интерфейс. Во-первых, объявим функции, которые будем вызывать из со-шки:
use std::ffi::{CString, c_char, c_uchar, c_int, c_double, c_void};
#[link(name = "PanoMaker")]
extern "C" {
fn ProInitRawFileReader(fileBuf: *mut c_uchar, fileSize: c_int) -> *mut c_void;
fn ProUpdateRawFileReader(hRawFileReader: *mut c_void, bufWrPos: c_int) -> c_int;
fn ProCleanRawFileReader(hRawFileReader: *mut c_void) -> c_int;
fn ProMakePanoramaBuf(threadNum: c_int, memType: c_int, hRawFileReader: *mut c_void, outputDir: *const c_uchar, fileNo: *const c_uchar,
hdrSel: c_int, outputType: c_int, colorMode: c_int, extendMode: c_int, outputJpgType: c_int, outputQuality: c_int, stitchMode: c_int,
gyroMode: c_int, templateMode: c_int, templateFileName: *const c_uchar,
logoAngle: c_double, luminance: c_double, contrastRatio: c_double, gammaMode: c_int, wbMode: c_int, wbConfB: c_double, wbConfG: c_double,
wbConfR: c_double, saturation: c_double, dbgData: *mut c_uchar) -> c_int;
}
По сути дела, здесь мы переписываем объявление функций из С++ на Rust, заменяя сишные типы на типы из Rust FFI. Обратите внимание, что там, где используются указатели, после звездочки следует ключевое слово mut , если же мы хотим показать, что память неизменяемая (или, как пишут в номиконе, place expression), пишем const . В остальном же, это дело нехитрое - где в C++ принимается int, в Rust принимается c_int, остальные типы также по аналогии. Здесь, правда, есть нюанс, что c_void - это не то же самое, что и (), поэтому явно конвертировать одно в другое не выйдет.
Но мало прилинковать PanoMaker, помимо него нам нужен и libz (он же zlib), без которого ничего не заработает. Поэтому добавим ссылку на libz:
#[link(name = "z")]
extern "C" {
fn zlibVersion() -> *mut c_char;
}Почему я написал конкретную функцию, а не оставил блок extern "C" пустым? Дело в том, что если оставить его пустым, то компилятор будет выдавать ту же ошибку, как если бы libz не был прилинкован. Более того, мало объявить функцию из этой библиотеки, нужно ее еще и вызвать - подозреваю, это все потому, что итоговый исполняемый файл просто-напросто оптимизируется и не включает в себя неиспользованную ссылку. Поэтому перед тем как будем писать код, посвященный обработке ori, вызовем функцию из zlib:
unsafe { println!("{:?}", zlibVersion()); }Что ж, теперь все готово к нашему ритуалу. Начнем с ori файла, прочитаем его и заполним буфер:
let target_ori: &'static str = "input";
let mut file_buf: Vec<c_uchar> = vec![];
let mut ori_file = File::open(target_ori.to_string() + ".ori").expect("No ori file found!");
let fsize = ori_file.metadata().unwrap().len();
ori_file.read_to_end(&mut file_buf);
Теперь создадим RawFileReader. Вернемся чуть назад, к объявлению функции ProInitRawFileReader и вспомним, что она возвращает *mut c_void, иными словами, сырой указатель. Безопасно ли это? Конечно же нет! Поэтому весь следующий код будет unsafe.
unsafe { // <- открываем unsafe блок
let mut reader: *mut c_void = ProInitRawFileReader(file_buf.as_mut_ptr(), (fsize) as c_int);
ProUpdateRawFileReader(reader, (fsize) as c_int);Обратите внимание, что мы вызвали ProUpdateRawFileReader , чтобы указать, что буфер полон. Все что теперь остается - это выделить память под отладочную информацию.
let mut dbg_data: Vec<c_uchar> = Vec::from([0;300]);Теперь можем вызывать заветную ProMakePanoramaBuf. В ней нужно обязательно указать папку, в которой будет итоговый файл, причем путь к папке должен заканчиваться на слэш / - это важно! Также указываем имя входного файла без расширения. Все остальные параметры - стандартные, согласно документации разработчика.
let result: c_int = ProMakePanoramaBuf(1, 0, reader, "output/".as_ptr(), target_ori.as_ptr(),
10, 0, 1, 0, 1, 70, 0, 0, 0, "".as_ptr(), -1., 1.2, 1.3, 1, 0, 1.0, 1.0, 1.0, 1.0,
dbg_data.as_mut_ptr()
);И - последний штрих - очистим память, выделенную под RawFileReader и закроем unsafe-блок.
ProCleanRawFileReader(reader);
} // <- закрыли unsafe-блокЧто ж, вот и все, что нужно было сделать. В итоге в папке output мы увидим нужную нам панораму в формате jpg. Полный код будет выглядеть так:
use std::ffi::{CString, c_char, c_uchar, c_int, c_double, c_void};
use std::fs::File;
use std::io::Read;
#[link(name = "z")]
extern "C" {
fn zlibVersion() -> *mut c_char;
}
#[link(name = "PanoMaker")]
extern "C" {
fn ProInitRawFileReader(fileBuf: *mut c_uchar, fileSize: c_int) -> *mut c_void;
fn ProUpdateRawFileReader(hRawFileReader: *mut c_void, bufWrPos: c_int) -> c_int;
fn ProCleanRawFileReader(hRawFileReader: *mut c_void) -> c_int;
fn ProMakePanoramaBuf(threadNum: c_int, memType: c_int, hRawFileReader: *mut c_void, outputDir: *const c_uchar, fileNo: *const c_uchar,
hdrSel: c_int, outputType: c_int, colorMode: c_int, extendMode: c_int, outputJpgType: c_int, outputQuality: c_int, stitchMode: c_int,
gyroMode: c_int, templateMode: c_int, templateFileName: *const c_uchar,
logoAngle: c_double, luminance: c_double, contrastRatio: c_double, gammaMode: c_int, wbMode: c_int, wbConfB: c_double, wbConfG: c_double,
wbConfR: c_double, saturation: c_double, dbgData: *mut c_uchar) -> c_int;
}
fn process_panorama() -> i32 {
unsafe { println!("{:?}", zlibVersion()); }
let target_ori: &'static str = "input";
let mut safe_result: i32 = 0;
let mut file_buf: Vec<c_uchar> = vec![];
let mut ori_file = File::open(target_ori.to_string() + ".ori").expect("No ori file found!");
let fsize = ori_file.metadata().unwrap().len();
ori_file.read_to_end(&mut file_buf);
unsafe {
let mut reader: *mut c_void = ProInitRawFileReader(file_buf.as_mut_ptr(), (fsize) as c_int);
ProUpdateRawFileReader(reader, (fsize) as c_int);
let mut dbg_data: Vec<c_uchar> = Vec::from([0;300]);
let result: c_int = ProMakePanoramaBuf(1, 0, reader, "output/".as_ptr(), target_ori.as_ptr(), 10, 0, 1, 0, 1, 70, 0, 0, 0, "".as_ptr(), -1., 1.2, 1.3, 1, 0, 1.0, 1.0, 1.0, 1.0, dbg_data.as_mut_ptr());
ProCleanRawFileReader(reader);
safe_result = result;
}
return safe_result;
}
fn main() {
println!("{}", process_panorama());
}Итоги
Ну что ж, мы узнали немного про камеры Xphase, про формат ori и про FFI.
В первую очередь, статья, конечно, направлена на тех бедолаг, кто столкнется с той же проблемой, что и я - как превратить непонятный ori в понятный jpg.
Во вторую очередь, мне давно хотелось как-то повзаимодействовать с FFI в Rust и написать более-менее понятный гайд. Оказалось, что все не так уж и сложно. Примитивные типы, такие как i32, без проблем конвертируются в c_int, строки одним методом конвертируются в *mut c_uchar в комментариях подсказали, что это неправильный подход, строки в Rust не являются нуль-терминированными, поэтому надо либо заканчивать их на \0, либо использовать CString и CStr. Понимаю, что почти не затронул теоретическую часть вопроса, но вряд ли я бы в рамках статьи написал полнее и понятнее, чем в номиконе.
В комментариях можете поделиться вариантами build.rs и подсказать, почему обязательно нужно объявлять и вызывать функцию из zlib, чтобы библиотека прилинковалась.
Ссылку на используемую .so и документацию к камере прикреплять не стал, потому что это не реклама, и мне за эту статью никто не платил, а значит приукрашивать реальность я не буду. Попробуйте поискать это все самостоятельно, и сами поймете, о чем я - мягко говоря, ищется это все не с первого раза.
