realsense_rust/base.rs
1//! Common types and functions.
2
3use crate::kind::Rs2DistortionModel;
4use num_traits::FromPrimitive;
5use realsense_sys as sys;
6use std::{ffi::CString, time::Duration};
7
8/// The default timeout duration in librealsense2
9pub const DEFAULT_TIMEOUT: Duration = Duration::from_millis(sys::RS2_DEFAULT_TIMEOUT as u64);
10
11/// Helper function for converting a path to a series of `c_char` that can be interpreted as a
12/// sequence of bytes / native path for a given platform..
13pub(crate) fn from_path<P>(path: P) -> anyhow::Result<CString>
14where
15 P: AsRef<std::path::Path>,
16{
17 // Thanks, Tenders McChiken.
18 // https://stackoverflow.com/questions/38948669/whats-the-most-direct-way-to-convert-a-path-to-a-c-char
19 let mut buf = Vec::new();
20
21 #[cfg(unix)]
22 {
23 use std::os::unix::ffi::OsStrExt;
24 buf.extend(path.as_ref().as_os_str().as_bytes());
25 };
26
27 #[cfg(windows)]
28 {
29 use std::os::windows::ffi::OsStrExt;
30 buf.extend(
31 path.as_ref()
32 .as_os_str()
33 .encode_wide()
34 .chain(Some(0))
35 .map(|b| {
36 let b = b.to_ne_bytes();
37 b.get(0).copied().into_iter().chain(b.get(1).copied())
38 })
39 .flatten(),
40 );
41 };
42
43 Ok(CString::new(buf)?)
44}
45
46/// Newtype wrapper for RealSense motion device intrinsics
47#[derive(Debug)]
48pub struct Rs2MotionDeviceIntrinsics(pub sys::rs2_motion_device_intrinsic);
49
50/// Profile the scale, bias, and variances for a given motion device
51///
52/// The bias and scale factors are stored as one large matrix; see the documentation on `data()` for the correct way to
53/// retrieve these parameters.
54///
55/// Use the function `stream_profile.motion_intrinsics()` to retrieve these intrinsics from a certain stream.
56impl Rs2MotionDeviceIntrinsics {
57 /// A 3x4 matrix describing the scale and bias intrinsics of the motion device.
58 ///
59 /// This matrix is stored internally like so:
60 /// [ Scale X | cross axis | cross axis | Bias X ]
61 /// [ cross axis | Scale Y | cross axis | Bias Y ]
62 /// [ cross axis | cross axis | Scale Z | Bias Z ]
63 ///
64 pub fn data(&self) -> [[f32; 4usize]; 3usize] {
65 self.0.data
66 }
67 /// Variance of noise for X, Y, and Z axis.
68 pub fn noise_variances(&self) -> [f32; 3usize] {
69 self.0.noise_variances
70 }
71 /// Variance of bias for X, Y, and Z axis.
72 pub fn bias_variances(&self) -> [f32; 3usize] {
73 self.0.bias_variances
74 }
75}
76
77unsafe impl Send for Rs2MotionDeviceIntrinsics {}
78
79/// Type representing the intrinsic scale, bias, and variances for a given motion device.
80///
81/// The data in `coeffs` means different things for different models.
82///
83/// - Brown-Conrady: [k1, k2, p1, p2, k3].
84/// - F-Theta Fisheye: [k1, k2, k3, k4, 0].
85/// - Kannala-Brandt: [k1, k2, k3, k4, 0].
86///
87/// The Intel RealSense documentation claims that "Other models are subject to their own interpretations". This is
88/// admittedly not too helpful, but it's worth noting in case your model isn't covered here.
89#[derive(Debug)]
90pub struct Rs2Distortion {
91 /// Distortion model of the image.
92 pub model: Rs2DistortionModel,
93 /// Distortion coefficients.
94 pub coeffs: [f32; 5usize],
95}
96
97unsafe impl Send for Rs2Distortion {}
98
99/// Type representing the model for describing the way that light bends in a stream.
100///
101/// This stores the focal length, principal point, dimensions, and distortion model used on the image frame. See the
102/// documentation for [Rs2Distortion] for specifics on the available distortion models for RealSense devices.
103///
104/// Use the function `stream_profile.intrinsics()` to retrieve these intrinsics from a certain stream.
105#[derive(Debug)]
106pub struct Rs2Intrinsics(pub sys::rs2_intrinsics);
107
108impl Rs2Intrinsics {
109 /// Width of the image in pixels
110 pub fn width(&self) -> usize {
111 self.0.width as usize
112 }
113 /// Height of the image in pixels
114 pub fn height(&self) -> usize {
115 self.0.height as usize
116 }
117
118 /// Horizontal coordinate of the principal point of the image, as a pixel offset from the left edge
119 pub fn ppx(&self) -> f32 {
120 self.0.ppx
121 }
122 /// Vertical coordinate of the principal point of the image, as a pixel offset from the top edge
123 pub fn ppy(&self) -> f32 {
124 self.0.ppy
125 }
126 /// Focal length of the image plane, as a multiple of pixel width
127 pub fn fx(&self) -> f32 {
128 self.0.fx
129 }
130 /// Focal length of the image plane, as a multiple of pixel height
131 pub fn fy(&self) -> f32 {
132 self.0.fy
133 }
134 /// Distortion model and coefficients of the image
135 pub fn distortion(&self) -> Rs2Distortion {
136 Rs2Distortion {
137 model: Rs2DistortionModel::from_i32(self.0.model as i32).unwrap(),
138 coeffs: self.0.coeffs,
139 }
140 }
141}
142
143unsafe impl Send for Rs2Intrinsics {}
144
145/// The topology describing how the different devices are oriented.
146///
147/// Use the function `stream_profile.extrinsics()` to retrieve these extrinsics from a certain stream in relation to
148/// another stream on the same device.
149#[derive(Debug)]
150pub struct Rs2Extrinsics(pub sys::rs2_extrinsics);
151
152impl Rs2Extrinsics {
153 /// Column-major 3x3 rotation matrix
154 pub fn rotation(&self) -> [f32; 9usize] {
155 self.0.rotation
156 }
157 /// Three-element translation vector, in meters
158 pub fn translation(&self) -> [f32; 3usize] {
159 self.0.translation
160 }
161}
162
163unsafe impl Send for Rs2Extrinsics {}
164
165/// Region of interest for the auto exposure algorithm.
166#[derive(Debug, Clone)]
167pub struct Rs2Roi {
168 /// Left coordinate of the region of interest.
169 pub min_x: i32,
170 /// Top coordinate of the region of interest.
171 pub min_y: i32,
172 /// Right coordinate of the region of interest.
173 pub max_x: i32,
174 /// Bottom coordinate of the region of interest.
175 pub max_y: i32,
176}