fers_api.rs

Go to the documentation of this file.

// SPDX-License-Identifier: GPL-2.0-only
// Copyright (c) 2025-present FERS Contributors (see AUTHORS.md).
 
//! # Safe Rust FFI Wrapper for `libfers`
//!
//! This module provides a safe, idiomatic Rust interface to the `libfers` C++
//! simulation library. It bridges the gap between the raw C-style FFI (generated
//! by `bindgen`) and the higher-level Rust code used in the Tauri application.
//!
//! ## Safety Guarantees
//!
//! The module ensures the following safety properties:
//!
//! 1. **Automatic Resource Management**: All C-allocated resources (contexts, strings)
//!    are wrapped in RAII types that guarantee cleanup via `Drop`.
//! 2. **Memory Safety**: Raw pointers from C are only dereferenced within `unsafe`
//!    blocks with documented safety invariants.
//! 3. **String Conversion**: All C strings are converted to Rust `String`s with
//!    proper UTF-8 validation and null-termination handling.
//! 4. **Thread Safety**: The `FersContext` is marked as `Send + Sync` because it
//!    will be protected by a `Mutex` in the application layer.
//!
//! ## Error Handling
//!
//! All fallible operations return `Result<T, String>`, where the error string
//! contains a human-readable message retrieved from the C library's thread-local
//! error storage.
 
use std::ffi::{c_void, CStr, CString};
use std::os::raw::c_char;
use tauri::{AppHandle, Emitter};
 
/// Raw FFI bindings generated by `bindgen` from `libfers/api.h`.
///
/// This inner module is kept private to prevent direct access to unsafe FFI
/// functions. It contains the raw C function declarations and opaque struct types
/// that mirror the C-API header.
///
/// # Safety
///
/// All items in this module are `unsafe` to use directly. They require:
/// * Valid, non-null pointers for all context handles.
/// * Proper null-termination for all C strings.
/// * Manual memory management (allocation/deallocation).
///
/// The parent module (`fers_api`) provides safe wrappers that enforce these invariants.
mod ffi {
    #![allow(non_upper_case_globals)]
    #![allow(non_camel_case_types)]
    #![allow(non_snake_case)]
    #![allow(dead_code)]
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}
 
/// A smart pointer wrapper for C-allocated strings returned from `libfers`.
///
/// This type ensures that the memory allocated by the C library (via `strdup`)
/// is properly freed when the wrapper goes out of scope, preventing memory leaks.
///
/// # Memory Management
///
/// The wrapped pointer must have been allocated by a `libfers` API function that
/// transfers ownership to the caller (e.g., `fers_get_scenario_as_json`). The
/// `Drop` implementation calls `fers_free_string` to release the memory back to
/// the C allocator.
///
/// # Null Handling
///
/// If the pointer is null, the wrapper treats it as an empty string. This simplifies
/// error handling in cases where null indicates "no data" rather than an error.
struct FersOwnedString(*mut c_char);
 
impl Drop for FersOwnedString {
    /// Frees the underlying C string by calling `fers_free_string`.
    ///
    /// This is automatically invoked when the wrapper goes out of scope,
    /// ensuring that no manual cleanup is required by the caller.
    ///
    /// # Safety
    ///
    /// The pointer must have been allocated by `libfers` (typically via `strdup`)
    /// and must not have been freed already. The `Drop` trait ensures this is
    /// called exactly once per instance.
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: The pointer was allocated by `libfers` and is valid until we call `fers_free_string`.
            // We are the sole owner of this pointer.
            unsafe { ffi::fers_free_string(self.0) };
        }
    }
}
 
impl FersOwnedString {
    /// Converts the owned C string to a Rust `String`, consuming the wrapper.
    ///
    /// This method performs UTF-8 validation and copies the string data into a
    /// Rust-managed `String`. The C-allocated memory is freed after the conversion.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The converted string if valid UTF-8.
    /// * `Err(std::str::Utf8Error)` - If the C string contains invalid UTF-8 bytes.
    ///
    /// # Example
    ///
    /// ```no_run
    /// let owned = FersOwnedString(some_c_string_ptr);
    /// match owned.into_string() {
    ///     Ok(s) => println!("Got string: {}", s),
    ///     Err(e) => eprintln!("Invalid UTF-8: {}", e),
    /// }
    /// ```
    fn into_string(self) -> Result<String, std::str::Utf8Error> {
        if self.0.is_null() {
            return Ok(String::new());
        }
        // SAFETY: `self.0` is a valid, null-terminated C string from `libfers`.
        // The `CStr::from_ptr` is safe as long as the pointer is valid.
        let c_str = unsafe { CStr::from_ptr(self.0) };
        c_str.to_str().map(|s| s.to_string())
    }
}
 
/// A safe, RAII-style wrapper for the `fers_context_t*` C handle.
///
/// This struct encapsulates the lifetime and ownership of a simulation context
/// created by the `libfers` C++ library. It ensures that:
/// * The context is created via `fers_context_create` on initialization.
/// * The context is destroyed via `fers_context_destroy` when dropped.
/// * The context is never null after successful creation.
///
/// # Thread Safety
///
/// This type implements `Send` and `Sync` because the underlying C++ context will
/// be protected by a `Mutex` in the Tauri application. The C++ `FersContext` class
/// is not thread-safe, but by serializing all access through Rust's `Mutex`, we
/// ensure that only one thread can call methods on the context at a time.
///
/// # Example
///
/// ```no_run
/// use fers_api::FersContext;
///
/// let context = FersContext::new().expect("Failed to create context");
/// context.load_scenario_from_xml_file("scenario.xml")?;
/// let json = context.get_scenario_as_json()?;
/// // Context is automatically destroyed when it goes out of scope
/// ```
pub struct FersContext {
    /// The raw pointer to the C++ context object.
    ///
    /// This must be a raw pointer because `fers_context_t` is an opaque struct.
    /// The `Send` and `Sync` traits are manually implemented because we'll wrap this
    /// context in a Mutex, ensuring that access to the non-thread-safe C++ object
    /// is properly synchronized.
    ptr: *mut ffi::fers_context_t,
}
 
// SAFETY: The FersContext will be protected by a Mutex. All C-API calls on a single
// context are not guaranteed to be thread-safe by themselves, but by enforcing
// serialized access through a Mutex, we make its usage safe across threads.
unsafe impl Send for FersContext {}
unsafe impl Sync for FersContext {}
 
impl Drop for FersContext {
    /// Destroys the underlying C++ context and frees all associated resources.
    ///
    /// This method is automatically called when the `FersContext` goes out of scope.
    /// It delegates to `fers_context_destroy`, which is responsible for cleaning up
    /// the C++ `FersContext` object and its owned `World`.
    ///
    /// # Safety
    ///
    /// The pointer must be valid and non-null. The `Drop` trait guarantees this is
    /// called exactly once, preventing double-free errors.
    fn drop(&mut self) {
        if !self.ptr.is_null() {
            // SAFETY: `self.ptr` is a valid handle created by `fers_context_create`.
            // The `Drop` trait ensures this is called exactly once.
            unsafe { ffi::fers_context_destroy(self.ptr) };
        }
    }
}
 
/// Retrieves and formats the last error message from the `libfers` C-API.
///
/// This helper function is called whenever a C-API function returns an error code.
/// It queries the thread-local error storage via `fers_get_last_error_message`,
/// converts the C string to a Rust `String`, and ensures the memory is freed.
///
/// # Returns
///
/// A human-readable error message. If no error message is available (null pointer),
/// a default message is returned. If the error message contains invalid UTF-8, an
/// error describing the UTF-8 issue is returned instead.
///
/// # Thread Safety
///
/// This function is thread-safe because the error storage in `libfers` is thread-local.
/// Each thread has its own error message buffer.
fn get_last_error() -> String {
    // SAFETY: `fers_get_last_error_message` is a thread-safe FFI function.
    let error_ptr = unsafe { ffi::fers_get_last_error_message() };
    if error_ptr.is_null() {
        "An unknown FFI error occurred.".to_string()
    } else {
        // The FersOwnedString wrapper ensures the memory is freed.
        FersOwnedString(error_ptr)
            .into_string()
            .unwrap_or_else(|e| format!("FFI error message contained invalid UTF-8: {}", e))
    }
}
 
/// Data structure for simulation progress events emitted to the frontend.
#[derive(serde::Serialize, Clone)]
struct ProgressPayload {
    message: String,
    current: i32,
    total: i32,
}
 
/// The C-style callback function passed to `fers_run_simulation`.
///
/// This function is invoked by the C++ core to report progress. It reconstructs the
/// `AppHandle` from the `user_data` pointer and emits a Tauri event to the frontend.
///
/// # Safety
///
/// This function is marked `unsafe` because it dereferences raw pointers (`message`, `user_data`).
/// The caller (the C++ library) must guarantee that `message` is a valid, null-terminated
/// UTF-8 string and that `user_data` is a valid pointer to an `AppHandle`. The pointer
/// is only valid for the duration of the `fers_run_simulation` call.
#[allow(clippy::similar_names)]
extern "C" fn simulation_progress_callback(
    message: *const c_char,
    current: i32,
    total: i32,
    user_data: *mut c_void,
) {
    if user_data.is_null() {
        return;
    }
    // SAFETY: This is safe because we know `user_data` is a pointer to the AppHandle,
    // which is guaranteed to be valid for the lifetime of the simulation call.
    let app_handle = unsafe { &*(user_data as *const AppHandle) };
 
    // SAFETY: `message` is guaranteed by the C-API to be a valid, null-terminated string.
    let message_str = unsafe { CStr::from_ptr(message) }.to_string_lossy().into_owned();
 
    let payload = ProgressPayload { message: message_str, current, total };
 
    // Emit the event to the frontend. If this fails, there's little we can do
    // from the callback, so we just let it panic in debug builds.
    app_handle
        .emit("simulation-progress", payload)
        .expect("Failed to emit simulation-progress event");
}
 
/// A safe RAII wrapper for the antenna pattern data returned by the C-API.
struct FersAntennaPatternData(*mut ffi::fers_antenna_pattern_data_t);
impl Drop for FersAntennaPatternData {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: The pointer is valid and owned by this struct.
            unsafe { ffi::fers_free_antenna_pattern_data(self.0) };
        }
    }
}
 
/// Data structure for antenna pattern data sent to the frontend.
///
/// This struct flattens the 2D gain data into a 1D vector for easy serialization.
#[derive(serde::Serialize)]
pub struct AntennaPatternData {
    /// Flattened array of linear gain values (normalized 0.0 to 1.0).
    /// Ordered row-major: Elevation rows, then Azimuth columns.
    gains: Vec<f64>,
    /// Number of samples along the azimuth axis (360 degrees).
    az_count: usize,
    /// Number of samples along the elevation axis (180 degrees).
    el_count: usize,
    /// The peak linear gain found in the pattern, used for normalization.
    max_gain: f64,
}
 
// Helper wrapper for the visual link list
struct FersVisualLinkList(*mut ffi::fers_visual_link_list_t);
 
impl Drop for FersVisualLinkList {
    fn drop(&mut self) {
        if !self.0.is_null() {
            unsafe { ffi::fers_free_preview_links(self.0) };
        }
    }
}
 
/// Represents a visual link segment for 3D rendering.
///
/// This struct maps C-style enums to integers for consumption by the TypeScript frontend.
#[derive(serde::Serialize)]
pub struct VisualLink {
    /// The type of radio link.
    /// * `0`: Monostatic (Tx -> Tgt -> Rx, where Tx==Rx)
    /// * `1`: Bistatic Illuminator (Tx -> Tgt)
    /// * `2`: Bistatic Scattered (Tgt -> Rx)
    /// * `3`: Direct Interference (Tx -> Rx)
    pub link_type: u8,
    /// The radiometric quality of the link.
    /// * `0`: Strong (SNR > 0 dB)
    /// * `1`: Weak (SNR < 0 dB, visible but sub-noise)
    pub quality: u8,
    /// A pre-formatted label string (e.g., "-95 dBm").
    pub label: String,
    /// The name of the start component for this segment.
    pub source_name: String,
    /// The name of the end component for this segment.
    pub dest_name: String,
    /// The name of the original transmitter (useful for scattered paths).
    pub origin_name: String,
}
 
impl FersContext {
    /// Creates a new `FersContext` by calling the C-API constructor.
    ///
    /// This function allocates a new C++ `FersContext` object on the heap via
    /// `fers_context_create`. The returned context is initially empty and must be
    /// populated by loading a scenario (via `load_scenario_from_xml_file` or
    /// `update_scenario_from_json`).
    ///
    /// # Returns
    ///
    /// * `Some(FersContext)` - If the context was successfully created.
    /// * `None` - If allocation failed (e.g., out of memory) or if the C++ constructor
    ///   threw an exception.
    ///
    /// # Example
    ///
    /// ```no_run
    /// let context = FersContext::new().expect("Failed to create FERS context");
    /// ```
    pub fn new() -> Option<Self> {
        // SAFETY: `fers_context_create` is a simple constructor function with no preconditions.
        let ptr = unsafe { ffi::fers_context_create() };
        if ptr.is_null() {
            None
        } else {
            Some(Self { ptr })
        }
    }
 
    /// Loads a FERS scenario from an XML file into the context.
    ///
    /// This method replaces any existing scenario in the context with the one parsed
    /// from the specified file. The XML is validated against the FERS schema if
    /// validation is enabled in the C++ library.
    ///
    /// # Parameters
    ///
    /// * `filepath` - A UTF-8 string containing the absolute or relative path to the
    ///   FERS XML scenario file.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the scenario was successfully loaded and parsed.
    /// * `Err(String)` - If the file could not be read, the XML was invalid, or a
    ///   C++ exception was thrown. The error string contains details.
    ///
    /// # Example
    ///
    /// ```no_run
    /// context.load_scenario_from_xml_file("/path/to/scenario.xml")?;
    /// ```
    pub fn load_scenario_from_xml_file(&self, filepath: &str) -> Result<(), String> {
        let c_filepath = CString::new(filepath).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string.
        // The function returns 0 on success.
        let result =
            unsafe { ffi::fers_load_scenario_from_xml_file(self.ptr, c_filepath.as_ptr(), 1) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Retrieves the current in-memory scenario as a JSON string.
    ///
    /// This method serializes the C++ `World` object into JSON format, which mirrors
    /// the structure used by the frontend. It is typically used to populate the UI
    /// after loading a scenario from XML.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The JSON representation of the scenario.
    /// * `Err(String)` - If serialization failed or the JSON contains invalid UTF-8.
    ///
    /// # Memory Management
    ///
    /// The returned string is a Rust-owned `String`. The underlying C-allocated memory
    /// is automatically freed by the `FersOwnedString` wrapper.
    ///
    /// # Example
    ///
    /// ```no_run
    /// let json = context.get_scenario_as_json()?;
    /// let scenario: serde_json::Value = serde_json::from_str(&json)?;
    /// ```
    pub fn get_scenario_as_json(&self) -> Result<String, String> {
        // SAFETY: We pass a valid context pointer. The function returns a C string
        // that we must free.
        let json_ptr = unsafe { ffi::fers_get_scenario_as_json(self.ptr) };
        if json_ptr.is_null() {
            return Err(get_last_error());
        }
        // FersOwnedString takes ownership and will free the memory on drop.
        FersOwnedString(json_ptr).into_string().map_err(|e| e.to_string())
    }
 
    /// Retrieves the current in-memory scenario as a FERS XML string.
    ///
    /// This method serializes the C++ `World` object into the standard FERS XML format.
    /// It is typically used when the user wants to export the scenario (potentially
    /// modified in the UI) back to a file.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The XML representation of the scenario.
    /// * `Err(String)` - If serialization failed or the XML contains invalid UTF-8.
    ///
    /// # Memory Management
    ///
    /// The returned string is a Rust-owned `String`. The underlying C-allocated memory
    /// is automatically freed by the `FersOwnedString` wrapper.
    ///
    /// # Example
    ///
    /// ```no_run
    /// let xml = context.get_scenario_as_xml()?;
    /// std::fs::write("exported_scenario.xml", xml)?;
    /// ```
    pub fn get_scenario_as_xml(&self) -> Result<String, String> {
        // SAFETY: We pass a valid context pointer. The function returns a C string
        // that we must free.
        let xml_ptr = unsafe { ffi::fers_get_scenario_as_xml(self.ptr) };
        if xml_ptr.is_null() {
            return Err(get_last_error());
        }
        // FersOwnedString takes ownership and will free the memory on drop.
        FersOwnedString(xml_ptr).into_string().map_err(|e| e.to_string())
    }
 
    /// Updates the in-memory scenario from a JSON string.
    ///
    /// This method is the primary way for the UI to push modified scenario data back
    /// to the C++ simulation engine. It deserializes the JSON and rebuilds the internal
    /// `World` object, replacing any existing scenario.
    ///
    /// # Parameters
    ///
    /// * `json` - A UTF-8 JSON string representing the scenario. The structure must
    ///   match the schema expected by `libfers` (the same format returned by
    ///   `get_scenario_as_json`).
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the scenario was successfully deserialized and loaded.
    /// * `Err(String)` - If the JSON was malformed, contained invalid data, or a C++
    ///   exception was thrown. The error string contains details.
    ///
    /// # Example
    ///
    /// ```no_run
    /// let modified_json = /* JSON from UI */;
    /// context.update_scenario_from_json(&modified_json)?;
    /// ```
    pub fn update_scenario_from_json(&self, json: &str) -> Result<(), String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string.
        // The function returns 0 on success.
        let result = unsafe { ffi::fers_update_scenario_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Runs the simulation defined in the context.
    ///
    /// This is a blocking call that executes the simulation on a separate thread pool
    /// managed by the C++ core. It accepts a Tauri `AppHandle` to enable progress
    /// reporting via events.
    ///
    /// # Parameters
    ///
    /// * `app_handle` - A reference to the Tauri application handle, used for emitting events.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the simulation completed successfully.
    /// * `Err(String)` - If the simulation failed.
    pub fn run_simulation(&self, app_handle: &AppHandle) -> Result<(), String> {
        // The AppHandle is passed as a raw pointer through the `user_data` argument.
        // This is safe because this function is blocking, and the app_handle reference
        // will be valid for the entire duration of the C++ call.
        let user_data_ptr = app_handle as *const _ as *mut c_void;
 
        // SAFETY: We pass a valid context pointer, a valid function pointer for the callback,
        // and a valid user_data pointer that points to the AppHandle.
        let result = unsafe {
            ffi::fers_run_simulation(self.ptr, Some(simulation_progress_callback), user_data_ptr)
        };
 
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Generates a KML file for the current scenario.
    ///
    /// # Parameters
    ///
    /// * `output_path` - The path where the KML file will be saved.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the KML file was generated successfully.
    /// * `Err(String)` - If KML generation failed.
    pub fn generate_kml(&self, output_path: &str) -> Result<(), String> {
        let c_output_path = CString::new(output_path).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string for the path.
        let result = unsafe { ffi::fers_generate_kml(self.ptr, c_output_path.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Retrieves a sampled gain pattern for a specified antenna.
    ///
    /// # Parameters
    ///
    /// * `antenna_name` - The name of the antenna asset to sample.
    /// * `az_samples` - The resolution along the azimuth axis.
    /// * `el_samples` - The resolution along the elevation axis.
    /// * `frequency` - The frequency in Hz to use for calculation.
    ///
    /// # Returns
    ///
    /// * `Ok(AntennaPatternData)` - If the pattern was successfully sampled.
    /// * `Err(String)` - If the antenna was not found or an error occurred.
    pub fn get_antenna_pattern(
        &self,
        antenna_name: &str,
        az_samples: usize,
        el_samples: usize,
        frequency: f64,
    ) -> Result<AntennaPatternData, String> {
        let c_antenna_name = CString::new(antenna_name).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and valid arguments.
        let result_ptr = unsafe {
            ffi::fers_get_antenna_pattern(
                self.ptr,
                c_antenna_name.as_ptr(),
                az_samples,
                el_samples,
                frequency,
            )
        };
 
        if result_ptr.is_null() {
            return Err(get_last_error());
        }
 
        let owned_data = FersAntennaPatternData(result_ptr);
 
        // SAFETY: Dereferencing the non-null pointer returned by the FFI.
        // The data is valid for the lifetime of `owned_data`.
        let (gains_ptr, az_count, el_count, max_gain) = unsafe {
            (
                (*owned_data.0).gains,
                (*owned_data.0).az_count,
                (*owned_data.0).el_count,
                (*owned_data.0).max_gain,
            )
        };
        let total_samples = az_count * el_count;
 
        // SAFETY: The gains_ptr is valid for `total_samples` elements.
        let gains_slice = unsafe { std::slice::from_raw_parts(gains_ptr, total_samples) };
 
        Ok(AntennaPatternData { gains: gains_slice.to_vec(), az_count, el_count, max_gain })
    }
 
    pub fn calculate_preview_links(&self, time: f64) -> Result<Vec<VisualLink>, String> {
        let list_ptr = unsafe { ffi::fers_calculate_preview_links(self.ptr, time) };
        if list_ptr.is_null() {
            let err_msg = get_last_error();
            // If we receive a NULL ptr but no error message, it might be a logic error
            // or an unhandled edge case in C++. We default to the retrieved message.
            return Err(err_msg);
        }
 
        let owned_list = FersVisualLinkList(list_ptr);
        let count = unsafe { (*owned_list.0).count };
        let links_ptr = unsafe { (*owned_list.0).links };
 
        let mut result = Vec::with_capacity(count);
        if count > 0 && !links_ptr.is_null() {
            let slice = unsafe { std::slice::from_raw_parts(links_ptr, count) };
            for l in slice {
                let link_type_val = match l.type_ {
                    ffi::fers_link_type_t_FERS_LINK_MONOSTATIC => 0,
                    ffi::fers_link_type_t_FERS_LINK_BISTATIC_TX_TGT => 1,
                    ffi::fers_link_type_t_FERS_LINK_BISTATIC_TGT_RX => 2,
                    ffi::fers_link_type_t_FERS_LINK_DIRECT_TX_RX => 3,
                    _ => 0,
                };
 
                let quality_val = match l.quality {
                    ffi::fers_link_quality_t_FERS_LINK_STRONG => 0,
                    _ => 1,
                };
 
                let label =
                    unsafe { CStr::from_ptr(l.label.as_ptr()) }.to_string_lossy().into_owned();
                let source_name = unsafe { CStr::from_ptr(l.source_name.as_ptr()) }
                    .to_string_lossy()
                    .into_owned();
                let dest_name =
                    unsafe { CStr::from_ptr(l.dest_name.as_ptr()) }.to_string_lossy().into_owned();
                let origin_name = unsafe { CStr::from_ptr(l.origin_name.as_ptr()) }
                    .to_string_lossy()
                    .into_owned();
 
                result.push(VisualLink {
                    link_type: link_type_val,
                    quality: quality_val,
                    label,
                    source_name,
                    dest_name,
                    origin_name,
                });
            }
        }
        Ok(result)
    }
}
 
/// A safe wrapper for the stateless `fers_get_interpolated_motion_path` C-API function.
///
/// This function converts Rust-native waypoint data into C-compatible types,
/// calls the FFI function, and then converts the result back into a `Vec` of points,
/// ensuring that all C-allocated memory is properly freed.
///
/// # Parameters
/// * `waypoints` - A vector of motion waypoints from the frontend.
/// * `interp_type` - The interpolation algorithm to use.
/// * `num_points` - The desired number of points in the output path.
///
/// # Returns
/// * `Ok(Vec<InterpolatedPoint>)` - A vector of points representing the calculated path.
/// * `Err(String)` - An error message if the FFI call failed.
pub fn get_interpolated_motion_path(
    waypoints: Vec<crate::MotionWaypoint>,
    interp_type: crate::InterpolationType,
    num_points: usize,
) -> Result<Vec<crate::InterpolatedMotionPoint>, String> {
    if waypoints.is_empty() || num_points == 0 {
        return Ok(Vec::new());
    }
 
    let c_waypoints: Vec<ffi::fers_motion_waypoint_t> = waypoints
        .into_iter()
        .map(|wp| ffi::fers_motion_waypoint_t { time: wp.time, x: wp.x, y: wp.y, z: wp.altitude })
        .collect();
 
    let c_interp_type = match interp_type {
        crate::InterpolationType::Static => ffi::fers_interp_type_t_FERS_INTERP_STATIC,
        crate::InterpolationType::Linear => ffi::fers_interp_type_t_FERS_INTERP_LINEAR,
        crate::InterpolationType::Cubic => ffi::fers_interp_type_t_FERS_INTERP_CUBIC,
    };
 
    // SAFETY: We are calling the stateless FFI function with valid, well-formed arguments.
    // The pointer returned is owned by us and must be freed.
    let result_ptr = unsafe {
        ffi::fers_get_interpolated_motion_path(
            c_waypoints.as_ptr(),
            c_waypoints.len(),
            c_interp_type,
            num_points,
        )
    };
 
    if result_ptr.is_null() {
        return Err(get_last_error());
    }
 
    // RAII wrapper to ensure the C-allocated path is freed.
    struct FersInterpolatedMotionPath(*mut ffi::fers_interpolated_path_t);
 
    impl Drop for FersInterpolatedMotionPath {
        fn drop(&mut self) {
            if !self.0.is_null() {
                // SAFETY: The pointer is valid and owned by this struct.
                unsafe { ffi::fers_free_interpolated_motion_path(self.0) };
            }
        }
    }
 
    let owned_path = FersInterpolatedMotionPath(result_ptr);
 
    // SAFETY: We are accessing the fields of a non-null pointer returned by the FFI.
    // The `count` and `points` fields are guaranteed to be valid for the lifetime of `owned_path`.
    let result_slice =
        unsafe { std::slice::from_raw_parts((*owned_path.0).points, (*owned_path.0).count) };
 
    let points: Vec<crate::InterpolatedMotionPoint> = result_slice
        .iter()
        .map(|p| crate::InterpolatedMotionPoint {
            x: p.x,
            y: p.y,
            z: p.z,
            vx: p.vx,
            vy: p.vy,
            vz: p.vz,
        })
        .collect();
 
    Ok(points)
}
 
/// A safe wrapper for the stateless `fers_get_interpolated_rotation_path` C-API function.
///
/// This function converts Rust-native rotation waypoints into C-compatible types,
/// calls the FFI function, and converts the result back into a `Vec` of points.
/// It handles the mapping between Rust enums and C enums for interpolation types
/// and ensures that the C-allocated array is properly freed.
///
/// # Parameters
/// * `waypoints` - A vector of `RotationWaypoint`s.
/// * `interp_type` - The interpolation algorithm to use.
/// * `num_points` - The desired number of points in the output path.
///
/// # Returns
/// * `Ok(Vec<InterpolatedRotationPoint>)` - A vector of interpolated points.
/// * `Err(String)` - An error message if the FFI call failed.
pub fn get_interpolated_rotation_path(
    waypoints: Vec<crate::RotationWaypoint>,
    interp_type: crate::InterpolationType,
    num_points: usize,
) -> Result<Vec<crate::InterpolatedRotationPoint>, String> {
    if waypoints.is_empty() || num_points == 0 {
        return Ok(Vec::new());
    }
 
    let c_waypoints: Vec<ffi::fers_rotation_waypoint_t> = waypoints
        .into_iter()
        .map(|wp| ffi::fers_rotation_waypoint_t {
            time: wp.time,
            azimuth_deg: wp.azimuth,
            elevation_deg: wp.elevation,
        })
        .collect();
 
    let c_interp_type = match interp_type {
        crate::InterpolationType::Static => ffi::fers_interp_type_t_FERS_INTERP_STATIC,
        crate::InterpolationType::Linear => ffi::fers_interp_type_t_FERS_INTERP_LINEAR,
        crate::InterpolationType::Cubic => ffi::fers_interp_type_t_FERS_INTERP_CUBIC,
    };
 
    let result_ptr = unsafe {
        ffi::fers_get_interpolated_rotation_path(
            c_waypoints.as_ptr(),
            c_waypoints.len(),
            c_interp_type,
            num_points,
        )
    };
 
    if result_ptr.is_null() {
        return Err(get_last_error());
    }
 
    struct FersInterpolatedRotationPath(*mut ffi::fers_interpolated_rotation_path_t);
 
    impl Drop for FersInterpolatedRotationPath {
        fn drop(&mut self) {
            if !self.0.is_null() {
                unsafe { ffi::fers_free_interpolated_rotation_path(self.0) };
            }
        }
    }
 
    let owned_path = FersInterpolatedRotationPath(result_ptr);
 
    let result_slice =
        unsafe { std::slice::from_raw_parts((*owned_path.0).points, (*owned_path.0).count) };
 
    let points: Vec<crate::InterpolatedRotationPoint> = result_slice
        .iter()
        .map(|p| crate::InterpolatedRotationPoint {
            azimuth_deg: p.azimuth_deg,
            elevation_deg: p.elevation_deg,
        })
        .collect();
 
    Ok(points)
}