Implementation of the C-style FFI for the libfers core library. More...

#include <algorithm>
#include <core/logging.h>
#include <core/parameters.h>
#include <core/sim_id.h>
#include <cstring>
#include <filesystem>
#include <format>
#include <functional>
#include <libfers/api.h>
#include <math/path.h>
#include <math/rotation_path.h>
#include <mutex>
#include <nlohmann/json.hpp>
#include <string>
#include <vector>
#include "antenna/antenna_factory.h"
#include "core/fers_context.h"
#include "core/sim_threading.h"
#include "core/thread_pool.h"
#include "serial/json_serializer.h"
#include "serial/kml_generator.h"
#include "serial/rotation_angle_utils.h"
#include "serial/rotation_warning_utils.h"
#include "serial/xml_parser.h"
#include "serial/xml_serializer.h"
#include "signal/radar_signal.h"
#include "simulation/channel_model.h"

Include dependency graph for api.cpp:

Go to the source code of this file.

Classes
struct	fers_context

Functions
static void	handle_api_exception (const std::exception &e, const std::string &function_name)
	Centralized exception handler for the C-API boundary.

static void	begin_warning_capture () noexcept

static void	complete_warning_capture ()

static void	discard_warning_capture () noexcept

fers_context_t *	fers_context_create ()
	Creates a new FERS simulation context.

void	fers_context_destroy (fers_context_t *context)
	Destroys a FERS simulation context and releases all associated memory.

static logging::Level	map_api_log_level (fers_log_level_t level)

static fers_log_level_t	map_internal_log_level (logging::Level level)

int	fers_configure_logging (fers_log_level_t level, const char *log_file_path)
	Configures the internal logger.

fers_log_level_t	fers_get_log_level ()
	Returns the current internal logger level.

void	fers_set_log_callback (fers_log_callback_t callback, void *user_data)
	Registers a callback for formatted log lines.

void	fers_log (fers_log_level_t level, const char *message)
	Submits a log message to the library's unified logging system.

int	fers_set_thread_count (unsigned num_threads)
	Sets the number of worker threads for the simulation.

int	fers_set_output_directory (fers_context_t context, const char out_dir)
	Sets the output directory for simulation results.

int	fers_load_scenario_from_xml_file (fers_context_t context, const char xml_filepath, const int validate)
	Loads a scenario into the context from a FERS XML file.

int	fers_load_scenario_from_xml_string (fers_context_t context, const char xml_content, const int validate)
	Loads a scenario into the context from a FERS XML string.

char *	fers_get_scenario_as_json (fers_context_t *context)
	Serializes the current simulation scenario into a JSON string.

char *	fers_get_scenario_as_xml (fers_context_t *context)
	Serializes the current simulation scenario into a FERS XML string.

char *	fers_get_last_output_metadata_json (fers_context_t *context)
	Returns JSON metadata for the most recent simulation output files.

int	fers_update_platform_from_json (fers_context_t context, uint64_t id, const char json)
	Updates a single platform's paths and name from JSON without full context recreation.

int	fers_update_parameters_from_json (fers_context_t context, const char json)
	Updates the global simulation parameters from JSON without full context recreation.

int	fers_update_antenna_from_json (fers_context_t context, const char json)
	Updates a single antenna from JSON without full context recreation.

int	fers_update_waveform_from_json (fers_context_t context, const char json)
	Updates a single waveform from JSON without full context recreation.

int	fers_update_transmitter_from_json (fers_context_t context, uint64_t id, const char json)
	Updates a single transmitter from JSON without full context recreation.

int	fers_update_receiver_from_json (fers_context_t context, uint64_t id, const char json)
	Updates a single receiver from JSON without full context recreation.

int	fers_update_target_from_json (fers_context_t context, uint64_t id, const char json)
	Updates a single target from JSON without full context recreation.

int	fers_update_monostatic_from_json (fers_context_t context, const char json)
	Updates a monostatic radar from JSON without full context recreation.

int	fers_update_timing_from_json (fers_context_t context, uint64_t id, const char json)
	Updates a single timing source from JSON without full context recreation.

int	fers_update_scenario_from_json (fers_context_t context, const char scenario_json)
	Updates the simulation scenario from a JSON string.

char *	fers_get_last_error_message ()
	Retrieves the last error message that occurred on the current thread.

char *	fers_get_last_warning_messages_json ()
	Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.

void	fers_free_string (char *str)
	Frees a string that was allocated and returned by the libfers API.

int	fers_run_simulation (fers_context_t context, fers_progress_callback_t callback, void user_data)
	Runs the simulation defined in the provided context.

int	fers_generate_kml (const fers_context_t context, const char output_kml_filepath)
	Generates a KML file for visualizing the scenario in the context.

math::Path::InterpType	to_cpp_interp_type (const fers_interp_type_t type)

math::RotationPath::InterpType	to_cpp_rot_interp_type (const fers_interp_type_t type)

fers_interpolated_path_t *	fers_get_interpolated_motion_path (const fers_motion_waypoint_t *waypoints, const size_t waypoint_count, const fers_interp_type_t interp_type, const size_t num_points)
	Calculates an interpolated motion path from a set of waypoints.

void	fers_free_interpolated_motion_path (fers_interpolated_path_t *path)
	Frees the memory allocated for an interpolated motion path.

fers_interpolated_rotation_path_t *	fers_get_interpolated_rotation_path (const fers_rotation_waypoint_t *waypoints, const size_t waypoint_count, const fers_interp_type_t interp_type, const fers_angle_unit_t angle_unit, const size_t num_points)
	Calculates an interpolated rotation path from a set of waypoints.

void	fers_free_interpolated_rotation_path (fers_interpolated_rotation_path_t *path)
	Frees the memory allocated for an interpolated rotation path.

fers_antenna_pattern_data_t *	fers_get_antenna_pattern (const fers_context_t *context, const uint64_t antenna_id, const size_t az_samples, const size_t el_samples, const double frequency_hz)
	Samples the gain pattern of a specified antenna and provides the data.

void	fers_free_antenna_pattern_data (fers_antenna_pattern_data_t *data)
	Frees the memory allocated for an antenna pattern data structure.

fers_visual_link_list_t *	fers_calculate_preview_links (const fers_context_t *context, const double time)
	Calculates visual links for a specific simulation time.

void	fers_free_preview_links (fers_visual_link_list_t *list)
	Frees the memory allocated for a preview link list.

Variables
thread_local std::string	last_error_message

thread_local std::vector< std::string >	last_warning_messages

Detailed Description

Implementation of the C-style FFI for the libfers core library.

This file provides the C implementations for the functions declared in api.h. It acts as the bridge between the C ABI and the C++ core, handling object creation/destruction, exception catching, error reporting, and type casting.

Definition in file api.cpp.

Function Documentation

◆ begin_warning_capture()

static void begin_warning_capture ( )

staticnoexcept

Definition at line 69 of file api.cpp.

{
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
}

References serial::rotation_warning_utils::clear_captured_warnings(), and last_warning_messages.

Referenced by fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ complete_warning_capture()

static void complete_warning_capture ( )

static

Definition at line 75 of file api.cpp.

{
    last_warning_messages = serial::rotation_warning_utils::take_captured_warnings();
}

References last_warning_messages, and serial::rotation_warning_utils::take_captured_warnings().

Referenced by fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ discard_warning_capture()

static void discard_warning_capture ( )

staticnoexcept

Definition at line 80 of file api.cpp.

{
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
}

References serial::rotation_warning_utils::clear_captured_warnings(), and last_warning_messages.

Referenced by fers_context_create(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_calculate_preview_links()

fers_visual_link_list_t * fers_calculate_preview_links	(	const fers_context_t *	context,
		double	time
	)

Calculates visual links for a specific simulation time.

Parameters

context	The simulation context.
time	The simulation time in seconds.

Returns: A pointer to a link list. Caller must free with fers_free_preview_links.

Definition at line 1137 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context passed to fers_calculate_preview_links";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = reinterpret_cast<const FersContext*>(context);
        // Call the core physics logic in channel_model.cpp
        const auto cpp_links = simulation::calculatePreviewLinks(*ctx->getWorld(), time);
 
        // Convert C++ vector to C-API struct
        auto* result = new fers_visual_link_list_t();
        result->count = cpp_links.size();
 
        if (!cpp_links.empty())
        {
            result->links = new fers_visual_link_t[result->count];
            for (size_t i = 0; i < result->count; ++i)
            {
                const auto& src = cpp_links[i];
                auto& dst = result->links[i];
 
                // Map enums
                switch (src.type)
                {
                case simulation::LinkType::Monostatic:
                    dst.type = FERS_LINK_MONOSTATIC;
                    break;
                case simulation::LinkType::BistaticTxTgt:
                    dst.type = FERS_LINK_BISTATIC_TX_TGT;
                    break;
                case simulation::LinkType::BistaticTgtRx:
                    dst.type = FERS_LINK_BISTATIC_TGT_RX;
                    break;
                case simulation::LinkType::DirectTxRx:
                    dst.type = FERS_LINK_DIRECT_TX_RX;
                    break;
                }
 
                dst.quality = (src.quality == simulation::LinkQuality::Strong) ? FERS_LINK_STRONG : FERS_LINK_WEAK;
 
                // Safe string copy
                std::strncpy(dst.label, src.label.c_str(), sizeof(dst.label) - 1);
                dst.label[sizeof(dst.label) - 1] = '\0';
 
                dst.source_id = static_cast<uint64_t>(src.source_id);
                dst.dest_id = static_cast<uint64_t>(src.dest_id);
                dst.origin_id = static_cast<uint64_t>(src.origin_id);
            }
        }
        else
        {
            result->links = nullptr;
        }
        return result;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_calculate_preview_links");
        return nullptr;
    }
}

References simulation::BistaticTgtRx, simulation::BistaticTxTgt, simulation::calculatePreviewLinks(), simulation::DirectTxRx, logging::ERROR, FERS_LINK_BISTATIC_TGT_RX, FERS_LINK_BISTATIC_TX_TGT, FERS_LINK_DIRECT_TX_RX, FERS_LINK_MONOSTATIC, FERS_LINK_STRONG, FERS_LINK_WEAK, handle_api_exception(), last_error_message, LOG, simulation::Monostatic, simulation::Strong, and fers_visual_link_t::type.

Here is the call graph for this function:

◆ fers_configure_logging()

int fers_configure_logging	(	fers_log_level_t	level,
		const char *	log_file_path
	)

Configures the internal logger.

Parameters

level	The minimum severity level to log.
log_file_path	Optional path to a log file. Pass NULL to disable file logging.

Returns: 0 on success, non-zero on error.

Definition at line 188 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        logging::logger.setLevel(map_api_log_level(level));
        if ((log_file_path != nullptr) && ((*log_file_path) != 0))
        {
            auto result = logging::logger.logToFile(log_file_path);
            if (!result)
            {
                last_error_message = result.error();
                return 1;
            }
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_configure_logging");
        return 1;
    }
}

References handle_api_exception(), last_error_message, logging::logger, logging::Logger::logToFile(), map_api_log_level(), and logging::Logger::setLevel().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_context_create()

fers_context_t * fers_context_create ( )

Creates a new FERS simulation context.

Allocates and initializes a new, empty simulation context in memory. This context serves as the container for a scenario loaded via one of the fers_load_... or fers_update_... functions.

Note: In a C API, RAII is not available. The caller is responsible for destroying the returned context using fers_context_destroy() to prevent resource leaks.

Returns: A non-null opaque pointer (handle) to the simulation context on success. Returns NULL on failure (e.g., out of memory).

Definition at line 88 of file api.cpp.

{
    last_error_message.clear();
    discard_warning_capture();
    try
    {
        return new fers_context_t();
    }
    catch (const std::bad_alloc& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
}

References discard_warning_capture(), handle_api_exception(), and last_error_message.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_context_destroy()

void fers_context_destroy ( fers_context_t * context )

Destroys a FERS simulation context and releases all associated memory.

This function must be called for every context created by fers_context_create() to ensure proper cleanup of the underlying C++ objects. Accessing the context handle after calling this function results in undefined behavior.

Parameters

context A valid pointer to a fers_context_t handle. If context is NULL, the function performs no action for safety and does not set an error.

Definition at line 108 of file api.cpp.

{
    if (context == nullptr)
    {
        return;
    }
    delete context;
}

Referenced by main().

Here is the caller graph for this function:

◆ fers_free_antenna_pattern_data()

void fers_free_antenna_pattern_data ( fers_antenna_pattern_data_t * data )

Frees the memory allocated for an antenna pattern data structure.

Parameters

data	A pointer to the `fers_antenna_pattern_data_t` struct to free.

Definition at line 1126 of file api.cpp.

{
    if (data != nullptr)
    {
        delete[] data->gains;
        delete data;
    }
}

References fers_antenna_pattern_data_t::gains.

◆ fers_free_interpolated_motion_path()

void fers_free_interpolated_motion_path ( fers_interpolated_path_t * path )

Frees the memory allocated for an interpolated motion path.

Parameters

path	A pointer to the `fers_interpolated_path_t` struct to free.

Definition at line 933 of file api.cpp.

{
    if (path != nullptr)
    {
        delete[] path->points;
        delete path;
    }
}

References fers_interpolated_path_t::points.

◆ fers_free_interpolated_rotation_path()

void fers_free_interpolated_rotation_path ( fers_interpolated_rotation_path_t * path )

Frees the memory allocated for an interpolated rotation path.

Parameters

path	A pointer to the `fers_interpolated_rotation_path_t` struct to free.

Definition at line 1029 of file api.cpp.

{
    if (path != nullptr)
    {
        delete[] path->points;
        delete path;
    }
}

References fers_interpolated_rotation_path_t::points.

◆ fers_free_preview_links()

void fers_free_preview_links ( fers_visual_link_list_t * list )

Frees the memory allocated for a preview link list.

Parameters

list	The list to free.

Definition at line 1206 of file api.cpp.

{
    if (list != nullptr)
    {
        delete[] list->links;
        delete list;
    }
}

References fers_visual_link_list_t::links.

◆ fers_free_string()

void fers_free_string ( char * str )

Frees a string that was allocated and returned by the libfers API.

This function must be used to release memory for any string returned by functions like fers_get_scenario_as_json or fers_get_last_error_message. It exists to ensure that the memory deallocation mechanism (free) matches the allocation mechanism (strdup/malloc) used within the C++ library, preventing potential crashes from mismatched allocators across language boundaries.

Parameters

str	A pointer to the string to be freed. If str is NULL, no action is taken.

Definition at line 752 of file api.cpp.

{
    if (str != nullptr)
    {
        free(str);
    }
}

Referenced by main().

Here is the caller graph for this function:

◆ fers_generate_kml()

int fers_generate_kml	(	const fers_context_t *	context,
		const char *	output_kml_filepath
	)

Generates a KML file for visualizing the scenario in the context.

This utility exists to provide a simple, out-of-the-box method for users to validate and visualize the geographic layout and motion paths of their scenarios in common external tools like Google Earth.

Parameters

context	A valid `fers_context_t` handle containing a loaded scenario.
output_kml_filepath	A null-terminated UTF-8 string for the output KML file path.

Returns: 0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 798 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (output_kml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or output_kml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    const auto* ctx = reinterpret_cast<const FersContext*>(context);
 
    try
    {
        if (serial::KmlGenerator::generateKml(*ctx->getWorld(), output_kml_filepath))
        {
            return 0; // Success
        }
 
        last_error_message = "KML generation failed for an unknown reason.";
        LOG(logging::Level::ERROR, last_error_message);
        return 2; // Generation failed
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_generate_kml");
        return 1; // Exception thrown
    }
}

References logging::ERROR, serial::KmlGenerator::generateKml(), handle_api_exception(), last_error_message, and LOG.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_get_antenna_pattern()

fers_antenna_pattern_data_t * fers_get_antenna_pattern	(	const fers_context_t *	context,
		uint64_t	antenna_id,
		size_t	az_samples,
		size_t	el_samples,
		double	frequency_hz
	)

Samples the gain pattern of a specified antenna and provides the data.

This function calculates the antenna's far-field gain at a specified resolution over the full sphere of directions (azimuth and elevation). The resulting gain values are linear (not in dB) and normalized relative to the pattern's peak gain. This is a stateless utility useful for UI previews and analysis.

Parameters

context	A valid `fers_context_t` handle containing a loaded scenario with the antenna.
antenna_id	The unique ID of the antenna asset to sample.
az_samples	The desired number of sample points along the azimuth axis. Must be at least 2 to span the full azimuth range.
el_samples	The desired number of sample points along the elevation axis. Must be at least 2 to span the full elevation range.
frequency_hz	The frequency in Hz to use for gain calculation (affects aperture antennas).

Returns: A pointer to a fers_antenna_pattern_data_t struct containing the results. Returns NULL on failure (e.g., antenna not found). The caller owns the returned struct and must free it with fers_free_antenna_pattern_data.

Definition at line 1040 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || az_samples < 2 || el_samples < 2)
    {
        last_error_message = "Invalid arguments: context must be non-null and sample counts must be >= 2.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = reinterpret_cast<const FersContext*>(context);
        antenna::Antenna* ant = ctx->getWorld()->findAntenna(static_cast<SimId>(antenna_id));
 
        if (ant == nullptr)
        {
            last_error_message = "Antenna ID '" + std::to_string(antenna_id) + "' not found in the world.";
            LOG(logging::Level::ERROR, last_error_message);
            return nullptr;
        }
 
        // TODO: Currently only using the first-found waveform. This is incorrect but also difficult to represent
        //       correctly in scenarios with multiple waveforms as the gain for squarehorn and parabolic antennas
        // depends on        the wavelength. Hence a decision needs to be made about whether to return multiple patterns
        // per waveform or       have the user specify a representative wavelength in the UI per antenna.
        // Calculate wavelength from the provided frequency.
        // Default to 1GHz (0.3m) if frequency is invalid/zero, though the UI should prevent this
        // for antennas that strictly require it (Horn/Parabolic).
        RealType wavelength = 0.3;
        if (frequency_hz > 0.0)
        {
            wavelength = params::c() / frequency_hz;
        }
 
        auto* data = new fers_antenna_pattern_data_t();
        data->az_count = az_samples;
        data->el_count = el_samples;
        const size_t total_samples = az_samples * el_samples;
        data->gains = new double[total_samples];
 
        // The reference angle (boresight) is implicitly the local X-axis in the FERS engine.
        // We pass a zero rotation to get the gain relative to this boresight.
        const math::SVec3 ref_angle(1.0, 0.0, 0.0);
        double max_gain = 0.0;
 
        const RealType az_denominator = static_cast<RealType>(az_samples - 1);
        const RealType el_denominator = static_cast<RealType>(el_samples - 1);
 
        for (size_t i = 0; i < el_samples; ++i)
        {
            // Elevation from -PI/2 to PI/2
            const RealType elevation = (static_cast<RealType>(i) / el_denominator) * PI - (PI / 2.0);
            for (size_t j = 0; j < az_samples; ++j)
            {
                // Azimuth from -PI to PI
                const RealType azimuth = (static_cast<RealType>(j) / az_denominator) * 2.0 * PI - PI;
                const math::SVec3 sample_angle(1.0, azimuth, elevation);
                const RealType gain = ant->getGain(sample_angle, ref_angle, wavelength);
                data->gains[i * az_samples + j] = gain;
                max_gain = std::max(gain, max_gain);
            }
        }
 
        data->max_gain = max_gain;
 
        // Normalize the gains
        if (max_gain > 0)
        {
            for (size_t i = 0; i < total_samples; ++i)
            {
                data->gains[i] /= max_gain;
            }
        }
 
        return data;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_antenna_pattern");
        return nullptr;
    }
}

References params::c(), logging::ERROR, antenna::Antenna::getGain(), handle_api_exception(), last_error_message, LOG, and PI.

Here is the call graph for this function:

◆ fers_get_interpolated_motion_path()

fers_interpolated_path_t * fers_get_interpolated_motion_path	(	const fers_motion_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		size_t	num_points
	)

Calculates an interpolated motion path from a set of waypoints.

This function is a stateless utility that computes the path without needing a full simulation context. It is useful for UI previews.

Parameters

waypoints	An array of `fers_motion_waypoint_t` structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use.
num_points	The desired number of points in the output interpolated path.

Returns: A pointer to a fers_interpolated_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_motion_path.

Definition at line 858 of file api.cpp.

{
    last_error_message.clear();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        math::Path path;
        path.setInterp(to_cpp_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            math::Coord c;
            c.t = waypoints[i].time;
            c.pos.x = waypoints[i].x;
            c.pos.y = waypoints[i].y;
            c.pos.z = waypoints[i].z;
            path.addCoord(c);
        }
 
        path.finalize();
 
        auto* result_path = new fers_interpolated_path_t();
        result_path->points = new fers_interpolated_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::Vec3 pos = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = {pos.x, pos.y, pos.z, 0.0, 0.0, 0.0};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::Vec3 pos = path.getPosition(t);
            const math::Vec3 vel = path.getVelocity(t);
            result_path->points[i] = {pos.x, pos.y, pos.z, vel.x, vel.y, vel.z};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_interpolated_motion_path");
        return nullptr;
    }
}

References math::Path::addCoord(), logging::ERROR, FERS_INTERP_CUBIC, math::Path::finalize(), math::Path::getPosition(), math::Path::getVelocity(), handle_api_exception(), last_error_message, LOG, math::Path::setInterp(), fers_motion_waypoint_t::time, to_cpp_interp_type(), fers_motion_waypoint_t::x, math::Vec3::x, fers_motion_waypoint_t::y, math::Vec3::y, fers_motion_waypoint_t::z, and math::Vec3::z.

Here is the call graph for this function:

◆ fers_get_interpolated_rotation_path()

fers_interpolated_rotation_path_t * fers_get_interpolated_rotation_path	(	const fers_rotation_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		fers_angle_unit_t	angle_unit,
		size_t	num_points
	)

Calculates an interpolated rotation path from a set of waypoints.

This function is a stateless utility for UI previews.

Parameters

waypoints	An array of `fers_rotation_waypoint_t` structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use (STATIC, LINEAR, CUBIC).
angle_unit	The unit used by the waypoint angles and desired output angles.
num_points	The desired number of points in the output interpolated path.

Returns: A pointer to a fers_interpolated_rotation_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_rotation_path.

Definition at line 942 of file api.cpp.

{
    last_error_message.clear();
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto unit =
            angle_unit == FERS_ANGLE_UNIT_RAD ? params::RotationAngleUnit::Radians : params::RotationAngleUnit::Degrees;
        math::RotationPath path;
        path.setInterp(to_cpp_rot_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].azimuth, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "azimuth");
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].elevation, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "elevation");
            path.addCoord(serial::rotation_angle_utils::external_rotation_to_internal(
                waypoints[i].azimuth, waypoints[i].elevation, waypoints[i].time, unit));
        }
 
        path.finalize();
 
        auto* result_path = new fers_interpolated_rotation_path_t();
        result_path->points = new fers_interpolated_rotation_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::SVec3 rot = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = fers_interpolated_rotation_point_t{
                    serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                    serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::SVec3 rot = path.getPosition(t);
 
            result_path->points[i] = fers_interpolated_rotation_point_t{
                serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        serial::rotation_warning_utils::clear_captured_warnings();
        handle_api_exception(e, "fers_get_interpolated_rotation_path");
        return nullptr;
    }
}

References math::RotationPath::addCoord(), serial::rotation_warning_utils::Angle, math::SVec3::azimuth, serial::rotation_warning_utils::clear_captured_warnings(), params::Degrees, math::SVec3::elevation, logging::ERROR, serial::rotation_angle_utils::external_rotation_to_internal(), FERS_ANGLE_UNIT_RAD, FERS_INTERP_CUBIC, math::RotationPath::finalize(), math::RotationPath::getPosition(), handle_api_exception(), serial::rotation_angle_utils::internal_azimuth_to_external(), serial::rotation_angle_utils::internal_elevation_to_external(), last_error_message, last_warning_messages, LOG, serial::rotation_warning_utils::maybe_warn_about_rotation_value(), params::Radians, math::RotationPath::setInterp(), fers_rotation_waypoint_t::time, and to_cpp_rot_interp_type().

Here is the call graph for this function:

◆ fers_get_last_error_message()

char * fers_get_last_error_message ( )

Retrieves the last error message that occurred on the current thread.

Because C++ exceptions cannot safely propagate across the FFI boundary into other languages, this function provides the standard C-style error reporting mechanism. The error state is stored in a thread-local variable to ensure that concurrent API calls from different threads do not overwrite each other's error messages. The error is cleared at the start of each fallible API call.

Note: Memory Management: The returned string's ownership is transferred to the caller. It MUST be freed using fers_free_string() to prevent memory leaks.

Returns: A dynamically allocated, null-terminated C-string containing the last error message, or NULL if no error has occurred.

Definition at line 728 of file api.cpp.

{
    if (last_error_message.empty())
    {
        return nullptr; // No error to report
    }
    // `strdup` allocates with `malloc`, which is part of the C standard ABI,
    // making it safe to transfer ownership across the FFI boundary. The caller
    // must then free this memory using `fers_free_string`.
    return strdup(last_error_message.c_str());
}

References last_error_message.

Referenced by main().

Here is the caller graph for this function:

◆ fers_get_last_output_metadata_json()

char * fers_get_last_output_metadata_json ( fers_context_t * context )

Returns JSON metadata for the most recent simulation output files.

The returned JSON describes generated HDF5 file structure and sample ranges. The caller owns the returned string and must free it with fers_free_string. If no simulation has completed yet, the returned JSON contains an empty files array.

Parameters

context A valid fers_context_t handle.

Returns: A heap-allocated JSON string, or NULL on error.

Definition at line 427 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_last_output_metadata_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const std::string json_str = ctx->getLastOutputMetadataJson();
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_last_output_metadata_json");
        return nullptr;
    }
}

References logging::ERROR, FersContext::getLastOutputMetadataJson(), handle_api_exception(), last_error_message, and LOG.

Here is the call graph for this function:

◆ fers_get_last_warning_messages_json()

char * fers_get_last_warning_messages_json ( )

Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.

The returned value is a JSON array of strings. It is populated by successful XML/JSON load and update calls that detect suspicious rotation values. The caller owns the string and must free it with fers_free_string().

Returns: A dynamically allocated JSON array string, or NULL if no warnings are available.

Definition at line 740 of file api.cpp.

{
    if (last_warning_messages.empty())
    {
        return nullptr;
    }
 
    const std::string warning_json = nlohmann::json(last_warning_messages).dump();
    last_warning_messages.clear();
    return strdup(warning_json.c_str());
}

References last_warning_messages.

◆ fers_get_log_level()

fers_log_level_t fers_get_log_level ( )

Returns the current internal logger level.

Definition at line 212 of file api.cpp.

212{ return map_internal_log_level(logging::logger.getLevel()); }

map_internal_log_level

static fers_log_level_t map_internal_log_level(logging::Level level)

Definition api.cpp:141

References logging::logger, and map_internal_log_level().

Here is the call graph for this function:

◆ fers_get_scenario_as_json()

char * fers_get_scenario_as_json ( fers_context_t * context )

Serializes the current simulation scenario into a JSON string.

This function is the primary method for the UI to retrieve the full state of the simulation. JSON is used as the interchange format because it is lightweight, human-readable, and natively supported by web technologies, making it trivial to parse and use in the React/TypeScript frontend.

Note: Memory Management: The returned string is allocated by this library and its ownership is transferred to the caller. It is crucial to free this string using fers_free_string() to prevent memory leaks.

Parameters

context A valid fers_context_t handle.

Returns: A dynamically allocated, null-terminated C-string containing the JSON representation of the scenario. Returns NULL on failure.

Definition at line 370 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const nlohmann::json j = serial::world_to_json(*ctx->getWorld());
        const std::string json_str = j.dump(2);
        // A heap-allocated copy of the string is returned. This is necessary
        // to transfer ownership of the memory across the FFI boundary to a
        // client that will free it using `fers_free_string`.
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_json");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_json().

Here is the call graph for this function:

◆ fers_get_scenario_as_xml()

char * fers_get_scenario_as_xml ( fers_context_t * context )

Serializes the current simulation scenario into a FERS XML string.

This function enables exporting the in-memory state back into the standard FERS XML file format. This is essential for interoperability with legacy tools and for allowing a user to save a scenario that was created or modified in the UI.

Note: Memory Management: The returned string is dynamically allocated and its ownership is transferred to the caller. It must be freed using fers_free_string() to prevent memory leaks.

Parameters

context A valid fers_context_t handle.

Returns: A dynamically allocated, null-terminated C-string containing the XML representation of the scenario. Returns NULL on failure.

Definition at line 397 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_xml.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const std::string xml_str = serial::world_to_xml_string(*ctx->getWorld());
        if (xml_str.empty())
        {
            throw std::runtime_error("XML serialization resulted in an empty string.");
        }
        // `strdup` is used to create a heap-allocated string that can be safely
        // passed across the FFI boundary. The client is responsible for freeing
        // this memory with `fers_free_string`.
        return strdup(xml_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_xml");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_xml_string().

Here is the call graph for this function:

◆ fers_load_scenario_from_xml_file()

int fers_load_scenario_from_xml_file	(	fers_context_t *	context,
		const char *	xml_filepath,
		int	validate
	)

Loads a scenario into the context from a FERS XML file.

This is the standard method for initializing a simulation context from a file on disk. It is essential for interoperability with the CLI and legacy workflows that rely on the FERS XML format.

Parameters

context	A valid `fers_context_t` handle.
xml_filepath	A null-terminated UTF-8 string for the input XML file path.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema. Validation is recommended to ensure scenario correctness.

Returns: 0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 274 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        // Set default output directory to the scenario file's directory
        std::filesystem::path p(xml_filepath);
        auto parent = p.parent_path();
        if (parent.empty())
            parent = ".";
        ctx->setOutputDir(parent.string());
 
        serial::parseSimulation(xml_filepath, ctx->getWorld(), static_cast<bool>(validate), ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This is done
        // to ensure simulation reproducibility. If the scenario specifies a seed,
        // it is used; otherwise, a non-deterministic seed is generated so that
        // subsequent runs are unique by default.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario file: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_file");
        return 1; // Error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulation(), and params::Parameters::random_seed.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_load_scenario_from_xml_string()

int fers_load_scenario_from_xml_string	(	fers_context_t *	context,
		const char *	xml_content,
		int	validate
	)

Loads a scenario into the context from a FERS XML string.

This function provides a way to load a scenario from an in-memory string, avoiding file I/O. It is useful for test harnesses or for UIs that manage scenarios as text content before parsing.

Parameters

context	A valid `fers_context_t` handle.
xml_content	A null-terminated UTF-8 string containing the FERS scenario in XML format.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema.

Returns: 0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 325 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_content == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_content is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        serial::parseSimulationFromString(xml_content, ctx->getWorld(), static_cast<bool>(validate),
                                          ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This ensures
        // that if the scenario provides a seed, the simulation will be
        // reproducible. If not, a random seed is used to ensure unique runs.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario string: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
 
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_string");
        return 1; // Parsing or logic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulationFromString(), and params::Parameters::random_seed.

Here is the call graph for this function:

◆ fers_log()

void fers_log	(	fers_log_level_t	level,
		const char *	message
	)

Submits a log message to the library's unified logging system.

This ensures CLI messages match the format (timestamps, alignment) of library messages.

Definition at line 225 of file api.cpp.

{
    if (message == nullptr)
        return;
    // We pass a default source_location because C-API calls don't provide C++ source info
    logging::logger.log(map_api_log_level(level), message, std::source_location::current());
}

References logging::Logger::log(), logging::logger, and map_api_log_level().

Here is the call graph for this function:

◆ fers_run_simulation()

int fers_run_simulation	(	fers_context_t *	context,
		fers_progress_callback_t	callback,
		void *	user_data
	)

Runs the simulation defined in the provided context.

This function is synchronous and will block the calling thread until the simulation is complete. This design keeps the API simple. For use in a responsive UI, it is the responsibility of the caller (e.g., the Tauri backend) to invoke this function on a separate worker thread to avoid freezing the user interface.

Parameters

context	A valid `fers_context_t` handle containing a loaded scenario.
callback	A function pointer to a progress callback. Can be NULL.
user_data	An opaque pointer passed to the callback function.

Returns: 0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 760 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_run_simulation.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
 
    // Wrap the C-style callback in a std::function for easier use in C++.
    // This also handles the case where the callback is null.
    std::function<void(const std::string&, int, int)> progress_fn;
    if (callback != nullptr)
    {
        progress_fn = [callback, user_data](const std::string& msg, const int current, const int total)
        { callback(msg.c_str(), current, total, user_data); };
    }
 
    try
    {
        pool::ThreadPool pool(params::renderThreads());
 
        ctx->clearLastOutputMetadata();
        const auto output_metadata = core::runEventDrivenSim(ctx->getWorld(), pool, progress_fn, ctx->getOutputDir());
        ctx->setLastOutputMetadata(output_metadata);
 
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_run_simulation");
        return 1;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, params::renderThreads(), and core::runEventDrivenSim().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_set_log_callback()

void fers_set_log_callback	(	fers_log_callback_t	callback,
		void *	user_data
	)

Registers a callback for formatted log lines.

Pass NULL as callback to disable log callbacks.

Definition at line 214 of file api.cpp.

{
    {
        std::scoped_lock lock(log_callback_mutex);
        log_callback = callback;
        log_callback_user_data = user_data;
    }
 
    logging::logger.setCallback(callback == nullptr ? nullptr : forward_log_callback, nullptr);
}

References logging::logger, and logging::Logger::setCallback().

Here is the call graph for this function:

◆ fers_set_output_directory()

int fers_set_output_directory	(	fers_context_t *	context,
		const char *	out_dir
	)

Sets the output directory for simulation results.

Parameters

context	A valid `fers_context_t` handle.
out_dir	A null-terminated UTF-8 string for the output directory path.

Returns: 0 on success, non-zero on error.

Definition at line 252 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (out_dir == nullptr))
    {
        last_error_message = "Invalid arguments: context or out_dir is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        ctx->setOutputDir(out_dir);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_output_directory");
        return 1;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and FersContext::setOutputDir().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_set_thread_count()

int fers_set_thread_count ( unsigned num_threads )

Sets the number of worker threads for the simulation.

Parameters

num_threads The number of threads to use.

Returns: 0 on success, non-zero on error. This function clears any previous thread-local error message at entry, like the other fallible API calls.

Definition at line 233 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        if (auto res = params::setThreads(num_threads); !res)
        {
            last_error_message = res.error();
            return 1;
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_thread_count");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and params::setThreads().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fers_update_antenna_from_json()

int fers_update_antenna_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single antenna from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
json	The JSON string for the antenna.

Returns: 0 on success, non-zero on failure.

Definition at line 511 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        auto id = j.at("id").is_string() ? std::stoull(j.at("id").get<std::string>()) : j.at("id").get<uint64_t>();
        auto* ant = ctx->getWorld()->findAntenna(id);
        if (ant == nullptr)
        {
            last_error_message = "Antenna not found";
            return 1;
        }
        serial::update_antenna_from_json(j, ant, *ctx->getWorld());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_antenna_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_antenna_from_json().

Here is the call graph for this function:

◆ fers_update_monostatic_from_json()

int fers_update_monostatic_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a monostatic radar from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
json	The JSON string for the monostatic component.

Returns: 0 on success, non-zero on failure.

Definition at line 635 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        uint64_t tx_id =
            j.at("tx_id").is_string() ? std::stoull(j.at("tx_id").get<std::string>()) : j.at("tx_id").get<uint64_t>();
        uint64_t rx_id =
            j.at("rx_id").is_string() ? std::stoull(j.at("rx_id").get<std::string>()) : j.at("rx_id").get<uint64_t>();
        auto* tx = ctx->getWorld()->findTransmitter(tx_id);
        auto* rx = ctx->getWorld()->findReceiver(rx_id);
        if ((tx == nullptr) || (rx == nullptr))
        {
            last_error_message = "Monostatic components not found";
            return 1;
        }
        serial::update_monostatic_from_json(j, tx, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_monostatic_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_monostatic_from_json().

Here is the call graph for this function:

◆ fers_update_parameters_from_json()

int fers_update_parameters_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates the global simulation parameters from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
json	The JSON string for the parameters.

Returns: 0 on success, non-zero on failure.

Definition at line 486 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        serial::update_parameters_from_json(j, ctx->getMasterSeeder());
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_parameters_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), handle_api_exception(), last_error_message, and serial::update_parameters_from_json().

Here is the call graph for this function:

◆ fers_update_platform_from_json()

int fers_update_platform_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single platform's paths and name from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
id	The unique ID of the platform.
json	The JSON string for the platform.

Returns: 0 on success, non-zero on failure.

Definition at line 450 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* p = ctx->getWorld()->findPlatform(id);
        if (p == nullptr)
        {
            last_error_message = "Platform not found";
            discard_warning_capture();
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_platform_paths_from_json(j, p);
        if (j.contains("name"))
        {
            p->setName(j.at("name").get<std::string>());
        }
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_platform_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), core::World::findPlatform(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_platform_paths_from_json().

Here is the call graph for this function:

◆ fers_update_receiver_from_json()

int fers_update_receiver_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single receiver from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
id	The unique ID of the receiver.
json	The JSON string for the receiver.

Returns: 0 on success, non-zero on failure.

Definition at line 585 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* rx = ctx->getWorld()->findReceiver(id);
        if (rx == nullptr)
        {
            last_error_message = "Receiver not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_receiver_from_json(j, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_receiver_from_json");
        return 1;
    }
}

References core::World::findReceiver(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_receiver_from_json().

Here is the call graph for this function:

◆ fers_update_scenario_from_json()

int fers_update_scenario_from_json	(	fers_context_t *	context,
		const char *	scenario_json
	)

Updates the simulation scenario from a JSON string.

This is the primary method for the UI to push its state back to the C++ core. It performs a full replacement of the existing scenario.

Parameters

context	A valid `fers_context_t` handle.
scenario_json	A null-terminated UTF-8 string containing the FERS scenario in JSON format.

Returns: 0 on success. 1 on generic logic error. 2 on JSON parsing/schema validation error. Use fers_get_last_error_message() to retrieve error details.

Definition at line 689 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (scenario_json == nullptr))
    {
        last_error_message = "Invalid arguments: context or scenario_json is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const nlohmann::json j = nlohmann::json::parse(scenario_json);
        serial::json_to_world(j, *ctx->getWorld(), ctx->getMasterSeeder());
        complete_warning_capture();
 
        return 0; // Success
    }
    catch (const nlohmann::json::exception& e)
    {
        // A specific catch block for JSON errors is used to provide more
        // detailed feedback to the client (e.g., the UI), which can help
        // developers diagnose schema or data format issues more easily.
        last_error_message = "JSON parsing/deserialization error: " + std::string(e.what());
        LOG(logging::Level::ERROR, "API Error in {}: {}", "fers_update_scenario_from_json", last_error_message);
        discard_warning_capture();
        return 2; // JSON error
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_scenario_from_json");
        return 1; // Generic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), serial::json_to_world(), last_error_message, and LOG.

Here is the call graph for this function:

◆ fers_update_target_from_json()

int fers_update_target_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single target from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
id	The unique ID of the target.
json	The JSON string for the target.

Returns: 0 on success, non-zero on failure.

Definition at line 610 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* tgt = ctx->getWorld()->findTarget(id);
        if (tgt == nullptr)
        {
            last_error_message = "Target not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_target_from_json(j, tgt, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_target_from_json");
        return 1;
    }
}

References core::World::findTarget(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_target_from_json().

Here is the call graph for this function:

◆ fers_update_timing_from_json()

int fers_update_timing_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single timing source from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
id	The unique ID of the timing source.
json	The JSON string for the timing source.

Returns: 0 on success, non-zero on failure.

Definition at line 665 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        if (ctx->getWorld()->findTiming(id) == nullptr)
        {
            last_error_message = "Timing not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_timing_from_json(j, *ctx->getWorld(), id);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_timing_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_timing_from_json().

Here is the call graph for this function:

◆ fers_update_transmitter_from_json()

int fers_update_transmitter_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single transmitter from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
id	The unique ID of the transmitter.
json	The JSON string for the transmitter.

Returns: 0 on success, non-zero on failure.

Definition at line 560 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* tx = ctx->getWorld()->findTransmitter(id);
        if (tx == nullptr)
        {
            last_error_message = "Transmitter not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_transmitter_from_json(j, tx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_transmitter_from_json");
        return 1;
    }
}

References core::World::findTransmitter(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_transmitter_from_json().

Here is the call graph for this function:

◆ fers_update_waveform_from_json()

int fers_update_waveform_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single waveform from JSON without full context recreation.

Parameters

context	A valid `fers_context_t` handle.
json	The JSON string for the waveform.

Returns: 0 on success, non-zero on failure.

Definition at line 537 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        auto wf = serial::parse_waveform_from_json(j);
        if (wf)
        {
            ctx->getWorld()->replace(std::move(wf));
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_waveform_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::parse_waveform_from_json().

Here is the call graph for this function:

◆ handle_api_exception()

static void handle_api_exception	(	const std::exception &	e,
		const std::string &	function_name
	)

static

Centralized exception handler for the C-API boundary.

This function catches standard C++ exceptions, records their what() message into the thread-local error storage, and logs the error. This prevents C++ exceptions from propagating across the FFI boundary, which would be undefined behavior.

Parameters

e	The exception that was caught.
function_name	The name of the API function where the error occurred.

Definition at line 63 of file api.cpp.

{
    last_error_message = e.what();
    LOG(logging::Level::ERROR, "API Error in {}: {}", function_name, last_error_message);
}

References logging::ERROR, last_error_message, and LOG.

Here is the caller graph for this function:

◆ map_api_log_level()

static logging::Level map_api_log_level ( fers_log_level_t level )

static

Definition at line 118 of file api.cpp.

{
    switch (level)
    {
    case FERS_LOG_TRACE:
        return logging::Level::TRACE;
    case FERS_LOG_DEBUG:
        return logging::Level::DEBUG;
    case FERS_LOG_INFO:
        return logging::Level::INFO;
    case FERS_LOG_WARNING:
        return logging::Level::WARNING;
    case FERS_LOG_ERROR:
        return logging::Level::ERROR;
    case FERS_LOG_FATAL:
        return logging::Level::FATAL;
    case FERS_LOG_OFF:
        return logging::Level::OFF;
    default:
        return logging::Level::INFO;
    }
}

References logging::DEBUG, logging::ERROR, logging::FATAL, FERS_LOG_DEBUG, FERS_LOG_ERROR, FERS_LOG_FATAL, FERS_LOG_INFO, FERS_LOG_OFF, FERS_LOG_TRACE, FERS_LOG_WARNING, logging::INFO, logging::OFF, logging::TRACE, and logging::WARNING.

Referenced by fers_configure_logging(), and fers_log().

Here is the caller graph for this function:

◆ map_internal_log_level()

static fers_log_level_t map_internal_log_level ( logging::Level level )

static

Definition at line 141 of file api.cpp.

{
    switch (level)
    {
    case logging::Level::TRACE:
        return FERS_LOG_TRACE;
    case logging::Level::DEBUG:
        return FERS_LOG_DEBUG;
    case logging::Level::INFO:
        return FERS_LOG_INFO;
    case logging::Level::WARNING:
        return FERS_LOG_WARNING;
    case logging::Level::ERROR:
        return FERS_LOG_ERROR;
    case logging::Level::FATAL:
        return FERS_LOG_FATAL;
    case logging::Level::OFF:
        return FERS_LOG_OFF;
    default:
        return FERS_LOG_INFO;
    }
}

References logging::DEBUG, logging::ERROR, logging::FATAL, FERS_LOG_DEBUG, FERS_LOG_ERROR, FERS_LOG_FATAL, FERS_LOG_INFO, FERS_LOG_OFF, FERS_LOG_TRACE, FERS_LOG_WARNING, logging::INFO, logging::OFF, logging::TRACE, and logging::WARNING.

Referenced by fers_get_log_level().

Here is the caller graph for this function:

◆ to_cpp_interp_type()

math::Path::InterpType to_cpp_interp_type ( const fers_interp_type_t type )

Definition at line 829 of file api.cpp.

{
    switch (type)
    {
    case FERS_INTERP_LINEAR:
        return math::Path::InterpType::INTERP_LINEAR;
    case FERS_INTERP_CUBIC:
        return math::Path::InterpType::INTERP_CUBIC;
    case FERS_INTERP_STATIC:
    default:
        return math::Path::InterpType::INTERP_STATIC;
    }
}

References FERS_INTERP_CUBIC, FERS_INTERP_LINEAR, FERS_INTERP_STATIC, math::Path::INTERP_CUBIC, math::Path::INTERP_LINEAR, and math::Path::INTERP_STATIC.

Referenced by fers_get_interpolated_motion_path().

Here is the caller graph for this function:

◆ to_cpp_rot_interp_type()

math::RotationPath::InterpType to_cpp_rot_interp_type ( const fers_interp_type_t type )

Definition at line 843 of file api.cpp.

{
    switch (type)
    {
    case FERS_INTERP_LINEAR:
        return math::RotationPath::InterpType::INTERP_LINEAR;
    case FERS_INTERP_CUBIC:
        return math::RotationPath::InterpType::INTERP_CUBIC;
    case FERS_INTERP_STATIC:
    default:
        return math::RotationPath::InterpType::INTERP_STATIC;
    }
}

References FERS_INTERP_CUBIC, FERS_INTERP_LINEAR, FERS_INTERP_STATIC, math::RotationPath::INTERP_CUBIC, math::RotationPath::INTERP_LINEAR, and math::RotationPath::INTERP_STATIC.

Referenced by fers_get_interpolated_rotation_path().

Here is the caller graph for this function:

Variable Documentation

◆ last_error_message

thread_local std::string last_error_message

Definition at line 51 of file api.cpp.

◆ last_warning_messages

thread_local std::vector<std::string> last_warning_messages

Definition at line 52 of file api.cpp.

Referenced by begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), fers_get_interpolated_rotation_path(), and fers_get_last_warning_messages_json().

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ begin_warning_capture()

◆ complete_warning_capture()

◆ discard_warning_capture()

◆ fers_calculate_preview_links()

◆ fers_configure_logging()

◆ fers_context_create()

◆ fers_context_destroy()

◆ fers_free_antenna_pattern_data()

◆ fers_free_interpolated_motion_path()

◆ fers_free_interpolated_rotation_path()

◆ fers_free_preview_links()

◆ fers_free_string()

◆ fers_generate_kml()

◆ fers_get_antenna_pattern()

◆ fers_get_interpolated_motion_path()

◆ fers_get_interpolated_rotation_path()

◆ fers_get_last_error_message()

◆ fers_get_last_output_metadata_json()

◆ fers_get_last_warning_messages_json()

◆ fers_get_log_level()

◆ fers_get_scenario_as_json()

◆ fers_get_scenario_as_xml()

◆ fers_load_scenario_from_xml_file()

◆ fers_load_scenario_from_xml_string()

◆ fers_log()

◆ fers_run_simulation()

◆ fers_set_log_callback()

◆ fers_set_output_directory()

◆ fers_set_thread_count()

◆ fers_update_antenna_from_json()

◆ fers_update_monostatic_from_json()

◆ fers_update_parameters_from_json()

◆ fers_update_platform_from_json()

◆ fers_update_receiver_from_json()

◆ fers_update_scenario_from_json()

◆ fers_update_target_from_json()

◆ fers_update_timing_from_json()

◆ fers_update_transmitter_from_json()

◆ fers_update_waveform_from_json()

◆ handle_api_exception()

◆ map_api_log_level()

◆ map_internal_log_level()

◆ to_cpp_interp_type()

◆ to_cpp_rot_interp_type()

Variable Documentation

◆ last_error_message

◆ last_warning_messages