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.
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.
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.
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 969 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(), XmlDocument::loadFile(), 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 76 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, and logging::TRACE.

Referenced by parseAntenna(), parsePlatform(), parseReceiver(), parseTarget(), parseTiming(), parseTransmitter(), 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 939 of file xml_parser_utils.cpp.

    {
        unsigned index = 0;
        while (true)
        {
            XmlElement include_element = doc.getRootElement().childElement("include", index++);
            if (!include_element.isValid())
                break;
 
            std::string include_filename = include_element.getText();
            if (include_filename.empty())
            {
                LOG(logging::Level::ERROR, "<include> element is missing the filename!");
                continue;
            }
 
            fs::path 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 XmlElement::childElement(), collectIncludeElements(), logging::ERROR, XmlDocument::getRootElement(), XmlElement::getText(), XmlElement::isValid(), XmlDocument::loadFile(), and LOG.

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 1122 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, and serial::loadWaveformFromFile().

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 extraction fails.

Definition at line 62 of file xml_parser_utils.cpp.

    {
        try
        {
            return XmlElement::getSafeAttribute(element, attributeName) == "true";
        }
        catch (const XmlException&)
        {
            LOG(logging::Level::WARNING, "Failed to get boolean value for attribute '{}'. Defaulting to {}.",
                attributeName, defaultVal);
            return defaultVal;
        }
    }

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

Referenced by parseReceiver(), 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 52 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 XmlElement::childElement(), and XmlElement::getText().

Referenced by parseAntenna(), parseFixedRotation(), parseMotionPath(), parseParameters(), parseReceiver(), parseRotationPath(), parseTarget(), parseTiming(), parseTransmitter(), and parseWaveform().

Here is the call graph for this function:

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 429 of file xml_parser_utils.cpp.

    {
        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);
        }
 
        try
        {
            ant->setEfficiencyFactor(get_child_real_type(antenna, "efficiency"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::WARNING, "Antenna '{}' does not specify efficiency, assuming unity.", name);
        }
 
        ctx.world->add(std::move(ant));
    }

References core::World::add(), Antenna, assign_id_from_attribute(), logging::DEBUG, logging::FATAL, get_child_real_type(), XmlElement::getSafeAttribute(), serial::xml_parser_utils::ParserContext::loaders, serial::xml_parser_utils::AssetLoaders::loadH5Antenna, serial::xml_parser_utils::AssetLoaders::loadXmlAntenna, LOG, logging::WARNING, and serial::xml_parser_utils::ParserContext::world.

Referenced by processParsedDocument().

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 615 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(), radar::Platform::getName(), radar::Platform::getRotationPath(), LOG, 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 805 of file xml_parser_utils.cpp.

    {
        radar::Transmitter* trans = parseTransmitter(monostatic, platform, ctx, refs);
        radar::Receiver* recv = parseReceiver(monostatic, platform, ctx, refs);
        trans->setAttached(recv);
        recv->setAttached(trans);
    }

References parseReceiver(), parseTransmitter(), and radar::Radar::setAttached().

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 487 of file xml_parser_utils.cpp.

    {
        math::Path* path = platform->getMotionPath();
        try
        {
            if (std::string interp = XmlElement::getSafeAttribute(motionPath, "interpolation"); interp == "linear")
            {
                path->setInterp(math::Path::InterpType::INTERP_LINEAR);
            }
            else if (interp == "cubic")
            {
                path->setInterp(math::Path::InterpType::INTERP_CUBIC);
            }
            else if (interp == "static")
            {
                path->setInterp(math::Path::InterpType::INTERP_STATIC);
            }
            else
            {
                LOG(logging::Level::ERROR, "Unsupported interpolation type: {} for platform {}. Defaulting to static",
                    interp, platform->getName());
                path->setInterp(math::Path::InterpType::INTERP_STATIC);
            }
        }
        catch (XmlException&)
        {
            LOG(logging::Level::ERROR,
                "Failed to set MotionPath interpolation type for platform {}. Defaulting to static",
                platform->getName());
            path->setInterp(math::Path::InterpType::INTERP_STATIC);
        }
 
        unsigned waypoint_index = 0;
        while (true)
        {
            XmlElement 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(), XmlElement::childElement(), logging::ERROR, math::Path::finalize(), get_child_real_type(), radar::Platform::getMotionPath(), radar::Platform::getName(), XmlElement::getSafeAttribute(), math::Path::INTERP_CUBIC, math::Path::INTERP_LINEAR, math::Path::INTERP_STATIC, XmlElement::isValid(), LOG, math::Coord::pos, math::Path::setInterp(), math::Coord::t, and logging::TRACE.

Referenced by parsePlatform().

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 128 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);
 
        const auto parse_unsigned_parameter = [&](const std::string_view param_name, const RealType raw_value)
        {
            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);
        };
 
        auto set_optional_real_parameter = [&](const std::string& param_name, const RealType default_value, auto setter)
        {
            if (!parameters.childElement(param_name, 0).isValid())
            {
                LOG(logging::Level::WARNING, "Failed to set parameter {}. Using default value. {}", param_name,
                    default_value);
                return;
            }
 
            setter(get_child_real_type(parameters, param_name));
        };
 
        auto set_optional_unsigned_parameter =
            [&](const std::string& param_name, const unsigned default_value, auto setter)
        {
            if (!parameters.childElement(param_name, 0).isValid())
            {
                LOG(logging::Level::WARNING, "Failed to set parameter {}. Using default value. {}", param_name,
                    default_value);
                return;
            }
 
            setter(parse_unsigned_parameter(param_name, get_child_real_type(parameters, param_name)));
        };
 
        set_optional_real_parameter("c", params::Parameters::DEFAULT_C,
                                    [&](const RealType value)
                                    {
                                        params_out.c = value;
                                        LOG(logging::Level::INFO, "Propagation speed (c) set to: {:.5f}", value);
                                    });
 
        set_optional_real_parameter("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 = parse_unsigned_parameter("randomseed", get_child_real_type(parameters, "randomseed"));
            params_out.random_seed = seed;
            LOG(logging::Level::DEBUG, "Random seed set to: {}", seed);
        }
 
        set_optional_unsigned_parameter("adc_bits", 0,
                                        [&](const unsigned value)
                                        {
                                            params_out.adc_bits = value;
                                            LOG(logging::Level::DEBUG, "ADC quantization bits set to: {}", value);
                                        });
 
        set_optional_unsigned_parameter("oversample", 1,
                                        [&](const unsigned value)
                                        {
                                            if (value == 0)
                                            {
                                                throw std::runtime_error("Oversample ratio must be >= 1");
                                            }
                                            params_out.oversample_ratio = value;
                                            LOG(logging::Level::DEBUG, "Oversampling enabled with ratio: {}", value);
                                        });
 
        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&)
        {
        }
 
        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"));
                params_out.origin_altitude = std::stod(XmlElement::getSafeAttribute(origin_element, "altitude"));
                origin_set = true;
                LOG(logging::Level::INFO, "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 origin from XML, using defaults. Error: {}", e.what());
            }
        }
 
        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")
                {
                    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("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("UTM hemisphere '" + hem_str + "' is invalid; must be 'N' or 'S'.");
                    }
                    LOG(logging::Level::INFO, "Coordinate system set to UTM, zone {}{}", params_out.utm_zone,
                        params_out.utm_north_hemisphere ? 'N' : 'S');
                }
                else if (frame_str == "ECEF")
                {
                    params_out.coordinate_frame = params::CoordinateFrame::ECEF;
                    LOG(logging::Level::INFO, "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 frame specified but no <origin> tag found. Using default origin at UCT.");
                    }
                    LOG(logging::Level::INFO, "Coordinate system set to ENU local tangent plane.");
                }
                else
                {
                    throw XmlException("Unsupported coordinate frame: " + frame_str);
                }
            }
            catch (const std::exception& e)
            {
                LOG(logging::Level::WARNING, "Could not parse <coordinatesystem> from XML: {}. Defaulting to ENU.",
                    e.what());
                params_out.coordinate_frame = params::CoordinateFrame::ENU;
                params_out.utm_zone = 0;
                params_out.utm_north_hemisphere = true;
            }
        }
    }

References params::Parameters::adc_bits, params::Parameters::c, XmlElement::childElement(), params::Parameters::coordinate_frame, logging::DEBUG, params::Parameters::DEFAULT_C, params::ECEF, params::Parameters::end, params::ENU, get_child_real_type(), XmlElement::getSafeAttribute(), XmlElement::getText(), logging::INFO, XmlElement::isValid(), LOG, params::Parameters::origin_altitude, params::Parameters::origin_latitude, params::Parameters::origin_longitude, params::Parameters::oversample_ratio, params::Parameters::random_seed, params::Parameters::rate, params::Parameters::rotation_angle_unit, params::rotationAngleUnitFromToken(), params::Parameters::sim_sampling_rate, params::Parameters::start, params::UTM, params::Parameters::utm_north_hemisphere, params::Parameters::utm_zone, and logging::WARNING.

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 902 of file xml_parser_utils.cpp.

    {
        std::string 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 core::World::add(), assign_id_from_attribute(), XmlElement::childElement(), logging::ERROR, radar::Platform::getName(), XmlElement::getSafeAttribute(), XmlElement::isValid(), LOG, serial::xml_parser_utils::ParserContext::parameters, parseFixedRotation(), parseMotionPath(), parsePlatformElements(), parseRotationPath(), Platform, params::Parameters::rotation_angle_unit, and serial::xml_parser_utils::ParserContext::world.

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 866 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 XmlElement::childElement(), XmlElement::isValid(), 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 715 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 = pulsed_mode_element.isValid();
        const radar::OperationMode mode = is_pulsed ? radar::OperationMode::PULSED_MODE : radar::OperationMode::CW_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);
 
        try
        {
            receiver_obj->setNoiseTemperature(get_child_real_type(receiver, "noise_temp"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::INFO, "Receiver '{}' does not specify noise temperature",
                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);
        }
        else if (!receiver.childElement("cw_mode", 0).isValid())
        {
            throw XmlException("Receiver '" + name + "' must specify a radar mode (<pulsed_mode> or <cw_mode>).");
        }
 
        const SimId timing_id = resolve_reference_id(receiver, "timing", "receiver '" + name + "'", *refs.timings);
        const timing::PrototypeTiming* proto = ctx.world->findTiming(timing_id);
        if (proto == nullptr)
        {
            throw XmlException("Timing ID '" + std::to_string(timing_id) + "' not found for receiver '" + name + "'");
        }
        const auto timing_obj =
            std::make_shared<timing::Timing>(proto->getName(), next_seed(*ctx.master_seeder), proto->getId());
        timing_obj->initializeModel(proto);
        receiver_obj->setTiming(timing_obj);
 
        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 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));
        }
 
        ctx.world->add(std::move(receiver_obj));
        return ctx.world->getReceivers().back().get();
    }

References core::World::add(), serial::xml_parser_utils::ReferenceLookup::antennas, assign_id_from_attribute(), XmlElement::childElement(), radar::CW_MODE, logging::DEBUG, core::World::findAntenna(), core::World::findTiming(), radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, get_attribute_bool(), get_child_real_type(), timing::PrototypeTiming::getId(), timing::PrototypeTiming::getName(), core::World::getReceivers(), XmlElement::getSafeAttribute(), logging::INFO, XmlElement::isValid(), LOG, serial::xml_parser_utils::ParserContext::master_seeder, parseSchedule(), radar::PULSED_MODE, Receiver, resolve_reference_id(), serial::xml_parser_utils::ReferenceLookup::timings, and serial::xml_parser_utils::ParserContext::world.

Referenced by parseMonostatic(), and parsePlatformElements().

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 548 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 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, XmlElement::childElement(), logging::ERROR, serial::rotation_angle_utils::external_rotation_to_internal(), math::RotationPath::finalize(), get_child_real_type(), radar::Platform::getName(), radar::Platform::getRotationPath(), XmlElement::getSafeAttribute(), math::RotationPath::INTERP_CUBIC, math::RotationPath::INTERP_LINEAR, math::RotationPath::INTERP_STATIC, XmlElement::isValid(), LOG, 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 99 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 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(std::move(raw_periods), parentName, isPulsed, pri);
    }

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

Referenced by parseReceiver(), and parseTransmitter().

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 814 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 core::World::add(), assign_id_from_attribute(), XmlElement::childElement(), radar::createIsoTarget(), logging::DEBUG, get_child_real_type(), radar::Platform::getName(), XmlElement::getSafeAttribute(), XmlElement::isValid(), serial::xml_parser_utils::ParserContext::loaders, serial::xml_parser_utils::AssetLoaders::loadFileTarget, LOG, serial::xml_parser_utils::ParserContext::master_seeder, Target, and serial::xml_parser_utils::ParserContext::world.

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 363 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 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"));
        }
 
        try
        {
            timing_obj->setFreqOffset(get_child_real_type(timing, "freq_offset"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::WARNING, "Clock section '{}' does not specify frequency offset.", name);
        }
 
        try
        {
            timing_obj->setRandomFreqOffsetStdev(get_child_real_type(timing, "random_freq_offset_stdev"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::WARNING, "Clock section '{}' does not specify random frequency offset.", name);
        }
 
        try
        {
            timing_obj->setPhaseOffset(get_child_real_type(timing, "phase_offset"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::WARNING, "Clock section '{}' does not specify phase offset.", name);
        }
 
        try
        {
            timing_obj->setRandomPhaseOffsetStdev(get_child_real_type(timing, "random_phase_offset_stdev"));
        }
        catch (XmlException&)
        {
            LOG(logging::Level::WARNING, "Clock section '{}' does not specify random phase offset.", name);
        }
 
        if (get_attribute_bool(timing, "synconpulse", false))
        {
            timing_obj->setSyncOnPulse();
        }
 
        ctx.world->add(std::move(timing_obj));
    }

References core::World::add(), assign_id_from_attribute(), get_attribute_bool(), get_child_real_type(), XmlElement::getSafeAttribute(), XmlElement::isValid(), LOG, Timing, logging::WARNING, and serial::xml_parser_utils::ParserContext::world.

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 650 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 = pulsed_mode_element.isValid();
        const radar::OperationMode mode = is_pulsed ? radar::OperationMode::PULSED_MODE : radar::OperationMode::CW_MODE;
 
        if (!is_pulsed && !transmitter.childElement("cw_mode", 0).isValid())
        {
            throw XmlException("Transmitter '" + name + "' must specify a radar mode (<pulsed_mode> or <cw_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 +
                               "'");
        }
        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);
        const timing::PrototypeTiming* proto = ctx.world->findTiming(timing_id);
        if (proto == nullptr)
        {
            throw XmlException("Timing ID '" + std::to_string(timing_id) + "' not found for transmitter '" + name +
                               "'");
        }
        const auto timing_obj =
            std::make_shared<timing::Timing>(proto->getName(), next_seed(*ctx.master_seeder), proto->getId());
        timing_obj->initializeModel(proto);
        transmitter_obj->setTiming(timing_obj);
 
        RealType pri = is_pulsed ? (1.0 / transmitter_obj->getPrf()) : 0.0;
        auto schedule = parseSchedule(transmitter, name, is_pulsed, pri);
        if (!schedule.empty())
        {
            transmitter_obj->setSchedule(std::move(schedule));
        }
 
        ctx.world->add(std::move(transmitter_obj));
        return ctx.world->getTransmitters().back().get();
    }

References core::World::add(), serial::xml_parser_utils::ReferenceLookup::antennas, assign_id_from_attribute(), XmlElement::childElement(), radar::CW_MODE, core::World::findAntenna(), core::World::findTiming(), core::World::findWaveform(), get_child_real_type(), timing::PrototypeTiming::getId(), timing::PrototypeTiming::getName(), XmlElement::getSafeAttribute(), core::World::getTransmitters(), XmlElement::isValid(), serial::xml_parser_utils::ParserContext::master_seeder, parseSchedule(), radar::PULSED_MODE, resolve_reference_id(), serial::xml_parser_utils::ReferenceLookup::timings, Transmitter, serial::xml_parser_utils::ReferenceLookup::waveforms, and serial::xml_parser_utils::ParserContext::world.

Referenced by parseMonostatic(), and parsePlatformElements().

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 327 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
        {
            LOG(logging::Level::FATAL, "Unsupported waveform type for '{}'", name);
            throw XmlException("Unsupported waveform type for '" + name + "'");
        }
    }

References core::World::add(), assign_id_from_attribute(), serial::xml_parser_utils::ParserContext::base_dir, XmlElement::childElement(), params::Parameters::end, logging::FATAL, get_child_real_type(), XmlElement::getSafeAttribute(), XmlElement::isValid(), serial::xml_parser_utils::ParserContext::loaders, serial::xml_parser_utils::AssetLoaders::loadWaveform, LOG, serial::xml_parser_utils::ParserContext::parameters, params::Parameters::start, Waveform, and serial::xml_parser_utils::ParserContext::world.

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 1009 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 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);
                      });
 
        const RealType start_time = ctx.parameters.start;
        const RealType end_time = ctx.parameters.end;
        const RealType dt_sim = 1.0 / (ctx.parameters.rate * ctx.parameters.oversample_ratio);
        const auto num_samples = static_cast<size_t>(std::ceil((end_time - start_time) / dt_sim));
 
        for (const auto& receiver : ctx.world->getReceivers())
        {
            if (receiver->getMode() == radar::OperationMode::CW_MODE)
            {
                receiver->prepareCwData(num_samples);
            }
        }
 
        ctx.world->scheduleInitialEvents();
 
        LOG(logging::Level::DEBUG, "Initial Event Queue State:\n{}", ctx.world->dumpEventQueue());
    }

References XmlElement::childElement(), radar::CW_MODE, logging::DEBUG, core::World::dumpEventQueue(), params::Parameters::end, core::World::getAntennas(), core::World::getReceivers(), XmlDocument::getRootElement(), XmlElement::getSafeAttribute(), core::World::getTimings(), core::World::getWaveforms(), logging::INFO, XmlElement::isValid(), LOG, XmlElement::name(), params::Parameters::oversample_ratio, serial::xml_parser_utils::ParserContext::parameters, params::params, parseAntenna(), parseParameters(), parsePlatform(), parseTiming(), parseWaveform(), params::Parameters::rate, core::World::scheduleInitialEvents(), params::Parameters::simulation_name, params::Parameters::start, logging::WARNING, and serial::xml_parser_utils::ParserContext::world.

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 83 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().

Referenced by parseReceiver(), and parseTransmitter().

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 991 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, XmlDocument::validateWithDtd(), and XmlDocument::validateWithXsd().

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

Here is the call graph for this function:

Here is the caller graph for this function: