api.cpp File Reference

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

#include <core/logging.h>
#include <core/parameters.h>
#include <cstring>
#include <functional>
#include <libfers/api.h>
#include <math/path.h>
#include <math/rotation_path.h>
#include <nlohmann/json.hpp>
#include <string>
#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/xml_parser.h"
#include "serial/xml_serializer.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.
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_level (fers_log_level_t level)
int	fers_configure_logging (fers_log_level_t level, const char *log_file_path)
	Configures the internal logger.
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_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.
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.
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 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 char *antenna_name, 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

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

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 725 of file api.cpp.

{
    last_error_message.clear();
    if (!context)
    {
        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';
 
                std::strncpy(dst.source_name, src.source_name.c_str(), sizeof(dst.source_name) - 1);
                dst.source_name[sizeof(dst.source_name) - 1] = '\0';
 
                std::strncpy(dst.dest_name, src.dest_name.c_str(), sizeof(dst.dest_name) - 1);
                dst.dest_name[sizeof(dst.dest_name) - 1] = '\0';
 
                std::strncpy(dst.origin_name, src.origin_name.c_str(), sizeof(dst.origin_name) - 1);
                dst.origin_name[sizeof(dst.origin_name) - 1] = '\0';
            }
        }
        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 112 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        logging::logger.setLevel(map_level(level));
        if (log_file_path && *log_file_path)
        {
            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_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 60 of file api.cpp.

{
    last_error_message.clear();
    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 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.

Definition at line 79 of file api.cpp.

{
    if (!context)
    {
        last_error_message = "Invalid context provided to fers_context_destroy.";
        LOG(logging::Level::WARNING, last_error_message);
        return;
    }
    delete context;
}

References last_error_message, LOG, and logging::WARNING.

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 714 of file api.cpp.

{
    if (data)
    {
        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 524 of file api.cpp.

{
    if (path)
    {
        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 617 of file api.cpp.

{
    if (path)
    {
        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 799 of file api.cpp.

{
    if (list)
    {
        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 346 of file api.cpp.

{
    if (str)
    {
        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 390 of file api.cpp.

{
    last_error_message.clear();
    if (!context || !output_kml_filepath)
    {
        last_error_message = "Invalid arguments: context or output_kml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    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,
		const char *	antenna_name,
		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_name	The name of the antenna asset to sample.
az_samples	The desired number of sample points along the azimuth axis.
el_samples	The desired number of sample points along the elevation axis.
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 628 of file api.cpp.

{
    last_error_message.clear();
    if (!context || !antenna_name || az_samples == 0 || el_samples == 0)
    {
        last_error_message = "Invalid arguments: context, antenna_name, or sample counts are invalid.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = reinterpret_cast<const FersContext*>(context);
        antenna::Antenna* ant = ctx->getWorld()->findAntenna(antenna_name);
 
        if (!ant)
        {
            last_error_message = "Antenna '" + std::string(antenna_name) + "' 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;
 
        for (size_t i = 0; i < el_samples; ++i)
        {
            // Elevation from -PI/2 to PI/2
            const RealType elevation = (static_cast<RealType>(i) / (el_samples - 1)) * 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_samples - 1)) * 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;
                if (gain > max_gain)
                {
                    max_gain = 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 450 of file api.cpp.

{
    last_error_message.clear();
    if (!waypoints || 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};
            }
            return result_path;
        }
 
        const double time_step = duration / (num_points > 1 ? num_points - 1 : 1);
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + 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,
		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).
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 533 of file api.cpp.

{
    last_error_message.clear();
    if (!waypoints || 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::RotationPath path;
        path.setInterp(to_cpp_rot_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            const RealType az_deg = waypoints[i].azimuth_deg;
            const RealType el_deg = waypoints[i].elevation_deg;
 
            // Convert from compass degrees (from C-API) to internal mathematical radians
            const RealType az_rad = (90.0 - az_deg) * (PI / 180.0);
            const RealType el_rad = el_deg * (PI / 180.0);
 
            path.addCoord({az_rad, el_rad, waypoints[i].time});
        }
 
        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);
            // Convert back to compass degrees for output without normalization
            const RealType az_deg = 90.0 - rot.azimuth * 180.0 / PI;
            const RealType el_deg = rot.elevation * 180.0 / PI;
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = {az_deg, el_deg};
            }
            return result_path;
        }
 
        const double time_step = duration / (num_points > 1 ? num_points - 1 : 1);
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + i * time_step;
            const math::SVec3 rot = path.getPosition(t);
 
            // Convert from internal mathematical radians back to compass degrees for C-API output
            // We do NOT normalize to [0, 360) to preserve winding/negative angles for the UI.
            const RealType az_deg = 90.0 - rot.azimuth * 180.0 / PI;
            const RealType el_deg = rot.elevation * 180.0 / PI;
 
            result_path->points[i] = {az_deg, el_deg};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_interpolated_rotation_path");
        return nullptr;
    }
}

References math::RotationPath::addCoord(), math::SVec3::azimuth, fers_rotation_waypoint_t::azimuth_deg, math::SVec3::elevation, fers_rotation_waypoint_t::elevation_deg, logging::ERROR, FERS_INTERP_CUBIC, math::RotationPath::finalize(), math::RotationPath::getPosition(), handle_api_exception(), last_error_message, LOG, PI, 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 334 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_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 243 of file api.cpp.

{
    last_error_message.clear();
    if (!context)
    {
        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 270 of file api.cpp.

{
    last_error_message.clear();
    if (!context)
    {
        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 162 of file api.cpp.

{
    last_error_message.clear();
    if (!context || !xml_filepath)
    {
        last_error_message = "Invalid arguments: context or xml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        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);
        }
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_load_scenario_from_xml_file");
        return 1; // Error
    }
}

References 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 202 of file api.cpp.

{
    last_error_message.clear();
    if (!context || !xml_content)
    {
        last_error_message = "Invalid arguments: context or xml_content is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        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);
        }
 
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_load_scenario_from_xml_string");
        return 1; // Parsing or logic error
    }
}

References 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 136 of file api.cpp.

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

References logging::Logger::log(), logging::logger, and map_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 354 of file api.cpp.

{
    last_error_message.clear();
    if (!context)
    {
        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)
    {
        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());
 
        core::runEventDrivenSim(ctx->getWorld(), pool, progress_fn);
 
        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_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.

Definition at line 144 of file api.cpp.

{
    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_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 300 of file api.cpp.

{
    last_error_message.clear();
    if (!context || !scenario_json)
    {
        last_error_message = "Invalid arguments: context or scenario_json is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        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());
 
        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);
        return 2; // JSON error
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_scenario_from_json");
        return 1; // Generic error
    }
}

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

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 52 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.

Referenced by fers_calculate_preview_links(), fers_configure_logging(), fers_context_create(), fers_generate_kml(), fers_get_antenna_pattern(), fers_get_interpolated_motion_path(), fers_get_interpolated_rotation_path(), fers_get_scenario_as_json(), fers_get_scenario_as_xml(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_run_simulation(), fers_set_thread_count(), and fers_update_scenario_from_json().

Here is the caller graph for this function:

map_level()

static logging::Level map_level ( fers_log_level_t  level )

static

Definition at line 91 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;
    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_TRACE, FERS_LOG_WARNING, logging::INFO, logging::TRACE, and logging::WARNING.

Referenced by fers_configure_logging(), and fers_log().

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 421 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 435 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 41 of file api.cpp.

Referenced by fers_calculate_preview_links(), fers_configure_logging(), fers_context_create(), fers_context_destroy(), fers_generate_kml(), fers_get_antenna_pattern(), fers_get_interpolated_motion_path(), fers_get_interpolated_rotation_path(), fers_get_last_error_message(), fers_get_scenario_as_json(), fers_get_scenario_as_xml(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_run_simulation(), fers_set_thread_count(), fers_update_scenario_from_json(), and handle_api_exception().