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}