Shared plane-chart helpers for chart-aware 2D field parameterization. More...

#include "operators/stimulus/coords.h"
#include <stdbool.h>

Include dependency graph for plane_chart.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	SimPlaneSamplingFrame
	Sampling frame that maps field sample coordinates into chart input space. More...

struct	SimPlaneChartConfig
	Parameters selecting and shaping a reusable 2D plane chart. More...

struct	SimPlaneProjectionConfig
	Projection policy for reducing chart coordinates to stimulus values. More...

struct	SimPlaneChartCoord
	Pair of primary and secondary coordinates produced by a plane chart. More...

struct	SimPlaneProjectionValue
	Projected chart value with an optional secondary coordinate. More...

Macros
#define	SIM_PLANE_CHART_EPS 1.0e-12

Typedefs
typedef enum SimPlaneChartKind	SimPlaneChartKind
	Coordinate chart families available for 2D plane parameterization.

typedef enum SimPlaneProjectionKind	SimPlaneProjectionKind
	Projection modes used to reduce chart coordinates to output values.

typedef enum SimPlaneChartWrapPolicy	SimPlaneChartWrapPolicy
	Wrapping policies for secondary chart coordinates.

typedef enum SimPlaneChartStatus	SimPlaneChartStatus
	Status values returned by plane-chart helpers.

typedef struct SimPlaneSamplingFrame	SimPlaneSamplingFrame
	Sampling frame that maps field sample coordinates into chart input space.

typedef struct SimPlaneChartConfig	SimPlaneChartConfig
	Parameters selecting and shaping a reusable 2D plane chart.

typedef struct SimPlaneProjectionConfig	SimPlaneProjectionConfig
	Projection policy for reducing chart coordinates to stimulus values.

typedef struct SimPlaneChartCoord	SimPlaneChartCoord
	Pair of primary and secondary coordinates produced by a plane chart.

typedef struct SimPlaneProjectionValue	SimPlaneProjectionValue
	Projected chart value with an optional secondary coordinate.

Enumerations
enum	SimPlaneChartKind { SIM_PLANE_CHART_CARTESIAN = 0 , SIM_PLANE_CHART_POLAR , SIM_PLANE_CHART_ELLIPTIC , SIM_PLANE_CHART_SPIRAL }
	Coordinate chart families available for 2D plane parameterization. More...

enum	SimPlaneProjectionKind { SIM_PLANE_PROJECTION_FULL = 0 , SIM_PLANE_PROJECTION_PRIMARY , SIM_PLANE_PROJECTION_SECONDARY }
	Projection modes used to reduce chart coordinates to output values. More...

enum	SimPlaneChartWrapPolicy { SIM_PLANE_CHART_WRAP_NONE = 0 , SIM_PLANE_CHART_WRAP_SIGNED_ANGLE , SIM_PLANE_CHART_WRAP_UNSIGNED_ANGLE , SIM_PLANE_CHART_WRAP_UNIT_INTERVAL }
	Wrapping policies for secondary chart coordinates. More...

enum	SimPlaneChartStatus { SIM_PLANE_CHART_STATUS_OK = 0 , SIM_PLANE_CHART_STATUS_INVALID_ARGUMENT , SIM_PLANE_CHART_STATUS_UNSUPPORTED , SIM_PLANE_CHART_STATUS_OUT_OF_DOMAIN , SIM_PLANE_CHART_STATUS_SINGULAR , SIM_PLANE_CHART_STATUS_NON_INVERTIBLE , SIM_PLANE_CHART_STATUS_NUMERIC_FAILURE }
	Status values returned by plane-chart helpers. More...

enum	{ SIM_PLANE_CHART_SEMANTIC_NONE = 0u , SIM_PLANE_CHART_SEMANTIC_PERIODIC_SECONDARY = 1u << 0 , SIM_PLANE_CHART_SEMANTIC_SINGULAR_CENTER = 1u << 1 , SIM_PLANE_CHART_SEMANTIC_SECONDARY_BRANCH_CUT = 1u << 2 }

enum	{ SIM_PLANE_CHART_CAPABILITY_NONE = 0u }

Functions
const char *	sim_plane_chart_status_string (SimPlaneChartStatus status)
	Human-readable description of a plane-chart status.

void	sim_plane_sampling_frame_normalize (SimPlaneSamplingFrame *frame)
	Normalize a sampling frame in-place.

void	sim_plane_chart_normalize (SimPlaneChartConfig *chart)
	Normalize a plane-chart config in-place.

void	sim_plane_projection_normalize (SimPlaneProjectionConfig *projection)
	Normalize a projection config in-place.

unsigned int	sim_plane_chart_semantic_flags (const SimPlaneChartConfig *chart)
	Semantic metadata flags for a chart configuration.

unsigned int	sim_plane_chart_capability_flags (const SimPlaneChartConfig *chart)
	Numerical capability flags currently exposed for a chart configuration.

SimPlaneChartStatus	sim_plane_chart_eval (const SimPlaneSamplingFrame frame, const SimPlaneChartConfig chart, double x, double y, double t, SimPlaneChartCoord *out_coord)
	Evaluate the chart coordinates at the provided sample-space point.

SimPlaneChartStatus	sim_plane_projection_eval (const SimPlaneProjectionConfig projection, SimPlaneChartCoord coord, SimPlaneProjectionValue out_value)
	Project chart coordinates into a value surface.

SimPlaneChartStatus	sim_plane_chart_eval_projected (const SimPlaneSamplingFrame frame, const SimPlaneChartConfig chart, const SimPlaneProjectionConfig projection, double x, double y, double t, SimPlaneProjectionValue out_value)
	Convenience wrapper for chart evaluation followed by projection.

SimPlaneChartStatus	sim_plane_chart_from_stimulus_coord (const SimStimulusCoordConfig coord, SimPlaneSamplingFrame out_frame, SimPlaneChartConfig out_chart, SimPlaneProjectionConfig out_projection)
	Build a frame/chart/projection triple from a legacy stimulus coord config.

Detailed Description

Shared plane-chart helpers for chart-aware 2D field parameterization.

This Phase 1 slice is compatibility-first: it defines a reusable sampling frame, chart, and projection surface, plus an adapter from the existing SimStimulusCoordConfig for the supported non-separable modes.

Enumeration Type Documentation

◆ SimPlaneChartKind

enum SimPlaneChartKind

Coordinate chart families available for 2D plane parameterization.

Enumerator
SIM_PLANE_CHART_CARTESIAN	Cartesian x/y chart.
SIM_PLANE_CHART_POLAR	Polar radius/angle chart.
SIM_PLANE_CHART_ELLIPTIC	Elliptic radius/angle-like chart.
SIM_PLANE_CHART_SPIRAL	Spiral phase/radius chart.

◆ SimPlaneChartStatus

enum SimPlaneChartStatus

Status values returned by plane-chart helpers.

Enumerator
SIM_PLANE_CHART_STATUS_OK	Chart operation completed successfully.
SIM_PLANE_CHART_STATUS_INVALID_ARGUMENT	NULL or invalid input was supplied.
SIM_PLANE_CHART_STATUS_UNSUPPORTED	Requested chart/projection is unsupported.
SIM_PLANE_CHART_STATUS_OUT_OF_DOMAIN	Coordinates lie outside the chart domain.
SIM_PLANE_CHART_STATUS_SINGULAR	Chart evaluation hit a singular point.
SIM_PLANE_CHART_STATUS_NON_INVERTIBLE	Requested transform is not invertible.
SIM_PLANE_CHART_STATUS_NUMERIC_FAILURE	Non-finite or unstable numeric result.

◆ SimPlaneChartWrapPolicy

enum SimPlaneChartWrapPolicy

Wrapping policies for secondary chart coordinates.

Enumerator
SIM_PLANE_CHART_WRAP_NONE	Leave the secondary coordinate unwrapped.
SIM_PLANE_CHART_WRAP_SIGNED_ANGLE	Wrap to a signed angular interval.
SIM_PLANE_CHART_WRAP_UNSIGNED_ANGLE	Wrap to an unsigned angular interval.
SIM_PLANE_CHART_WRAP_UNIT_INTERVAL	Wrap to the unit interval [0, 1).

◆ SimPlaneProjectionKind

enum SimPlaneProjectionKind

Projection modes used to reduce chart coordinates to output values.

Enumerator
SIM_PLANE_PROJECTION_FULL	Preserve both primary and secondary coordinates.
SIM_PLANE_PROJECTION_PRIMARY	Emit only the primary coordinate.
SIM_PLANE_PROJECTION_SECONDARY	Emit only the secondary coordinate.

Function Documentation

◆ sim_plane_chart_capability_flags()

unsigned int sim_plane_chart_capability_flags ( const SimPlaneChartConfig * chart )

Numerical capability flags currently exposed for a chart configuration.

Parameters

chart Chart config to inspect.

Returns: Bitmask of SIM_PLANE_CHART_CAPABILITY_* values.

◆ sim_plane_chart_eval()

SimPlaneChartStatus sim_plane_chart_eval	(	const SimPlaneSamplingFrame *	frame,
		const SimPlaneChartConfig *	chart,
		double	x,
		double	y,
		double	t,
		SimPlaneChartCoord *	out_coord
	)

Evaluate the chart coordinates at the provided sample-space point.

Parameters

	frame	Sampling frame that maps sample indices to world coordinates.
	chart	Chart transform to evaluate.
	x	Sample-space x coordinate.
	y	Sample-space y coordinate.
	t	Simulation time used for frame velocity and spiral angular velocity.
[out]	out_coord	Receives primary/secondary chart coordinates.

Returns: Chart status indicating success, invalid input, unsupported chart, or numeric failure.

◆ sim_plane_chart_eval_projected()

SimPlaneChartStatus sim_plane_chart_eval_projected	(	const SimPlaneSamplingFrame *	frame,
		const SimPlaneChartConfig *	chart,
		const SimPlaneProjectionConfig *	projection,
		double	x,
		double	y,
		double	t,
		SimPlaneProjectionValue *	out_value
	)

Convenience wrapper for chart evaluation followed by projection.

Parameters

	frame	Sampling frame that maps sample indices to world coordinates.
	chart	Chart transform to evaluate.
	projection	Projection policy applied after chart evaluation.
	x	Sample-space x coordinate.
	y	Sample-space y coordinate.
	t	Simulation time used by moving charts.
[out]	out_value	Receives the projected value.

Returns: First non-OK status from chart or projection evaluation.

◆ sim_plane_chart_from_stimulus_coord()

SimPlaneChartStatus sim_plane_chart_from_stimulus_coord	(	const SimStimulusCoordConfig *	coord,
		SimPlaneSamplingFrame *	out_frame,
		SimPlaneChartConfig *	out_chart,
		SimPlaneProjectionConfig *	out_projection
	)

Build a frame/chart/projection triple from a legacy stimulus coord config.

Returns SIM_PLANE_CHART_STATUS_UNSUPPORTED for structural modes that do not yet have a shared chart representation, such as SEPARABLE.

Parameters

	coord	Legacy stimulus coordinate config.
[out]	out_frame	Receives the normalized sampling frame.
[out]	out_chart	Receives the normalized chart config.
[out]	out_projection	Receives the normalized projection config.

Returns: SIM_PLANE_CHART_STATUS_OK, SIM_PLANE_CHART_STATUS_INVALID_ARGUMENT, or SIM_PLANE_CHART_STATUS_UNSUPPORTED.

◆ sim_plane_chart_normalize()

void sim_plane_chart_normalize ( SimPlaneChartConfig * chart )

Normalize a plane-chart config in-place.

Invalid enum values and non-finite chart parameters are replaced with cartesian/signed-angle-compatible defaults.

Parameters

chart Chart config to normalize; NULL is ignored.

◆ sim_plane_chart_semantic_flags()

unsigned int sim_plane_chart_semantic_flags ( const SimPlaneChartConfig * chart )

Semantic metadata flags for a chart configuration.

Parameters

chart Chart config to inspect; NULL is treated as no semantics.

Returns: Bitmask of SIM_PLANE_CHART_SEMANTIC_* values.

◆ sim_plane_chart_status_string()

const char * sim_plane_chart_status_string ( SimPlaneChartStatus status )

Human-readable description of a plane-chart status.

Parameters

status Status enum value.

Returns: Static machine-readable string such as "ok" or "numeric-failure".

◆ sim_plane_projection_eval()

SimPlaneChartStatus sim_plane_projection_eval	(	const SimPlaneProjectionConfig *	projection,
		SimPlaneChartCoord	coord,
		SimPlaneProjectionValue *	out_value
	)

Project chart coordinates into a value surface.

Parameters

	projection	Projection policy.
	coord	Chart coordinates to project; values must be finite.
[out]	out_value	Receives primary value and optional secondary value.

Returns: SIM_PLANE_CHART_STATUS_OK or SIM_PLANE_CHART_STATUS_INVALID_ARGUMENT.

◆ sim_plane_projection_normalize()

void sim_plane_projection_normalize ( SimPlaneProjectionConfig * projection )

Normalize a projection config in-place.

Parameters

projection Projection config to normalize; NULL is ignored.

◆ sim_plane_sampling_frame_normalize()

void sim_plane_sampling_frame_normalize ( SimPlaneSamplingFrame * frame )

Normalize a sampling frame in-place.

Non-finite origins, centers, and velocities are set to zero. Near-zero or non-finite spacing falls back to finite positive defaults.

Parameters

frame Frame to normalize; NULL is ignored.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ SimPlaneChartKind

◆ SimPlaneChartStatus

◆ SimPlaneChartWrapPolicy

◆ SimPlaneProjectionKind

Function Documentation

◆ sim_plane_chart_capability_flags()

◆ sim_plane_chart_eval()

◆ sim_plane_chart_eval_projected()

◆ sim_plane_chart_from_stimulus_coord()

◆ sim_plane_chart_normalize()

◆ sim_plane_chart_semantic_flags()

◆ sim_plane_chart_status_string()

◆ sim_plane_projection_eval()

◆ sim_plane_projection_normalize()

◆ sim_plane_sampling_frame_normalize()