Merge pull request #73 from Tropix126/feat/distance-sensor-object-size

feat: add `object_size` method to distance sensor

CHANGELOG.md

@@ -33,13 +33,17 @@ Before releasing:
   - Added various constants for convenience around `Motor` and `Gearset`.
 - Added `Controller` API to the `pros::prelude` module. (#108)
 
+- `relative_size` method on `DistanceSensor` for getting a guess at an object's relative size. (#73)
+
 ### Fixed
 
 - `pros_sys` bindings to the Motors C API now takes the correct port type (`i8`) as of PROS 4 (**Breaking Change**) (#66).
 - Fixed the unintended `unsafe` context present in the `sync_robot` and `async_robot` family of macros (**Breaking Change**) (#107).
 
 ### Changed
 
+- Renamed `DistanceSensor::object_velocity` to `DistanceSensor::velocity`.
+- Adjusted `distance_confidence` to return a value from [`0.0`, `1.0`] rather than 0-100 to match other percentage getters.
 - Refactored the Motor API (**Breaking Change**) (#66)
   - Adjusts constructor arguments for `Motor` to allow passing `Gearset` and a direction instead of `brake_mode` at construction. (**Breaking Change**) (#66)
   - Renamed `Motor::get_state` to `Motor::state`. (**Breaking Change**) (#66)

packages/pros-devices/src/smart/distance.rs

@@ -24,31 +24,45 @@ impl DistanceSensor {
 
     /// Returns the distance to the object the sensor detects in millimeters.
     pub fn distance(&self) -> Result<u32, PortError> {
-        Ok(unsafe { bail_on!(PROS_ERR, pros_sys::distance_get(self.port.index())) as u32 })
+        Ok(bail_on!(PROS_ERR, unsafe {
+            pros_sys::distance_get(self.port.index())
+        }) as u32)
     }
 
-    /// returns the velocity of the object the sensor detects in m/s
-    pub fn object_velocity(&self) -> Result<f64, PortError> {
-        // all VEX Distance Sensor functions return PROS_ERR on failure even though
+    /// Returns the velocity of the object the sensor detects in m/s
+    pub fn velocity(&self) -> Result<f64, PortError> {
+        // All VEX Distance Sensor functions return PROS_ERR on failure even though
         // some return floating point values (not PROS_ERR_F)
-        Ok(unsafe {
-            bail_on!(
-                PROS_ERR as c_double,
-                pros_sys::distance_get_object_velocity(self.port.index())
-            )
-        })
+        Ok(bail_on!(PROS_ERR as c_double, unsafe {
+            pros_sys::distance_get_object_velocity(self.port.index())
+        }))
     }
 
-    /// Returns the confidence in the distance measurement from 0% to 100%.
-    pub fn distance_confidence(&self) -> Result<f32, PortError> {
+    /// Get the current guess at relative "object size".
+    ///
+    /// This is a value that has a range of 0 to 400. A 18" x 30" grey card will return
+    /// a value of approximately 75 in typical room lighting.
+    ///
+    /// This sensor reading is unusual, as it is entirely unitless with the seemingly arbitrary
+    /// range of 0-400 existing due to VEXCode's [`vex::sizeType`] enum having four variants. It's
+    /// unknown what the sensor is *actually* measuring here either, so use this data with a grain
+    /// of salt.
+    ///
+    /// [`vex::sizeType`]: https://api.vexcode.cloud/v5/search/sizeType/sizeType/enum
+    pub fn relative_size(&self) -> Result<u32, PortError> {
+        Ok(bail_on!(PROS_ERR, unsafe {
+            pros_sys::distance_get_object_size(self.port.index())
+        }) as u32)
+    }
+
+    /// Returns the confidence in the distance measurement from 0.0 to 1.0.
+    pub fn distance_confidence(&self) -> Result<f64, PortError> {
         // 0 -> 63
-        let confidence = unsafe {
-            bail_on!(
-                PROS_ERR,
-                pros_sys::distance_get_confidence(self.port.index())
-            )
-        } as f32;
-        Ok(confidence * 100.0 / 63.0)
+        let confidence = bail_on!(PROS_ERR, unsafe {
+            pros_sys::distance_get_confidence(self.port.index())
+        }) as f64;
+
+        Ok(confidence / 63.0)
     }
 }