serial::xml_parser_utils Namespace Reference

Classes
struct	AssetLoaders
	Container for functions that load external file-backed assets. More...
struct	ParserContext
	Encapsulates the state required during the XML parsing process. More...
struct	ReferenceLookup
	Holds maps to resolve string names to internal SimId references during XML parsing. More...

Functions
RealType	get_child_real_type (const XmlElement &element, const std::string &elementName)
	Extracts a floating-point (RealType) value from a named child element.
bool	get_attribute_bool (const XmlElement &element, const std::string &attributeName, bool defaultVal)
	Extracts a boolean value from a named attribute.
SimId	assign_id_from_attribute (const std::string &owner, ObjectType type)
	Generates a unique SimId based on the requested object type.
SimId	resolve_reference_id (const XmlElement &element, const std::string &attributeName, const std::string &owner, const std::unordered_map< std::string, SimId > &name_map)
	Resolves an XML string reference into an internal SimId.
std::vector< radar::SchedulePeriod >	parseSchedule (const XmlElement &parent, const std::string &parentName, bool isPulsed, RealType pri=0.0)
	Parses a schedule (active periods) for a transmitter or receiver.
unsigned	parseUnsignedParameter (const std::string_view param_name, const RealType raw_value)
template<typename Setter >
void	setOptionalRealParameter (const XmlElement &parameters, const std::string &param_name, const RealType default_value, Setter setter)
template<typename Setter >
void	setOptionalUnsignedParameter (const XmlElement &parameters, const std::string &param_name, const unsigned default_value, Setter setter)
void	parseOptionalNumericParameters (const XmlElement &parameters, params::Parameters &params_out)
void	parseRotationAngleUnit (const XmlElement &parameters, params::Parameters &params_out)
bool	parseOriginParameter (const XmlElement &parameters, params::Parameters &params_out)
void	parseUtmCoordinateSystem (const XmlElement &cs_element, params::Parameters &params_out)
void	parseCoordinateSystemParameter (const XmlElement &parameters, params::Parameters &params_out, const bool origin_set)
void	parseParameters (const XmlElement &parameters, params::Parameters &params_out)
	Parses the <parameters> block into the isolated context parameters.
void	parseWaveform (const XmlElement &waveform, ParserContext &ctx)
	Parses a <waveform> block and adds it to the World.
void	parseTiming (const XmlElement &timing, ParserContext &ctx)
	Parses a <timing> block and adds the prototype timing to the World.
void	parseAntenna (const XmlElement &antenna, ParserContext &ctx)
	Parses an <antenna> block and adds it to the World.
void	parseMotionPath (const XmlElement &motionPath, radar::Platform *platform)
	Parses a <motionpath> block and attaches it to a Platform.
void	parseRotationPath (const XmlElement &rotation, radar::Platform *platform, params::RotationAngleUnit unit)
	Parses a <rotationpath> block and attaches it to a Platform.
void	parseFixedRotation (const XmlElement &rotation, radar::Platform *platform, params::RotationAngleUnit unit)
	Parses a <fixedrotation> block and attaches it to a Platform.
static radar::Transmitter *	parseTransmitterWithMode (const XmlElement &transmitter, radar::Platform *platform, ParserContext &ctx, const ReferenceLookup &refs, const radar::OperationMode mode)
	Parses a transmitter after its operation mode has already been determined.
radar::Transmitter *	parseTransmitter (const XmlElement &transmitter, radar::Platform *platform, ParserContext &ctx, const ReferenceLookup &refs)
	Parses a <transmitter> block, resolves its dependencies, and adds it to the World.
static radar::Receiver *	parseReceiverWithMode (const XmlElement &receiver, radar::Platform *platform, ParserContext &ctx, const ReferenceLookup &refs, const radar::OperationMode mode)
	Parses a receiver after its operation mode has already been determined.
radar::Receiver *	parseReceiver (const XmlElement &receiver, radar::Platform *platform, ParserContext &ctx, const ReferenceLookup &refs)
	Parses a <receiver> block, resolves its dependencies, and adds it to the World.
void	parseMonostatic (const XmlElement &monostatic, radar::Platform *platform, ParserContext &ctx, const ReferenceLookup &refs)
	Parses a <monostatic> block, creating a linked transmitter and receiver pair.
void	parseTarget (const XmlElement &target, radar::Platform *platform, ParserContext &ctx)
	Parses a <target> block and adds it to the World.
void	parsePlatformElements (const XmlElement &platform, ParserContext &ctx, radar::Platform *plat, const std::function< void(const XmlElement &, std::string_view)> &register_name, const ReferenceLookup &refs)
	Iterates and parses all children elements (radars, targets) of a platform.
void	parsePlatform (const XmlElement &platform, ParserContext &ctx, const std::function< void(const XmlElement &, std::string_view)> &register_name, const ReferenceLookup &refs)
	Parses a complete <platform> block, including its motion paths and sub-elements.
void	collectIncludeElements (const XmlDocument &doc, const fs::path &currentDir, std::vector< fs::path > &includePaths)
bool	addIncludeFilesToMainDocument (const XmlDocument &mainDoc, const fs::path &currentDir)
void	validateXml (bool didCombine, const XmlDocument &mainDoc)
	Validates an XML document against the embedded DTD and XSD schemas.
void	processParsedDocument (const XmlDocument &doc, ParserContext &ctx)
	Coordinates the full parsing of a validated XML document tree.
AssetLoaders	createDefaultAssetLoaders ()
	Creates an AssetLoaders struct populated with standard file-I/O implementations.
void	collectIncludeElements (const XmlDocument &doc, const std::filesystem::path &currentDir, std::vector< std::filesystem::path > &includePaths)
	Recursively finds all <include> tags in a document and resolves their absolute paths.
bool	addIncludeFilesToMainDocument (const XmlDocument &mainDoc, const std::filesystem::path &currentDir)
	Resolves and merges all <include> files directly into the provided main document.

Function Documentation

addIncludeFilesToMainDocument() [1/2]

bool serial::xml_parser_utils::addIncludeFilesToMainDocument	(	const XmlDocument &	mainDoc,
		const fs::path &	currentDir
	)

Definition at line 1362 of file xml_parser_utils.cpp.

    {
        std::vector<fs::path> include_paths;
        collectIncludeElements(mainDoc, currentDir, include_paths);
        bool did_combine = false;
 
        for (const auto& include_path : include_paths)
        {
            XmlDocument included_doc;
            if (!included_doc.loadFile(include_path.string()))
            {
                throw XmlException("Failed to load included XML file: " + include_path.string());
            }
 
            mergeXmlDocuments(mainDoc, included_doc);
            did_combine = true;
        }
 
        removeIncludeElements(mainDoc);
        return did_combine;
    }

References collectIncludeElements(), max, mergeXmlDocuments(), and removeIncludeElements().

Referenced by serial::parseSimulation().

Here is the call graph for this function:

Here is the caller graph for this function:

addIncludeFilesToMainDocument() [2/2]

bool serial::xml_parser_utils::addIncludeFilesToMainDocument	(	const XmlDocument &	mainDoc,
		const std::filesystem::path &	currentDir
	)

Resolves and merges all <include> files directly into the provided main document.

Parameters

mainDoc	The primary XML document that will be mutated.
currentDir	The base directory used to resolve include paths.

Returns

True if at least one file was included and merged, false otherwise.

assign_id_from_attribute()

SimId serial::xml_parser_utils::assign_id_from_attribute	(	const std::string &	owner,
		ObjectType	type
	)

Generates a unique SimId based on the requested object type.

Parameters

owner	The name/description of the object requesting the ID (used for logging).
type	The category/type of the object.

Returns

A newly generated SimId.

Definition at line 349 of file xml_parser_utils.cpp.

    {
        const SimId id = SimIdGenerator::instance().generateId(type);
        LOG(logging::Level::TRACE, "Assigned ID {} to {} (generated)", id, owner);
        return id;
    }

References SimIdGenerator::generateId(), SimIdGenerator::instance(), LOG, max, and logging::TRACE.

Referenced by parseAntenna(), parsePlatform(), parseReceiverWithMode(), parseTarget(), parseTiming(), parseTransmitterWithMode(), and parseWaveform().

Here is the call graph for this function:

Here is the caller graph for this function:

collectIncludeElements() [1/2]

void serial::xml_parser_utils::collectIncludeElements	(	const XmlDocument &	doc,
		const fs::path &	currentDir,
		std::vector< fs::path > &	includePaths
	)

Definition at line 1332 of file xml_parser_utils.cpp.

    {
        unsigned index = 0;
        while (true)
        {
            XmlElement const include_element = doc.getRootElement().childElement("include", index++);
            if (!include_element.isValid())
                break;
 
            std::string const include_filename = include_element.getText();
            if (include_filename.empty())
            {
                LOG(logging::Level::ERROR, "<include> element is missing the filename!");
                continue;
            }
 
            fs::path const include_path = currentDir / include_filename;
            includePaths.push_back(include_path);
 
            XmlDocument included_doc;
            if (!included_doc.loadFile(include_path.string()))
            {
                LOG(logging::Level::ERROR, "Failed to load included XML file: {}", include_path.string());
                continue;
            }
 
            collectIncludeElements(included_doc, include_path.parent_path(), includePaths);
        }
    }

References collectIncludeElements(), logging::ERROR, LOG, and max.

Referenced by addIncludeFilesToMainDocument(), and collectIncludeElements().

Here is the call graph for this function:

Here is the caller graph for this function:

collectIncludeElements() [2/2]

void serial::xml_parser_utils::collectIncludeElements	(	const XmlDocument &	doc,
		const std::filesystem::path &	currentDir,
		std::vector< std::filesystem::path > &	includePaths
	)

Recursively finds all <include> tags in a document and resolves their absolute paths.

Parameters

doc	The XML document to search.
currentDir	The base directory for resolving relative paths.
includePaths	A vector populated with the absolute paths of included files.

createDefaultAssetLoaders()

AssetLoaders serial::xml_parser_utils::createDefaultAssetLoaders

(

)

Creates an AssetLoaders struct populated with standard file-I/O implementations.

Provides the default hooks to load actual HDF5, XML, and binary waveform files from the filesystem into the simulation environment.

Returns

An AssetLoaders instance with standard file handlers attached.

Definition at line 1504 of file xml_parser_utils.cpp.

    {
        return {.loadWaveform = [](const std::string& name, const fs::path& pulse_path, RealType power,
                                   RealType carrierFreq, SimId id)
                { return serial::loadWaveformFromFile(name, pulse_path.string(), power, carrierFreq, id); },
                .loadXmlAntenna = [](const std::string& name, const std::string& filename, SimId id)
                { return std::make_unique<antenna::XmlAntenna>(name, filename, id); },
                .loadH5Antenna = [](const std::string& name, const std::string& filename, SimId id)
                { return std::make_unique<antenna::H5Antenna>(name, filename, id); },
                .loadFileTarget = [](radar::Platform* platform, const std::string& name, const std::string& filename,
                                     unsigned seed, SimId id)
                { return radar::createFileTarget(platform, name, filename, seed, id); }};
    }

References radar::createFileTarget(), serial::xml_parser_utils::AssetLoaders::loadWaveform, serial::loadWaveformFromFile(), and max.

Referenced by serial::parseSimulation(), and serial::parseSimulationFromString().

Here is the call graph for this function:

Here is the caller graph for this function:

get_attribute_bool()

bool serial::xml_parser_utils::get_attribute_bool	(	const XmlElement &	element,
		const std::string &	attributeName,
		bool	defaultVal
	)

Extracts a boolean value from a named attribute.

Parameters

element	The XML element containing the attribute.
attributeName	The name of the attribute.
defaultVal	The value to return if the attribute is missing or invalid.

Returns

The parsed boolean value, or the default if the attribute is missing or invalid.

Definition at line 327 of file xml_parser_utils.cpp.

    {
        const auto attr_value = XmlElement::getOptionalAttribute(element, attributeName);
        if (!attr_value.has_value())
        {
            LOG(logging::Level::DEBUG, "Attribute '{}' not specified. Defaulting to {}.", attributeName, defaultVal);
            return defaultVal;
        }
        if (*attr_value == "true")
        {
            return true;
        }
        if (*attr_value == "false")
        {
            return false;
        }
 
        LOG(logging::Level::WARNING, "Invalid boolean value '{}' for attribute '{}'. Defaulting to {}.", *attr_value,
            attributeName, defaultVal);
        return defaultVal;
    }

References logging::DEBUG, XmlElement::getOptionalAttribute(), LOG, max, and logging::WARNING.

Referenced by parseReceiverWithMode(), and parseTiming().

Here is the call graph for this function:

Here is the caller graph for this function:

get_child_real_type()

RealType serial::xml_parser_utils::get_child_real_type	(	const XmlElement &	element,
		const std::string &	elementName
	)

Extracts a floating-point (RealType) value from a named child element.

Parameters

element	The parent XML element.
elementName	The name of the child element to extract text from.

Returns

The parsed floating-point value.

Exceptions

XmlException

if the child element is missing or empty.

Definition at line 317 of file xml_parser_utils.cpp.

    {
        const std::string text = element.childElement(elementName, 0).getText();
        if (text.empty())
        {
            throw XmlException("Element " + elementName + " is empty!");
        }
        return std::stod(text);
    }

References max.

Referenced by parseAntenna(), parseFixedRotation(), parseMotionPath(), parseOptionalNumericParameters(), parseParameters(), parseReceiverWithMode(), parseRotationPath(), parseTarget(), parseTiming(), parseTransmitterWithMode(), parseWaveform(), setOptionalRealParameter(), and setOptionalUnsignedParameter().

Here is the caller graph for this function:

parseAntenna()

void serial::xml_parser_utils::parseAntenna	(	const XmlElement &	antenna,
		ParserContext &	ctx
	)

Parses an <antenna> block and adds it to the World.

Parameters

antenna	The <antenna> XML element.
ctx	The current parser context.

Definition at line 792 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(antenna, "name");
        const SimId id = assign_id_from_attribute("antenna '" + name + "'", ObjectType::Antenna);
        const std::string pattern = XmlElement::getSafeAttribute(antenna, "pattern");
 
        std::unique_ptr<antenna::Antenna> ant;
 
        LOG(logging::Level::DEBUG, "Adding antenna '{}' with pattern '{}'", name, pattern);
        if (pattern == "isotropic")
        {
            ant = std::make_unique<antenna::Isotropic>(name, id);
        }
        else if (pattern == "sinc")
        {
            ant = std::make_unique<antenna::Sinc>(name, get_child_real_type(antenna, "alpha"),
                                                  get_child_real_type(antenna, "beta"),
                                                  get_child_real_type(antenna, "gamma"), id);
        }
        else if (pattern == "gaussian")
        {
            ant = std::make_unique<antenna::Gaussian>(name, get_child_real_type(antenna, "azscale"),
                                                      get_child_real_type(antenna, "elscale"), id);
        }
        else if (pattern == "squarehorn")
        {
            ant = std::make_unique<antenna::SquareHorn>(name, get_child_real_type(antenna, "diameter"), id);
        }
        else if (pattern == "parabolic")
        {
            ant = std::make_unique<antenna::Parabolic>(name, get_child_real_type(antenna, "diameter"), id);
        }
        else if (pattern == "xml")
        {
            ant = ctx.loaders.loadXmlAntenna(name, XmlElement::getSafeAttribute(antenna, "filename"), id);
        }
        else if (pattern == "file")
        {
            ant = ctx.loaders.loadH5Antenna(name, XmlElement::getSafeAttribute(antenna, "filename"), id);
        }
        else
        {
            LOG(logging::Level::FATAL, "Unsupported antenna pattern: {}", pattern);
            throw XmlException("Unsupported antenna pattern: " + pattern);
        }
 
        if (!antenna.childElement("efficiency", 0).isValid())
        {
            LOG(logging::Level::DEBUG, "Antenna '{}' does not specify efficiency, assuming unity.", name);
        }
        else
        {
            try
            {
                ant->setEfficiencyFactor(get_child_real_type(antenna, "efficiency"));
            }
            catch (const XmlException&)
            {
                LOG(logging::Level::WARNING, "Antenna '{}' has an empty efficiency, assuming unity.", name);
            }
        }
 
        ctx.world->add(std::move(ant));
    }

References Antenna, assign_id_from_attribute(), logging::DEBUG, logging::FATAL, get_child_real_type(), XmlElement::getSafeAttribute(), LOG, max, and logging::WARNING.

Referenced by processParsedDocument().

Here is the call graph for this function:

Here is the caller graph for this function:

parseCoordinateSystemParameter()

void serial::xml_parser_utils::parseCoordinateSystemParameter	(	const XmlElement &	parameters,
		params::Parameters &	params_out,
		const bool	origin_set
	)

Definition at line 569 of file xml_parser_utils.cpp.

    {
        if (const XmlElement cs_element = parameters.childElement("coordinatesystem", 0); cs_element.isValid())
        {
            try
            {
                const std::string frame_str = XmlElement::getSafeAttribute(cs_element, "frame");
                if (frame_str == "UTM")
                {
                    parseUtmCoordinateSystem(cs_element, params_out);
                }
                else if (frame_str == "ECEF")
                {
                    params_out.coordinate_frame = params::CoordinateFrame::ECEF;
                    LOG(logging::Level::INFO, "KML coordinate system set to ECEF.");
                }
                else if (frame_str == "ENU")
                {
                    params_out.coordinate_frame = params::CoordinateFrame::ENU;
                    if (!origin_set)
                    {
                        LOG(logging::Level::WARNING,
                            "ENU KML frame specified but no <origin> tag found. Using default KML origin at UCT.");
                    }
                    LOG(logging::Level::INFO, "KML coordinate system set to ENU local tangent plane.");
                }
                else
                {
                    throw XmlException("Unsupported KML coordinate frame: " + frame_str);
                }
            }
            catch (const std::exception& e)
            {
                LOG(logging::Level::WARNING,
                    "Could not parse KML <coordinatesystem> from XML: {}. Defaulting KML export to ENU.", e.what());
                params_out.coordinate_frame = params::CoordinateFrame::ENU;
                params_out.utm_zone = 0;
                params_out.utm_north_hemisphere = true;
            }
        }
    }

References XmlElement::childElement(), params::ECEF, params::ENU, XmlElement::getSafeAttribute(), logging::INFO, LOG, max, parseUtmCoordinateSystem(), and logging::WARNING.

Referenced by parseParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

parseFixedRotation()

void serial::xml_parser_utils::parseFixedRotation	(	const XmlElement &	rotation,
		radar::Platform *	platform,
		params::RotationAngleUnit	unit
	)

Parses a <fixedrotation> block and attaches it to a Platform.

Parameters

rotation	The <fixedrotation> XML element.
platform	The platform to modify.

Definition at line 985 of file xml_parser_utils.cpp.

    {
        math::RotationPath* path = platform->getRotationPath();
        try
        {
            const RealType start_az_deg = get_child_real_type(rotation, "startazimuth");
            const RealType start_el_deg = get_child_real_type(rotation, "startelevation");
            const RealType rate_az_deg_s = get_child_real_type(rotation, "azimuthrate");
            const RealType rate_el_deg_s = get_child_real_type(rotation, "elevationrate");
            const std::string owner = std::format("platform '{}' fixedrotation", platform->getName());
 
            rotation_warning_utils::maybe_warn_about_rotation_value(
                start_az_deg, unit, rotation_warning_utils::ValueKind::Angle, "XML", owner, "startazimuth");
            rotation_warning_utils::maybe_warn_about_rotation_value(
                start_el_deg, unit, rotation_warning_utils::ValueKind::Angle, "XML", owner, "startelevation");
            rotation_warning_utils::maybe_warn_about_rotation_value(
                rate_az_deg_s, unit, rotation_warning_utils::ValueKind::Rate, "XML", owner, "azimuthrate");
            rotation_warning_utils::maybe_warn_about_rotation_value(
                rate_el_deg_s, unit, rotation_warning_utils::ValueKind::Rate, "XML", owner, "elevationrate");
            const math::RotationCoord start =
                rotation_angle_utils::external_rotation_to_internal(start_az_deg, start_el_deg, 0.0, unit);
            const math::RotationCoord rate =
                rotation_angle_utils::external_rotation_rate_to_internal(rate_az_deg_s, rate_el_deg_s, 0.0, unit);
 
            path->setConstantRate(start, rate);
            LOG(logging::Level::DEBUG, "Added fixed rotation to platform {}", platform->getName());
        }
        catch (XmlException& e)
        {
            LOG(logging::Level::FATAL, "Failed to set fixed rotation for platform {}. {}", platform->getName(),
                e.what());
            throw XmlException("Failed to set fixed rotation for platform " + platform->getName());
        }
    }

References serial::rotation_warning_utils::Angle, logging::DEBUG, serial::rotation_angle_utils::external_rotation_rate_to_internal(), serial::rotation_angle_utils::external_rotation_to_internal(), logging::FATAL, get_child_real_type(), LOG, max, serial::rotation_warning_utils::maybe_warn_about_rotation_value(), serial::rotation_warning_utils::Rate, and math::RotationPath::setConstantRate().

Referenced by parsePlatform().

Here is the call graph for this function:

Here is the caller graph for this function:

parseMonostatic()

void serial::xml_parser_utils::parseMonostatic	(	const XmlElement &	monostatic,
		radar::Platform *	platform,
		ParserContext &	ctx,
		const ReferenceLookup &	refs
	)

Parses a <monostatic> block, creating a linked transmitter and receiver pair.

Parameters

monostatic	The <monostatic> XML element.
platform	The platform this radar belongs to.
ctx	The current parser context.
refs	Lookup tables for resolving references.

Definition at line 1187 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(monostatic, "name");
        const radar::OperationMode monostatic_mode = parse_mode_elements(monostatic, "Monostatic '" + name + "'");
        radar::Transmitter* trans = parseTransmitterWithMode(monostatic, platform, ctx, refs, monostatic_mode);
        radar::Receiver* recv = parseReceiverWithMode(monostatic, platform, ctx, refs, monostatic_mode);
        if (trans->getMode() != monostatic_mode || recv->getMode() != monostatic_mode)
        {
            throw XmlException("Monostatic '" + name + "' parsed inconsistent transmitter/receiver modes.");
        }
        if (trans->getSignal() != nullptr)
        {
            validate_waveform_mode_match(*trans->getSignal(), trans->getMode(),
                                         "Monostatic '" + trans->getName() + "'");
        }
        trans->setAttached(recv);
        recv->setAttached(trans);
    }

References XmlElement::getSafeAttribute(), max, parseReceiverWithMode(), and parseTransmitterWithMode().

Referenced by parsePlatformElements().

Here is the call graph for this function:

Here is the caller graph for this function:

parseMotionPath()

void serial::xml_parser_utils::parseMotionPath	(	const XmlElement &	motionPath,
		radar::Platform *	platform
	)

Parses a <motionpath> block and attaches it to a Platform.

Parameters

motionPath	The <motionpath> XML element.
platform	The platform to modify.

Definition at line 857 of file xml_parser_utils.cpp.

    {
        math::Path* path = platform->getMotionPath();
        if (const auto interp_value = XmlElement::getOptionalAttribute(motionPath, "interpolation"))
        {
            if (*interp_value == "linear")
            {
                path->setInterp(math::Path::InterpType::INTERP_LINEAR);
            }
            else if (*interp_value == "cubic")
            {
                path->setInterp(math::Path::InterpType::INTERP_CUBIC);
            }
            else if (*interp_value == "static")
            {
                path->setInterp(math::Path::InterpType::INTERP_STATIC);
            }
            else
            {
                LOG(logging::Level::ERROR, "Unsupported interpolation type: {} for platform {}. Defaulting to static",
                    *interp_value, platform->getName());
                path->setInterp(math::Path::InterpType::INTERP_STATIC);
            }
        }
        else
        {
            LOG(logging::Level::DEBUG,
                "MotionPath interpolation type for platform {} not specified. Defaulting to static.",
                platform->getName());
            path->setInterp(math::Path::InterpType::INTERP_STATIC);
        }
 
        unsigned waypoint_index = 0;
        while (true)
        {
            XmlElement const waypoint = motionPath.childElement("positionwaypoint", waypoint_index);
            if (!waypoint.isValid())
            {
                break;
            }
 
            try
            {
                math::Coord coord;
                coord.t = get_child_real_type(waypoint, "time");
                coord.pos = math::Vec3(get_child_real_type(waypoint, "x"), get_child_real_type(waypoint, "y"),
                                       get_child_real_type(waypoint, "altitude"));
                path->addCoord(coord);
                LOG(logging::Level::TRACE, "Added waypoint {} to motion path for platform {}.", waypoint_index,
                    platform->getName());
            }
            catch (const XmlException& e)
            {
                LOG(logging::Level::ERROR, "Failed to add waypoint to motion path. Discarding waypoint. {}", e.what());
            }
 
            waypoint_index++;
        }
        path->finalize();
    }

References math::Path::addCoord(), logging::DEBUG, logging::ERROR, math::Path::finalize(), get_child_real_type(), XmlElement::getOptionalAttribute(), math::Path::INTERP_CUBIC, math::Path::INTERP_LINEAR, math::Path::INTERP_STATIC, LOG, max, math::Path::setInterp(), and logging::TRACE.

Referenced by parsePlatform().

Here is the call graph for this function:

Here is the caller graph for this function:

parseOptionalNumericParameters()

void serial::xml_parser_utils::parseOptionalNumericParameters	(	const XmlElement &	parameters,
		params::Parameters &	params_out
	)

Definition at line 449 of file xml_parser_utils.cpp.

    {
        setOptionalRealParameter(parameters, "c", params::Parameters::DEFAULT_C,
                                 [&](const RealType value)
                                 {
                                     params_out.c = value;
                                     LOG(logging::Level::INFO, "Propagation speed (c) set to: {:.5f}", value);
                                 });
 
        setOptionalRealParameter(parameters, "simSamplingRate", 1000.0,
                                 [&](const RealType value)
                                 {
                                     params_out.sim_sampling_rate = value;
                                     LOG(logging::Level::DEBUG, "Simulation sampling rate set to: {:.5f} Hz", value);
                                 });
 
        if (parameters.childElement("randomseed", 0).isValid())
        {
            const auto seed = parseUnsignedParameter("randomseed", get_child_real_type(parameters, "randomseed"));
            params_out.random_seed = seed;
            LOG(logging::Level::DEBUG, "Random seed set to: {}", seed);
        }
 
        setOptionalUnsignedParameter(parameters, "adc_bits", 0,
                                     [&](const unsigned value)
                                     {
                                         params_out.adc_bits = value;
                                         LOG(logging::Level::DEBUG, "ADC quantization bits set to: {}", value);
                                     });
 
        setOptionalUnsignedParameter(parameters, "oversample", 1,
                                     [&](const unsigned value)
                                     {
                                         params::validateOversampleRatio(value);
                                         params_out.oversample_ratio = value;
                                         LOG(logging::Level::DEBUG, "Oversampling enabled with ratio: {}", value);
                                     });
    }

References XmlElement::childElement(), logging::DEBUG, params::Parameters::DEFAULT_C, get_child_real_type(), logging::INFO, XmlElement::isValid(), LOG, max, parseUnsignedParameter(), setOptionalRealParameter(), setOptionalUnsignedParameter(), and params::validateOversampleRatio().

Referenced by parseParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

parseOriginParameter()

bool serial::xml_parser_utils::parseOriginParameter	(	const XmlElement &	parameters,
		params::Parameters &	params_out
	)

Definition at line 510 of file xml_parser_utils.cpp.

    {
        bool origin_set = false;
        if (const XmlElement origin_element = parameters.childElement("origin", 0); origin_element.isValid())
        {
            try
            {
                params_out.origin_latitude = std::stod(XmlElement::getSafeAttribute(origin_element, "latitude"));
                params_out.origin_longitude = std::stod(XmlElement::getSafeAttribute(origin_element, "longitude"));
                if (const auto altitude = XmlElement::getOptionalAttribute(origin_element, "altitude"))
                {
                    params_out.origin_altitude = std::stod(*altitude);
                }
                else
                {
                    params_out.origin_altitude = 0.0;
                    LOG(logging::Level::DEBUG, "KML origin altitude not specified. Defaulting to 0.");
                }
                origin_set = true;
                LOG(logging::Level::INFO, "KML origin set to lat: {}, lon: {}, alt: {}", params_out.origin_latitude,
                    params_out.origin_longitude, params_out.origin_altitude);
            }
            catch (const std::exception& e)
            {
                LOG(logging::Level::WARNING, "Could not parse KML origin from XML, using defaults. Error: {}",
                    e.what());
            }
        }
        return origin_set;
    }

References XmlElement::childElement(), logging::DEBUG, XmlElement::getOptionalAttribute(), XmlElement::getSafeAttribute(), logging::INFO, LOG, max, and logging::WARNING.

Referenced by parseParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

parseParameters()

void serial::xml_parser_utils::parseParameters	(	const XmlElement &	parameters,
		params::Parameters &	params_out
	)

Parses the <parameters> block into the isolated context parameters.

Parameters

parameters	The <parameters> XML element.
params_out	The Parameters struct to mutate with parsed values.

Definition at line 612 of file xml_parser_utils.cpp.

    {
        params_out.start = get_child_real_type(parameters, "starttime");
        params_out.end = get_child_real_type(parameters, "endtime");
        LOG(logging::Level::INFO, "Simulation time set from {:.5f} to {:.5f} seconds", params_out.start,
            params_out.end);
 
        params_out.rate = get_child_real_type(parameters, "rate");
        if (params_out.rate <= 0)
        {
            throw std::runtime_error("Sampling rate must be > 0");
        }
        LOG(logging::Level::DEBUG, "Sample rate set to: {:.5f}", params_out.rate);
 
        parseOptionalNumericParameters(parameters, params_out);
        parseRotationAngleUnit(parameters, params_out);
        const bool origin_set = parseOriginParameter(parameters, params_out);
        parseCoordinateSystemParameter(parameters, params_out, origin_set);
    }

References logging::DEBUG, get_child_real_type(), logging::INFO, LOG, max, parseCoordinateSystemParameter(), parseOptionalNumericParameters(), parseOriginParameter(), and parseRotationAngleUnit().

Referenced by processParsedDocument().

Here is the call graph for this function:

Here is the caller graph for this function:

parsePlatform()

void serial::xml_parser_utils::parsePlatform	(	const XmlElement &	platform,
		ParserContext &	ctx,
		const std::function< void(const XmlElement &, std::string_view)> &	register_name,
		const ReferenceLookup &	refs
	)

Parses a complete <platform> block, including its motion paths and sub-elements.

Parameters

platform	The <platform> XML element.
ctx	The current parser context.
register_name	Callback used to ensure unique naming.
refs	Lookup tables for resolving references.

Definition at line 1295 of file xml_parser_utils.cpp.

    {
        std::string const name = XmlElement::getSafeAttribute(platform, "name");
        const SimId id = assign_id_from_attribute("platform '" + name + "'", ObjectType::Platform);
        auto plat = std::make_unique<radar::Platform>(name, id);
 
        parsePlatformElements(platform, ctx, plat.get(), register_name, refs);
 
        if (const XmlElement motion_path = platform.childElement("motionpath", 0); motion_path.isValid())
        {
            parseMotionPath(motion_path, plat.get());
        }
 
        const XmlElement rot_path = platform.childElement("rotationpath", 0);
        if (const XmlElement fixed_rot = platform.childElement("fixedrotation", 0);
            rot_path.isValid() && fixed_rot.isValid())
        {
            LOG(logging::Level::ERROR,
                "Both <rotationpath> and <fixedrotation> are declared for platform {}. Only <rotationpath> will be "
                "used.",
                plat->getName());
            parseRotationPath(rot_path, plat.get(), ctx.parameters.rotation_angle_unit);
        }
        else if (rot_path.isValid())
        {
            parseRotationPath(rot_path, plat.get(), ctx.parameters.rotation_angle_unit);
        }
        else if (fixed_rot.isValid())
        {
            parseFixedRotation(fixed_rot, plat.get(), ctx.parameters.rotation_angle_unit);
        }
 
        ctx.world->add(std::move(plat));
    }

References assign_id_from_attribute(), logging::ERROR, XmlElement::getSafeAttribute(), LOG, max, parseFixedRotation(), parseMotionPath(), parsePlatformElements(), parseRotationPath(), and Platform.

Referenced by processParsedDocument().

Here is the call graph for this function:

Here is the caller graph for this function:

parsePlatformElements()

void serial::xml_parser_utils::parsePlatformElements	(	const XmlElement &	platform,
		ParserContext &	ctx,
		radar::Platform *	plat,
		const std::function< void(const XmlElement &, std::string_view)> &	register_name,
		const ReferenceLookup &	refs
	)

Iterates and parses all children elements (radars, targets) of a platform.

Parameters

platform	The <platform> XML element.
ctx	The current parser context.
plat	The Platform object to attach parsed elements to.
register_name	Callback used to ensure unique naming globally across parsed objects.
refs	Lookup tables for resolving references.

Definition at line 1259 of file xml_parser_utils.cpp.

    {
        auto parseChildrenWithRefs = [&](const std::string& elementName, auto parseFunc)
        {
            unsigned index = 0;
            while (true)
            {
                const XmlElement element = platform.childElement(elementName, index++);
                if (!element.isValid())
                    break;
                register_name(element, elementName);
                parseFunc(element, plat, ctx, refs);
            }
        };
 
        auto parseChildrenWithoutRefs = [&](const std::string& elementName, auto parseFunc)
        {
            unsigned index = 0;
            while (true)
            {
                const XmlElement element = platform.childElement(elementName, index++);
                if (!element.isValid())
                    break;
                register_name(element, elementName);
                parseFunc(element, plat, ctx);
            }
        };
 
        parseChildrenWithRefs("monostatic", parseMonostatic);
        parseChildrenWithRefs("transmitter", parseTransmitter);
        parseChildrenWithRefs("receiver", parseReceiver);
        parseChildrenWithoutRefs("target", parseTarget);
    }

References max, parseMonostatic(), parseReceiver(), parseTarget(), and parseTransmitter().

Referenced by parsePlatform().

Here is the call graph for this function:

Here is the caller graph for this function:

parseReceiver()

radar::Receiver * serial::xml_parser_utils::parseReceiver	(	const XmlElement &	receiver,
		radar::Platform *	platform,
		ParserContext &	ctx,
		const ReferenceLookup &	refs
	)

Parses a <receiver> block, resolves its dependencies, and adds it to the World.

Parameters

receiver	The <receiver> XML element.
platform	The platform this receiver belongs to.
ctx	The current parser context.
refs	Lookup tables for resolving antenna and timing references.

Returns

A pointer to the newly created Receiver object.

Definition at line 1179 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(receiver, "name");
        const radar::OperationMode mode = parse_mode_elements(receiver, "Receiver '" + name + "'");
        return parseReceiverWithMode(receiver, platform, ctx, refs, mode);
    }

References XmlElement::getSafeAttribute(), max, parseReceiverWithMode(), and receiver.

Referenced by parsePlatformElements().

Here is the call graph for this function:

Here is the caller graph for this function:

parseReceiverWithMode()

static radar::Receiver * serial::xml_parser_utils::parseReceiverWithMode ( const XmlElement &  receiver, radar::Platform *  platform, ParserContext &  ctx, const ReferenceLookup &  refs, const radar::OperationMode  mode  )

static

Parses a receiver after its operation mode has already been determined.

Definition at line 1092 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(receiver, "name");
        const SimId id = assign_id_from_attribute("receiver '" + name + "'", ObjectType::Receiver);
        const XmlElement pulsed_mode_element = receiver.childElement("pulsed_mode", 0);
        const bool is_pulsed = mode == radar::OperationMode::PULSED_MODE;
 
        auto receiver_obj = std::make_unique<radar::Receiver>(platform, name, next_seed(*ctx.master_seeder), mode, id);
 
        const SimId ant_id = resolve_reference_id(receiver, "antenna", "receiver '" + name + "'", *refs.antennas);
        const antenna::Antenna* antenna = ctx.world->findAntenna(ant_id);
        if (antenna == nullptr)
        {
            throw XmlException("Antenna ID '" + std::to_string(ant_id) + "' not found for receiver '" + name + "'");
        }
        receiver_obj->setAntenna(antenna);
 
        if (!receiver.childElement("noise_temp", 0).isValid())
        {
            LOG(logging::Level::DEBUG, "Receiver '{}' does not specify noise temperature",
                receiver_obj->getName().c_str());
        }
        else
        {
            try
            {
                receiver_obj->setNoiseTemperature(get_child_real_type(receiver, "noise_temp"));
            }
            catch (const XmlException&)
            {
                LOG(logging::Level::WARNING, "Receiver '{}' has an empty noise temperature; using default.",
                    receiver_obj->getName().c_str());
            }
        }
 
        if (is_pulsed)
        {
            const RealType window_length = get_child_real_type(pulsed_mode_element, "window_length");
            if (window_length <= 0)
            {
                throw XmlException("<window_length> must be positive for receiver '" + name + "'");
            }
 
            const RealType prf = get_child_real_type(pulsed_mode_element, "prf");
            if (prf <= 0)
            {
                throw XmlException("<prf> must be positive for receiver '" + name + "'");
            }
 
            const RealType window_skip = get_child_real_type(pulsed_mode_element, "window_skip");
            if (window_skip < 0)
            {
                throw XmlException("<window_skip> must not be negative for receiver '" + name + "'");
            }
            receiver_obj->setWindowProperties(window_length, prf, window_skip);
        }
        const SimId timing_id = resolve_reference_id(receiver, "timing", "receiver '" + name + "'", *refs.timings);
        receiver_obj->setTiming(resolve_timing_instance(timing_id, ctx, "receiver '" + name + "'"));
 
        if (get_attribute_bool(receiver, "nodirect", false))
        {
            receiver_obj->setFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
            LOG(logging::Level::DEBUG, "Ignoring direct signals for receiver '{}'", receiver_obj->getName().c_str());
        }
 
        if (get_attribute_bool(receiver, "nopropagationloss", false))
        {
            receiver_obj->setFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
            LOG(logging::Level::DEBUG, "Ignoring propagation losses for receiver '{}'",
                receiver_obj->getName().c_str());
        }
 
        RealType const pri = is_pulsed ? (1.0 / receiver_obj->getWindowPrf()) : 0.0;
        auto schedule = parseSchedule(receiver, name, is_pulsed, pri);
        if (!schedule.empty())
        {
            receiver_obj->setSchedule(std::move(schedule));
        }
 
        parse_receiver_dechirp_config(receiver, *receiver_obj, "Receiver '" + name + "'");
 
        ctx.world->add(std::move(receiver_obj));
        return ctx.world->getReceivers().back().get();
    }

References assign_id_from_attribute(), logging::DEBUG, radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, get_attribute_bool(), get_child_real_type(), XmlElement::getSafeAttribute(), LOG, max, parseSchedule(), radar::PULSED_MODE, Receiver, receiver, resolve_reference_id(), and logging::WARNING.

Referenced by parseMonostatic(), and parseReceiver().

Here is the call graph for this function:

Here is the caller graph for this function:

parseRotationAngleUnit()

void serial::xml_parser_utils::parseRotationAngleUnit	(	const XmlElement &	parameters,
		params::Parameters &	params_out
	)

Definition at line 488 of file xml_parser_utils.cpp.

    {
        try
        {
            const auto unit_token = parameters.childElement("rotationangleunit", 0).getText();
            if (!unit_token.empty())
            {
                if (const auto unit = params::rotationAngleUnitFromToken(unit_token))
                {
                    params_out.rotation_angle_unit = *unit;
                }
                else
                {
                    throw XmlException("Unsupported rotation angle unit '" + unit_token + "'.");
                }
            }
        }
        catch (const XmlException&)
        {
        }
    }

References XmlElement::childElement(), XmlElement::getText(), max, and params::rotationAngleUnitFromToken().

Referenced by parseParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

parseRotationPath()

void serial::xml_parser_utils::parseRotationPath	(	const XmlElement &	rotation,
		radar::Platform *	platform,
		params::RotationAngleUnit	unit
	)

Parses a <rotationpath> block and attaches it to a Platform.

Parameters

rotation	The <rotationpath> XML element.
platform	The platform to modify.

Definition at line 918 of file xml_parser_utils.cpp.

    {
        math::RotationPath* path = platform->getRotationPath();
        try
        {
            if (const std::string interp = XmlElement::getSafeAttribute(rotation, "interpolation"); interp == "linear")
            {
                path->setInterp(math::RotationPath::InterpType::INTERP_LINEAR);
            }
            else if (interp == "cubic")
            {
                path->setInterp(math::RotationPath::InterpType::INTERP_CUBIC);
            }
            else if (interp == "static")
            {
                path->setInterp(math::RotationPath::InterpType::INTERP_STATIC);
            }
            else
            {
                throw XmlException("Unsupported interpolation type: " + interp);
            }
        }
        catch (XmlException&)
        {
            LOG(logging::Level::ERROR,
                "Failed to set RotationPath interpolation type for platform {}. Defaulting to static",
                platform->getName());
            path->setInterp(math::RotationPath::InterpType::INTERP_STATIC);
        }
 
        unsigned waypoint_index = 0;
        while (true)
        {
            XmlElement const waypoint = rotation.childElement("rotationwaypoint", waypoint_index);
            if (!waypoint.isValid())
            {
                break;
            }
 
            try
            {
                LOG(logging::Level::TRACE, "Adding waypoint {} to rotation path for platform {}.", waypoint_index,
                    platform->getName());
 
                const RealType az_deg = get_child_real_type(waypoint, "azimuth");
                const RealType el_deg = get_child_real_type(waypoint, "elevation");
                const RealType time = get_child_real_type(waypoint, "time");
                const std::string owner =
                    std::format("platform '{}' rotation waypoint {}", platform->getName(), waypoint_index);
 
                rotation_warning_utils::maybe_warn_about_rotation_value(
                    az_deg, unit, rotation_warning_utils::ValueKind::Angle, "XML", owner, "azimuth");
                rotation_warning_utils::maybe_warn_about_rotation_value(
                    el_deg, unit, rotation_warning_utils::ValueKind::Angle, "XML", owner, "elevation");
 
                path->addCoord(rotation_angle_utils::external_rotation_to_internal(az_deg, el_deg, time, unit));
            }
            catch (const XmlException& e)
            {
                LOG(logging::Level::ERROR, "Failed to add waypoint to rotation path. Discarding waypoint. {}",
                    e.what());
            }
            waypoint_index++;
        }
        path->finalize();
    }

References math::RotationPath::addCoord(), serial::rotation_warning_utils::Angle, logging::ERROR, serial::rotation_angle_utils::external_rotation_to_internal(), math::RotationPath::finalize(), get_child_real_type(), XmlElement::getSafeAttribute(), math::RotationPath::INTERP_CUBIC, math::RotationPath::INTERP_LINEAR, math::RotationPath::INTERP_STATIC, LOG, max, serial::rotation_warning_utils::maybe_warn_about_rotation_value(), math::RotationPath::setInterp(), and logging::TRACE.

Referenced by parsePlatform().

Here is the call graph for this function:

Here is the caller graph for this function:

parseSchedule()

std::vector< radar::SchedulePeriod > serial::xml_parser_utils::parseSchedule	(	const XmlElement &	parent,
		const std::string &	parentName,
		bool	isPulsed,
		RealType	pri = 0.0
	)

Parses a schedule (active periods) for a transmitter or receiver.

Parameters

parent	The parent XML element that might contain a <schedule> block.
parentName	Name of the parent for error logging.
isPulsed	True if the owning object operates in pulsed mode (used for PRI validation).
pri	The pulse repetition interval, if applicable.

Returns

A vector of parsed and validated SchedulePeriod objects.

Definition at line 372 of file xml_parser_utils.cpp.

    {
        std::vector<radar::SchedulePeriod> raw_periods;
        if (const XmlElement schedule_element = parent.childElement("schedule", 0); schedule_element.isValid())
        {
            unsigned p_idx = 0;
            while (true)
            {
                XmlElement const period_element = schedule_element.childElement("period", p_idx++);
                if (!period_element.isValid())
                {
                    break;
                }
                try
                {
                    const RealType start = std::stod(XmlElement::getSafeAttribute(period_element, "start"));
                    const RealType end = std::stod(XmlElement::getSafeAttribute(period_element, "end"));
                    raw_periods.push_back({start, end});
                }
                catch (const std::exception& e)
                {
                    LOG(logging::Level::WARNING, "Failed to parse schedule period for '{}': {}", parentName, e.what());
                }
            }
        }
        return radar::processRawSchedule(raw_periods, parentName, isPulsed, pri);
    }

References XmlElement::getSafeAttribute(), LOG, max, radar::processRawSchedule(), and logging::WARNING.

Referenced by parseReceiverWithMode(), and parseTransmitterWithMode().

Here is the call graph for this function:

Here is the caller graph for this function:

parseTarget()

void serial::xml_parser_utils::parseTarget	(	const XmlElement &	target,
		radar::Platform *	platform,
		ParserContext &	ctx
	)

Parses a <target> block and adds it to the World.

Parameters

target	The <target> XML element.
platform	The platform this target belongs to.
ctx	The current parser context.

Definition at line 1207 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(target, "name");
        const SimId id = assign_id_from_attribute("target '" + name + "'", ObjectType::Target);
 
        const XmlElement rcs_element = target.childElement("rcs", 0);
        if (!rcs_element.isValid())
        {
            throw XmlException("<rcs> element is required in <target>!");
        }
 
        const std::string rcs_type = XmlElement::getSafeAttribute(rcs_element, "type");
        std::unique_ptr<radar::Target> target_obj;
        const unsigned seed = next_seed(*ctx.master_seeder);
 
        if (rcs_type == "isotropic")
        {
            target_obj = radar::createIsoTarget(platform, name, get_child_real_type(rcs_element, "value"), seed, id);
        }
        else if (rcs_type == "file")
        {
            // Defer to dependency-injected file loader
            target_obj = ctx.loaders.loadFileTarget(platform, name,
                                                    XmlElement::getSafeAttribute(rcs_element, "filename"), seed, id);
        }
        else
        {
            throw XmlException("Unsupported RCS type: " + rcs_type);
        }
 
        if (const XmlElement model = target.childElement("model", 0); model.isValid())
        {
            if (const std::string model_type = XmlElement::getSafeAttribute(model, "type"); model_type == "constant")
            {
                target_obj->setFluctuationModel(std::make_unique<radar::RcsConst>());
            }
            else if (model_type == "chisquare" || model_type == "gamma")
            {
                target_obj->setFluctuationModel(
                    std::make_unique<radar::RcsChiSquare>(target_obj->getRngEngine(), get_child_real_type(model, "k")));
            }
            else
            {
                throw XmlException("Unsupported model type: " + model_type);
            }
        }
 
        LOG(logging::Level::DEBUG, "Added target {} with RCS type {} to platform {}", name, rcs_type,
            platform->getName());
        ctx.world->add(std::move(target_obj));
    }

References assign_id_from_attribute(), radar::createIsoTarget(), logging::DEBUG, get_child_real_type(), XmlElement::getSafeAttribute(), LOG, max, and Target.

Referenced by parsePlatformElements().

Here is the call graph for this function:

Here is the caller graph for this function:

parseTiming()

void serial::xml_parser_utils::parseTiming	(	const XmlElement &	timing,
		ParserContext &	ctx
	)

Parses a <timing> block and adds the prototype timing to the World.

Parameters

timing	The <timing> XML element.
ctx	The current parser context.

Definition at line 735 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(timing, "name");
        const SimId id = assign_id_from_attribute("timing '" + name + "'", ObjectType::Timing);
        const RealType freq = get_child_real_type(timing, "frequency");
        auto timing_obj = std::make_unique<timing::PrototypeTiming>(name, id);
 
        timing_obj->setFrequency(freq);
 
        unsigned noise_index = 0;
        while (true)
        {
            XmlElement const noise_element = timing.childElement("noise_entry", noise_index++);
            if (!noise_element.isValid())
            {
                break;
            }
 
            timing_obj->setAlpha(get_child_real_type(noise_element, "alpha"),
                                 get_child_real_type(noise_element, "weight"));
        }
 
        const auto set_optional_timing_parameter =
            [&](const std::string& element_name, const std::string& description, auto setter)
        {
            if (!timing.childElement(element_name, 0).isValid())
            {
                LOG(logging::Level::DEBUG, "Clock section '{}' does not specify {}.", name, description);
                return;
            }
            try
            {
                setter(get_child_real_type(timing, element_name));
            }
            catch (const XmlException&)
            {
                LOG(logging::Level::WARNING, "Clock section '{}' has an empty {}. Using default.", name, description);
            }
        };
 
        set_optional_timing_parameter("freq_offset", "frequency offset",
                                      [&](const RealType value) { timing_obj->setFreqOffset(value); });
        set_optional_timing_parameter("random_freq_offset_stdev", "random frequency offset",
                                      [&](const RealType value) { timing_obj->setRandomFreqOffsetStdev(value); });
        set_optional_timing_parameter("phase_offset", "phase offset",
                                      [&](const RealType value) { timing_obj->setPhaseOffset(value); });
        set_optional_timing_parameter("random_phase_offset_stdev", "random phase offset",
                                      [&](const RealType value) { timing_obj->setRandomPhaseOffsetStdev(value); });
 
        if (get_attribute_bool(timing, "synconpulse", false))
        {
            timing_obj->setSyncOnPulse();
        }
 
        ctx.world->add(std::move(timing_obj));
    }

References assign_id_from_attribute(), logging::DEBUG, get_attribute_bool(), get_child_real_type(), XmlElement::getSafeAttribute(), LOG, max, Timing, and logging::WARNING.

Referenced by processParsedDocument().

Here is the call graph for this function:

Here is the caller graph for this function:

parseTransmitter()

radar::Transmitter * serial::xml_parser_utils::parseTransmitter	(	const XmlElement &	transmitter,
		radar::Platform *	platform,
		ParserContext &	ctx,
		const ReferenceLookup &	refs
	)

Parses a <transmitter> block, resolves its dependencies, and adds it to the World.

Parameters

transmitter	The <transmitter> XML element.
platform	The platform this transmitter belongs to.
ctx	The current parser context.
refs	Lookup tables for resolving waveform, antenna, and timing references.

Returns

A pointer to the newly created Transmitter object.

Definition at line 1078 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(transmitter, "name");
        const radar::OperationMode mode = parse_mode_elements(transmitter, "Transmitter '" + name + "'");
        if (const XmlElement fmcw_mode = transmitter.childElement("fmcw_mode", 0);
            fmcw_mode.isValid() && has_dechirp_fields(fmcw_mode))
        {
            throw XmlException("Transmitter '" + name + "' fmcw_mode must not contain dechirp configuration.");
        }
        return parseTransmitterWithMode(transmitter, platform, ctx, refs, mode);
    }

References XmlElement::getSafeAttribute(), max, parseTransmitterWithMode(), and transmitter.

Referenced by parsePlatformElements().

Here is the call graph for this function:

Here is the caller graph for this function:

parseTransmitterWithMode()

static radar::Transmitter * serial::xml_parser_utils::parseTransmitterWithMode ( const XmlElement &  transmitter, radar::Platform *  platform, ParserContext &  ctx, const ReferenceLookup &  refs, const radar::OperationMode  mode  )

static

Parses a transmitter after its operation mode has already been determined.

Definition at line 1021 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(transmitter, "name");
        const SimId id = assign_id_from_attribute("transmitter '" + name + "'", ObjectType::Transmitter);
        const XmlElement pulsed_mode_element = transmitter.childElement("pulsed_mode", 0);
        const bool is_pulsed = mode == radar::OperationMode::PULSED_MODE;
 
        auto transmitter_obj = std::make_unique<radar::Transmitter>(platform, name, mode, id);
 
        const SimId waveform_id =
            resolve_reference_id(transmitter, "waveform", "transmitter '" + name + "'", *refs.waveforms);
        fers_signal::RadarSignal* wave = ctx.world->findWaveform(waveform_id);
        if (wave == nullptr)
        {
            throw XmlException("Waveform ID '" + std::to_string(waveform_id) + "' not found for transmitter '" + name +
                               "'");
        }
        validate_fmcw_waveform(*wave, "Waveform '" + wave->getName() + "'");
        validate_waveform_mode_match(*wave, mode, "Transmitter '" + name + "'");
        transmitter_obj->setWave(wave);
 
        if (is_pulsed)
        {
            transmitter_obj->setPrf(get_child_real_type(pulsed_mode_element, "prf"));
        }
 
        const SimId antenna_id =
            resolve_reference_id(transmitter, "antenna", "transmitter '" + name + "'", *refs.antennas);
        const antenna::Antenna* ant = ctx.world->findAntenna(antenna_id);
        if (ant == nullptr)
        {
            throw XmlException("Antenna ID '" + std::to_string(antenna_id) + "' not found for transmitter '" + name +
                               "'");
        }
        transmitter_obj->setAntenna(ant);
 
        const SimId timing_id =
            resolve_reference_id(transmitter, "timing", "transmitter '" + name + "'", *refs.timings);
        transmitter_obj->setTiming(resolve_timing_instance(timing_id, ctx, "transmitter '" + name + "'"));
 
        RealType const pri = is_pulsed ? (1.0 / transmitter_obj->getPrf()) : 0.0;
        auto schedule = parseSchedule(transmitter, name, is_pulsed, pri);
        if (wave->isFmcwFamily())
        {
            validate_fmcw_schedule(schedule, *wave, "Transmitter '" + name + "'");
        }
        if (!schedule.empty())
        {
            transmitter_obj->setSchedule(std::move(schedule));
        }
 
        ctx.world->add(std::move(transmitter_obj));
        return ctx.world->getTransmitters().back().get();
    }

References assign_id_from_attribute(), get_child_real_type(), XmlElement::getSafeAttribute(), max, parseSchedule(), radar::PULSED_MODE, resolve_reference_id(), Transmitter, and transmitter.

Referenced by parseMonostatic(), and parseTransmitter().

Here is the call graph for this function:

Here is the caller graph for this function:

parseUnsignedParameter()

unsigned serial::xml_parser_utils::parseUnsignedParameter	(	const std::string_view	param_name,
		const RealType	raw_value
	)

Definition at line 401 of file xml_parser_utils.cpp.

    {
        if (!std::isfinite(raw_value))
        {
            throw XmlException(std::format("Parameter '{}' must be finite.", param_name));
        }
        if (raw_value < 0.0)
        {
            throw XmlException(std::format("Parameter '{}' must be non-negative.", param_name));
        }
 
        const RealType floored_value = std::floor(raw_value);
        if (floored_value > static_cast<RealType>(std::numeric_limits<unsigned>::max()))
        {
            throw XmlException(std::format("Parameter '{}' exceeds the supported unsigned range.", param_name));
        }
 
        return static_cast<unsigned>(floored_value);
    }

References max.

Referenced by parseOptionalNumericParameters(), and setOptionalUnsignedParameter().

Here is the caller graph for this function:

parseUtmCoordinateSystem()

void serial::xml_parser_utils::parseUtmCoordinateSystem	(	const XmlElement &	cs_element,
		params::Parameters &	params_out
	)

Definition at line 541 of file xml_parser_utils.cpp.

    {
        params_out.coordinate_frame = params::CoordinateFrame::UTM;
        params_out.utm_zone = std::stoi(XmlElement::getSafeAttribute(cs_element, "zone"));
        const std::string hem_str = XmlElement::getSafeAttribute(cs_element, "hemisphere");
 
        if (params_out.utm_zone < GeographicLib::UTMUPS::MINUTMZONE ||
            params_out.utm_zone > GeographicLib::UTMUPS::MAXUTMZONE)
        {
            throw XmlException("KML UTM zone " + std::to_string(params_out.utm_zone) +
                               " is invalid; must be in [1, 60].");
        }
        if (hem_str == "N" || hem_str == "n")
        {
            params_out.utm_north_hemisphere = true;
        }
        else if (hem_str == "S" || hem_str == "s")
        {
            params_out.utm_north_hemisphere = false;
        }
        else
        {
            throw XmlException("KML UTM hemisphere '" + hem_str + "' is invalid; must be 'N' or 'S'.");
        }
        LOG(logging::Level::INFO, "KML coordinate system set to UTM, zone {}{}", params_out.utm_zone,
            params_out.utm_north_hemisphere ? 'N' : 'S');
    }

References XmlElement::getSafeAttribute(), logging::INFO, LOG, max, and params::UTM.

Referenced by parseCoordinateSystemParameter().

Here is the call graph for this function:

Here is the caller graph for this function:

parseWaveform()

void serial::xml_parser_utils::parseWaveform	(	const XmlElement &	waveform,
		ParserContext &	ctx
	)

Parses a <waveform> block and adds it to the World.

Parameters

waveform	The <waveform> XML element.
ctx	The current parser context.

Definition at line 632 of file xml_parser_utils.cpp.

    {
        const std::string name = XmlElement::getSafeAttribute(waveform, "name");
        const SimId id = assign_id_from_attribute("waveform '" + name + "'", ObjectType::Waveform);
 
        const auto power = get_child_real_type(waveform, "power");
        const auto carrier = get_child_real_type(waveform, "carrier_frequency");
 
        if (const XmlElement pulsed_file = waveform.childElement("pulsed_from_file", 0); pulsed_file.isValid())
        {
            const std::string filename_str = XmlElement::getSafeAttribute(pulsed_file, "filename");
            fs::path pulse_path(filename_str);
 
            if (!fs::exists(pulse_path))
            {
                pulse_path = ctx.base_dir / filename_str;
            }
 
            // Defer to dependency-injected file loader
            auto wave = ctx.loaders.loadWaveform(name, pulse_path, power, carrier, id);
            ctx.world->add(std::move(wave));
        }
        else if (waveform.childElement("cw", 0).isValid())
        {
            auto cw_signal = std::make_unique<fers_signal::CwSignal>();
            auto wave = std::make_unique<fers_signal::RadarSignal>(
                name, power, carrier, ctx.parameters.end - ctx.parameters.start, std::move(cw_signal), id);
            ctx.world->add(std::move(wave));
        }
        else if (const XmlElement fmcw_element = waveform.childElement("fmcw_linear_chirp", 0); fmcw_element.isValid())
        {
            const auto direction =
                fers_signal::parseFmcwChirpDirection(XmlElement::getSafeAttribute(fmcw_element, "direction"));
            const RealType chirp_bandwidth = get_child_real_type(fmcw_element, "chirp_bandwidth");
            const RealType chirp_duration = get_child_real_type(fmcw_element, "chirp_duration");
            const RealType chirp_period = get_child_real_type(fmcw_element, "chirp_period");
 
            RealType start_frequency_offset = 0.0;
            if (const auto start_offset = fmcw_element.childElement("start_frequency_offset", 0);
                start_offset.isValid())
            {
                start_frequency_offset = get_child_real_type(fmcw_element, "start_frequency_offset");
            }
 
            std::optional<std::size_t> chirp_count;
            if (const auto chirp_count_element = fmcw_element.childElement("chirp_count", 0);
                chirp_count_element.isValid())
            {
                const RealType raw_count = get_child_real_type(fmcw_element, "chirp_count");
                if (raw_count <= 0.0 || std::floor(raw_count) != raw_count)
                {
                    throw XmlException("Waveform '" + name + "' has an invalid chirp_count.");
                }
                chirp_count = static_cast<std::size_t>(raw_count);
            }
 
            auto fmcw_signal = std::make_unique<fers_signal::FmcwChirpSignal>(
                chirp_bandwidth, chirp_duration, chirp_period, start_frequency_offset, chirp_count, direction);
            // RadarSignal length is the active chirp duration, not T_rep. The repeat period only spaces chirps.
            auto wave = std::make_unique<fers_signal::RadarSignal>(name, power, carrier, chirp_duration,
                                                                   std::move(fmcw_signal), id);
            validate_fmcw_waveform(*wave, "Waveform '" + name + "'");
            ctx.world->add(std::move(wave));
        }
        else if (const XmlElement fmcw_triangle_element = waveform.childElement("fmcw_triangle", 0);
                 fmcw_triangle_element.isValid())
        {
            const RealType chirp_bandwidth = get_child_real_type(fmcw_triangle_element, "chirp_bandwidth");
            const RealType chirp_duration = get_child_real_type(fmcw_triangle_element, "chirp_duration");
 
            RealType start_frequency_offset = 0.0;
            if (const auto start_offset = fmcw_triangle_element.childElement("start_frequency_offset", 0);
                start_offset.isValid())
            {
                start_frequency_offset = get_child_real_type(fmcw_triangle_element, "start_frequency_offset");
            }
 
            std::optional<std::size_t> triangle_count;
            if (const auto triangle_count_element = fmcw_triangle_element.childElement("triangle_count", 0);
                triangle_count_element.isValid())
            {
                const RealType raw_count = get_child_real_type(fmcw_triangle_element, "triangle_count");
                if (raw_count <= 0.0 || std::floor(raw_count) != raw_count)
                {
                    throw XmlException("Waveform '" + name + "' has an invalid triangle_count.");
                }
                triangle_count = static_cast<std::size_t>(raw_count);
            }
 
            auto fmcw_signal = std::make_unique<fers_signal::FmcwTriangleSignal>(
                chirp_bandwidth, chirp_duration, start_frequency_offset, triangle_count);
            auto wave = std::make_unique<fers_signal::RadarSignal>(
                name, power, carrier, fmcw_signal->getTrianglePeriod(), std::move(fmcw_signal), id);
            validate_fmcw_waveform(*wave, "Waveform '" + name + "'");
            ctx.world->add(std::move(wave));
        }
        else
        {
            LOG(logging::Level::FATAL, "Unsupported waveform type for '{}'", name);
            throw XmlException("Unsupported waveform type for '" + name + "'");
        }
    }

References assign_id_from_attribute(), XmlElement::childElement(), logging::FATAL, get_child_real_type(), XmlElement::getSafeAttribute(), XmlElement::isValid(), LOG, max, fers_signal::parseFmcwChirpDirection(), and Waveform.

Referenced by processParsedDocument().

Here is the call graph for this function:

Here is the caller graph for this function:

processParsedDocument()

void serial::xml_parser_utils::processParsedDocument	(	const XmlDocument &	doc,
		ParserContext &	ctx
	)

Coordinates the full parsing of a validated XML document tree.

This is the root parsing function that iterates over parameters, waveforms, timings, antennas, and platforms. It populates the World in the proper order and triggers initial event scheduling.

Parameters

doc	The parsed XML document tree.
ctx	The parser context containing the World, isolated parameters, and asset loaders.

Definition at line 1402 of file xml_parser_utils.cpp.

    {
        const XmlElement root = doc.getRootElement();
        if (root.name() != "simulation")
        {
            throw XmlException("Root element is not <simulation>!");
        }
 
        std::unordered_map<std::string, std::string> name_registry;
        name_registry.reserve(64); // TODO: reserve 64?
        const auto register_name = [&](const XmlElement& element, const std::string_view kind)
        {
            const std::string name = XmlElement::getSafeAttribute(element, "name");
            const auto [iter, inserted] = name_registry.emplace(name, std::string(kind));
            if (!inserted)
            {
                throw XmlException("Duplicate name '" + name + "' found for " + std::string(kind) +
                                   "; previously used by " + iter->second + ".");
            }
        };
 
        try
        {
            ctx.parameters.simulation_name = XmlElement::getSafeAttribute(root, "name");
            if (!ctx.parameters.simulation_name.empty())
            {
                LOG(logging::Level::INFO, "Simulation name set to: {}", ctx.parameters.simulation_name);
            }
        }
        catch (const XmlException&)
        {
            LOG(logging::Level::WARNING, "No 'name' attribute found in <simulation> tag. KML name will default.");
        }
 
        parseParameters(root.childElement("parameters", 0), ctx.parameters);
 
        params::params = ctx.parameters;
 
        auto parseElements =
            [](const XmlElement& parent, const std::string& elementName, ParserContext& parser_ctx, auto parseFunction)
        {
            unsigned index = 0;
            while (true)
            {
                XmlElement const element = parent.childElement(elementName, index++);
                if (!element.isValid())
                    break;
                parseFunction(element, parser_ctx);
            }
        };
 
        parseElements(root, "waveform", ctx,
                      [&](const XmlElement& p, ParserContext& c)
                      {
                          register_name(p, "waveform");
                          parseWaveform(p, c);
                      });
 
        parseElements(root, "timing", ctx,
                      [&](const XmlElement& p, ParserContext& c)
                      {
                          register_name(p, "timing");
                          parseTiming(p, c);
                      });
 
        parseElements(root, "antenna", ctx,
                      [&](const XmlElement& p, ParserContext& c)
                      {
                          register_name(p, "antenna");
                          parseAntenna(p, c);
                      });
 
        std::unordered_map<std::string, SimId> waveform_refs;
        std::unordered_map<std::string, SimId> antenna_refs;
        std::unordered_map<std::string, SimId> timing_refs;
        waveform_refs.reserve(ctx.world->getWaveforms().size());
        antenna_refs.reserve(ctx.world->getAntennas().size());
        timing_refs.reserve(ctx.world->getTimings().size());
 
        for (const auto& [id, waveform] : ctx.world->getWaveforms())
            waveform_refs.emplace(waveform->getName(), id);
        for (const auto& [id, antenna] : ctx.world->getAntennas())
            antenna_refs.emplace(antenna->getName(), id);
        for (const auto& [id, timing] : ctx.world->getTimings())
            timing_refs.emplace(timing->getName(), id);
 
        const ReferenceLookup refs{&waveform_refs, &antenna_refs, &timing_refs};
 
        parseElements(root, "platform", ctx,
                      [&](const XmlElement& p, ParserContext& c)
                      {
                          register_name(p, "platform");
                          parsePlatform(p, c, register_name, refs);
                      });
 
        ctx.world->resolveReceiverDechirpReferences();
 
        ctx.world->scheduleInitialEvents();
 
        LOG(logging::Level::DEBUG, "Initial Event Queue State:\n{}", ctx.world->dumpEventQueue());
    }

References c, logging::DEBUG, XmlElement::getSafeAttribute(), logging::INFO, LOG, max, params::params, parseAntenna(), parseParameters(), parsePlatform(), parseTiming(), parseWaveform(), and logging::WARNING.

Referenced by serial::parseSimulation(), and serial::parseSimulationFromString().

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_reference_id()

SimId serial::xml_parser_utils::resolve_reference_id	(	const XmlElement &	element,
		const std::string &	attributeName,
		const std::string &	owner,
		const std::unordered_map< std::string, SimId > &	name_map
	)

Resolves an XML string reference into an internal SimId.

Parameters

element	The XML element containing the string reference attribute.
attributeName	The name of the attribute containing the reference string.
owner	A description of the object making the reference (used for error messages).
name_map	The lookup table mapping string names to SimIds.

Returns

The resolved SimId.

Exceptions

XmlException

if the reference cannot be resolved or is missing.

Definition at line 356 of file xml_parser_utils.cpp.

    {
        const std::string value = XmlElement::getSafeAttribute(element, attributeName);
        if (value.empty())
        {
            throw XmlException("Missing " + attributeName + " for " + owner + ".");
        }
        const auto it = name_map.find(value);
        if (it != name_map.end())
        {
            return it->second;
        }
        throw XmlException("Unknown " + attributeName + " '" + value + "' for " + owner + ".");
    }

References XmlElement::getSafeAttribute(), and max.

Referenced by parseReceiverWithMode(), and parseTransmitterWithMode().

Here is the call graph for this function:

Here is the caller graph for this function:

setOptionalRealParameter()

template<typename Setter >

void serial::xml_parser_utils::setOptionalRealParameter	(	const XmlElement &	parameters,
		const std::string &	param_name,
		const RealType	default_value,
		Setter	setter
	)

Definition at line 422 of file xml_parser_utils.cpp.

    {
        if (!parameters.childElement(param_name, 0).isValid())
        {
            LOG(logging::Level::DEBUG, "Parameter '{}' not specified. Using default value {}.", param_name,
                default_value);
            return;
        }
 
        setter(get_child_real_type(parameters, param_name));
    }

References XmlElement::childElement(), logging::DEBUG, get_child_real_type(), XmlElement::isValid(), LOG, and max.

Referenced by parseOptionalNumericParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

setOptionalUnsignedParameter()

template<typename Setter >

void serial::xml_parser_utils::setOptionalUnsignedParameter	(	const XmlElement &	parameters,
		const std::string &	param_name,
		const unsigned	default_value,
		Setter	setter
	)

Definition at line 436 of file xml_parser_utils.cpp.

    {
        if (!parameters.childElement(param_name, 0).isValid())
        {
            LOG(logging::Level::DEBUG, "Parameter '{}' not specified. Using default value {}.", param_name,
                default_value);
            return;
        }
 
        setter(parseUnsignedParameter(param_name, get_child_real_type(parameters, param_name)));
    }

References XmlElement::childElement(), logging::DEBUG, get_child_real_type(), XmlElement::isValid(), LOG, max, and parseUnsignedParameter().

Referenced by parseOptionalNumericParameters().

Here is the call graph for this function:

Here is the caller graph for this function:

validateXml()

void serial::xml_parser_utils::validateXml	(	bool	didCombine,
		const XmlDocument &	mainDoc
	)

Validates an XML document against the embedded DTD and XSD schemas.

Parameters

didCombine	Flag indicating whether the document contains merged includes (used for formatting log messages).
mainDoc	The XML document to validate.

Exceptions

XmlException

if validation fails.

Definition at line 1384 of file xml_parser_utils.cpp.

    {
        LOG(logging::Level::DEBUG, "Validating the{}XML file...", didCombine ? " combined " : " ");
        if (!mainDoc.validateWithDtd(fers_xml_dtd))
        {
            LOG(logging::Level::FATAL, "{} XML file failed DTD validation!", didCombine ? "Combined" : "Main");
            throw XmlException("XML file failed DTD validation!");
        }
        LOG(logging::Level::DEBUG, "{} XML file passed DTD validation.", didCombine ? "Combined" : "Main");
 
        if (!mainDoc.validateWithXsd(fers_xml_xsd))
        {
            LOG(logging::Level::FATAL, "{} XML file failed XSD validation!", didCombine ? "Combined" : "Main");
            throw XmlException("XML file failed XSD validation!");
        }
        LOG(logging::Level::DEBUG, "{} XML file passed XSD validation.", didCombine ? "Combined" : "Main");
    }

References logging::DEBUG, logging::FATAL, LOG, and max.

Referenced by serial::parseSimulation(), and serial::parseSimulationFromString().

Here is the caller graph for this function: