Math Engine Reference: Motion

문서 탐색

개요

Frame과 SI 단위를 명시한 neutral motion 값과 단발 model query를 선언한다.

이 API는 absolute/world time, entity ID, registry, callback과 mutable component를 보관하지 않는다. 모든 시간 입력은 초 단위 local interval이며 caller가 초기화한 versioned POD만 입출력으로 사용한다.

실행 원본: include/math_engine/math_engine_motion.h
분류: 물리·운동·제어

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_motion.h>

Type과 callback

`math_engine_motion_unit_system_t`

Motion POD가 사용하는 고정 단위계다.

typedef enum math_engine_motion_unit_system {
    MATH_ENGINE_MOTION_UNIT_SYSTEM_INVALID = 0, /**< Uninitialized or unsupported unit-system sentinel. */
    MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1 = 1 /**< SI metres, kilograms, seconds and radians contract. */
} math_engine_motion_unit_system_t;

math_engine_motion_unit_system_t.MATH_ENGINE_MOTION_UNIT_SYSTEM_INVALID
Uninitialized or unsupported unit-system sentinel.
```
MATH_ENGINE_MOTION_UNIT_SYSTEM_INVALID = 0,
```
math_engine_motion_unit_system_t.MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1
SI metres, kilograms, seconds and radians contract.
```
MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1 = 1,
```

`math_engine_motion_model_id_t`

공개 motion model의 안정된 식별자다.

typedef enum math_engine_motion_model_id {
    MATH_ENGINE_MOTION_MODEL_INVALID = 0, /**< No model has produced a value. */
    /** Constant-linear-acceleration propagation in one frame. */
    MATH_ENGINE_MOTION_MODEL_LINEAR_CONSTANT_ACCELERATION_V1 = 1,
    /** Subject state relative to a reference state in the same frame. */
    MATH_ENGINE_MOTION_MODEL_RELATIVE_LINEAR_V1 = 2,
    MATH_ENGINE_MOTION_MODEL_AERODYNAMIC_LOAD_V1 = 3, /**< Analytic drag, lift and Magnus load model. */
    MATH_ENGINE_MOTION_MODEL_SPIN_EXPONENTIAL_DECAY_V1 = 4, /**< Exponential angular-velocity decay model. */
    MATH_ENGINE_MOTION_MODEL_LEGACY_SPIN_DRAG_SCALE_V1 = 5 /**< Bounded empirical spin/velocity scale model. */
} math_engine_motion_model_id_t;

math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_INVALID
No model has produced a value.
```
MATH_ENGINE_MOTION_MODEL_INVALID = 0,
```
math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_LINEAR_CONSTANT_ACCELERATION_V1
Constant-linear-acceleration propagation in one frame.
```
/** Constant-linear-acceleration propagation in one frame. */
    MATH_ENGINE_MOTION_MODEL_LINEAR_CONSTANT_ACCELERATION_V1 = 1,
```
math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_RELATIVE_LINEAR_V1
Subject state relative to a reference state in the same frame.
```
/** Subject state relative to a reference state in the same frame. */
    MATH_ENGINE_MOTION_MODEL_RELATIVE_LINEAR_V1 = 2,
```
math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_AERODYNAMIC_LOAD_V1
Analytic drag, lift and Magnus load model.
```
MATH_ENGINE_MOTION_MODEL_AERODYNAMIC_LOAD_V1 = 3,
```
math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_SPIN_EXPONENTIAL_DECAY_V1
Exponential angular-velocity decay model.
```
MATH_ENGINE_MOTION_MODEL_SPIN_EXPONENTIAL_DECAY_V1 = 4,
```
math_engine_motion_model_id_t.MATH_ENGINE_MOTION_MODEL_LEGACY_SPIN_DRAG_SCALE_V1
Bounded empirical spin/velocity scale model.
```
MATH_ENGINE_MOTION_MODEL_LEGACY_SPIN_DRAG_SCALE_V1 = 5,
```

`math_engine_motion_quality_t`

결과가 사용한 수치 또는 empirical 품질이다.

typedef enum math_engine_motion_quality {
    MATH_ENGINE_MOTION_QUALITY_INVALID = 0, /**< No usable quality classification. */
    MATH_ENGINE_MOTION_QUALITY_EXACT_ANALYTIC = 1, /**< Closed-form model evaluated without an approximation policy. */
    MATH_ENGINE_MOTION_QUALITY_FAST_APPROXIMATION = 2, /**< GAME_FAST binary evaluation with a reported error bound. */
    MATH_ENGINE_MOTION_QUALITY_REFINED_BINARY = 3, /**< Higher-precision intermediate binary evaluation. */
    MATH_ENGINE_MOTION_QUALITY_EMPIRICAL_BOUNDED = 4 /**< Empirical output clamped to declared bounds. */
} math_engine_motion_quality_t;

math_engine_motion_quality_t.MATH_ENGINE_MOTION_QUALITY_INVALID
No usable quality classification.
```
MATH_ENGINE_MOTION_QUALITY_INVALID = 0,
```
math_engine_motion_quality_t.MATH_ENGINE_MOTION_QUALITY_EXACT_ANALYTIC
Closed-form model evaluated without an approximation policy.
```
MATH_ENGINE_MOTION_QUALITY_EXACT_ANALYTIC = 1,
```
math_engine_motion_quality_t.MATH_ENGINE_MOTION_QUALITY_FAST_APPROXIMATION
GAME_FAST binary evaluation with a reported error bound.
```
MATH_ENGINE_MOTION_QUALITY_FAST_APPROXIMATION = 2,
```
math_engine_motion_quality_t.MATH_ENGINE_MOTION_QUALITY_REFINED_BINARY
Higher-precision intermediate binary evaluation.
```
MATH_ENGINE_MOTION_QUALITY_REFINED_BINARY = 3,
```
math_engine_motion_quality_t.MATH_ENGINE_MOTION_QUALITY_EMPIRICAL_BOUNDED
Empirical output clamped to declared bounds.
```
MATH_ENGINE_MOTION_QUALITY_EMPIRICAL_BOUNDED = 4,
```

`math_engine_motion_state_f64_t`

동일 frame_id 안의 3차원 motion 순간값이다.

Position은 m, linear velocity는 m/s, linear acceleration은 m/s^2, orientation은 unit quaternion, angular velocity는 rad/s, angular acceleration은 rad/s^2다. frame_id 0은 invalid이고 absolute time field는 의도적으로 없다.

typedef struct math_engine_motion_state_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned POD. */
    uint32_t struct_version; /**< =MATH_ENGINE_MOTION_STATE_F64_VERSION_1=. */
    uint32_t unit_system; /**< Must be =MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1=. */
    uint32_t reserved0; /**< Reserved for ABI growth; must be 0. */
    uint64_t frame_id; /**< Nonzero caller-defined coordinate-frame identity. */
    math_engine_vec3_f64_t position_m; /**< Finite position in =frame_id=, in metres. */
    math_engine_vec3_f64_t linear_velocity_mps; /**< Finite velocity in the same frame, in m/s. */
    math_engine_vec3_f64_t linear_acceleration_mps2; /**< Finite acceleration in the same frame, in m/s^2. */
    math_engine_quat_f64_t orientation; /**< Finite unit quaternion expressed in =frame_id=. */
    math_engine_vec3_f64_t angular_velocity_radps; /**< Right-hand angular velocity in =frame_id=, rad/s. */
    math_engine_vec3_f64_t angular_acceleration_radps2; /**< Right-hand angular acceleration, rad/s^2. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_motion_state_f64_t;

math_engine_motion_state_f64_t.struct_size
Exact byte size of this versioned POD.
```
uint32_t struct_size;
```
math_engine_motion_state_f64_t.struct_version
MATH_ENGINE_MOTION_STATE_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_motion_state_f64_t.unit_system
Must be MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1.
```
uint32_t unit_system;
```
math_engine_motion_state_f64_t.reserved0
Reserved for ABI growth; must be 0.
```
uint32_t reserved0;
```
math_engine_motion_state_f64_t.frame_id
Nonzero caller-defined coordinate-frame identity.
```
uint64_t frame_id;
```
math_engine_motion_state_f64_t.position_m
Finite position in frame_id, in metres.
```
math_engine_vec3_f64_t position_m;
```
math_engine_motion_state_f64_t.linear_velocity_mps
Finite velocity in the same frame, in m/s.
```
math_engine_vec3_f64_t linear_velocity_mps;
```
math_engine_motion_state_f64_t.linear_acceleration_mps2
Finite acceleration in the same frame, in m/s^2.
```
math_engine_vec3_f64_t linear_acceleration_mps2;
```
math_engine_motion_state_f64_t.orientation
Finite unit quaternion expressed in frame_id.
```
math_engine_quat_f64_t orientation;
```
math_engine_motion_state_f64_t.angular_velocity_radps
Right-hand angular velocity in frame_id, rad/s.
```
math_engine_vec3_f64_t angular_velocity_radps;
```
math_engine_motion_state_f64_t.angular_acceleration_radps2
Right-hand angular acceleration, rad/s^2.
```
math_engine_vec3_f64_t angular_acceleration_radps2;
```
math_engine_motion_state_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_motion_result_f64_t`

선형 kinematics와 relative query의 versioned 결과다.

typedef struct math_engine_motion_result_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned result. */
    uint32_t struct_version; /**< =MATH_ENGINE_MOTION_RESULT_F64_VERSION_1=. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_RESULT_FLAG_*= value/quality diagnostics. */
    uint32_t model_id; /**< One =math_engine_motion_model_id_t= identifying the calculation. */
    uint32_t model_version; /**< Semantic version of the selected model; currently 1. */
    uint32_t quality; /**< One =math_engine_motion_quality_t= for the committed result. */
    uint32_t reserved0; /**< Reserved for ABI growth; must be 0. */
    uint32_t reserved1; /**< Reserved for ABI growth; must be 0. */
    math_engine_motion_state_f64_t state; /**< Propagated or relative SI state in its nonzero frame. */
    double local_interval_seconds; /**< Nonnegative local propagation interval in seconds. */
    double residual; /**< Model-specific nonnegative residual; 0 for closed-form propagation. */
    double error_bound; /**< Nonnegative absolute floating-point error bound. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_motion_result_f64_t;

math_engine_motion_result_f64_t.struct_size
Exact byte size of this versioned result.
```
uint32_t struct_size;
```
math_engine_motion_result_f64_t.struct_version
MATH_ENGINE_MOTION_RESULT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_motion_result_f64_t.flags
Bitwise MATH_ENGINE_RESULT_FLAG_* value/quality diagnostics.
```
uint32_t flags;
```
math_engine_motion_result_f64_t.model_id
One math_engine_motion_model_id_t identifying the calculation.
```
uint32_t model_id;
```
math_engine_motion_result_f64_t.model_version
Semantic version of the selected model; currently 1.
```
uint32_t model_version;
```
math_engine_motion_result_f64_t.quality
One math_engine_motion_quality_t for the committed result.
```
uint32_t quality;
```
math_engine_motion_result_f64_t.reserved0
Reserved for ABI growth; must be 0.
```
uint32_t reserved0;
```
math_engine_motion_result_f64_t.reserved1
Reserved for ABI growth; must be 0.
```
uint32_t reserved1;
```
math_engine_motion_result_f64_t.state
Propagated or relative SI state in its nonzero frame.
```
math_engine_motion_state_f64_t state;
```
math_engine_motion_result_f64_t.local_interval_seconds
Nonnegative local propagation interval in seconds.
```
double local_interval_seconds;
```
math_engine_motion_result_f64_t.residual
Model-specific nonnegative residual; 0 for closed-form propagation.
```
double residual;
```
math_engine_motion_result_f64_t.error_bound
Nonnegative absolute floating-point error bound.
```
double error_bound;
```
math_engine_motion_result_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_aerodynamic_input_f64_t`

Aerodynamic load에 필요한 모든 물리량을 명시하는 caller-owned 입력이다.

typedef struct math_engine_aerodynamic_input_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned input. */
    uint32_t struct_version; /**< =MATH_ENGINE_AERODYNAMIC_INPUT_F64_VERSION_1=. */
    uint32_t unit_system; /**< Must be =MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1=. */
    uint32_t reserved0; /**< Reserved for ABI growth; must be 0. */
    uint64_t frame_id; /**< Nonzero frame shared by every vector in this input. */
    /** Body velocity minus fluid velocity, m/s. */
    math_engine_vec3_f64_t relative_flow_velocity_mps;
    /** Right-hand angular velocity, rad/s. */
    math_engine_vec3_f64_t spin_radps;
    /** Lift 방향 후보. Lift가 0이 아니면 flow에 수직인 성분이 필요하다. */
    math_engine_vec3_f64_t lift_reference_direction;
    double fluid_density_kg_per_m3; /**< Finite positive fluid density in kg/m^3. */
    double reference_area_m2; /**< Finite positive aerodynamic reference area in m^2. */
    double characteristic_length_m; /**< Finite positive Magnus reference length in metres. */
    double mass_kg; /**< Finite positive body mass used to derive acceleration, in kg. */
    double drag_coefficient; /**< Finite nonnegative dimensionless drag coefficient. */
    double lift_coefficient; /**< Finite nonnegative dimensionless lift coefficient. */
    /** =rho*A*L*C_m*(omega x v)=에서 사용하는 dimensionless 계수다. */
    double magnus_coefficient;
    double reserved_scalar; /**< Reserved scalar; must be exactly 0.0. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_aerodynamic_input_f64_t;

math_engine_aerodynamic_input_f64_t.struct_size
Exact byte size of this versioned input.
```
uint32_t struct_size;
```
math_engine_aerodynamic_input_f64_t.struct_version
MATH_ENGINE_AERODYNAMIC_INPUT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_aerodynamic_input_f64_t.unit_system
Must be MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1.
```
uint32_t unit_system;
```
math_engine_aerodynamic_input_f64_t.reserved0
Reserved for ABI growth; must be 0.
```
uint32_t reserved0;
```
math_engine_aerodynamic_input_f64_t.frame_id
Nonzero frame shared by every vector in this input.
```
uint64_t frame_id;
```

math_engine_aerodynamic_input_f64_t.relative_flow_velocity_mps

Body velocity minus fluid velocity, m/s.

/** Body velocity minus fluid velocity, m/s. */
    math_engine_vec3_f64_t relative_flow_velocity_mps;

math_engine_aerodynamic_input_f64_t.spin_radps

Right-hand angular velocity, rad/s.

/** Right-hand angular velocity, rad/s. */
    math_engine_vec3_f64_t spin_radps;

math_engine_aerodynamic_input_f64_t.lift_reference_direction

Lift 방향 후보. Lift가 0이 아니면 flow에 수직인 성분이 필요하다.

/** Lift 방향 후보. Lift가 0이 아니면 flow에 수직인 성분이 필요하다. */
    math_engine_vec3_f64_t lift_reference_direction;

math_engine_aerodynamic_input_f64_t.fluid_density_kg_per_m3
Finite positive fluid density in kg/m^3.
```
double fluid_density_kg_per_m3;
```
math_engine_aerodynamic_input_f64_t.reference_area_m2
Finite positive aerodynamic reference area in m^2.
```
double reference_area_m2;
```
math_engine_aerodynamic_input_f64_t.characteristic_length_m
Finite positive Magnus reference length in metres.
```
double characteristic_length_m;
```
math_engine_aerodynamic_input_f64_t.mass_kg
Finite positive body mass used to derive acceleration, in kg.
```
double mass_kg;
```
math_engine_aerodynamic_input_f64_t.drag_coefficient
Finite nonnegative dimensionless drag coefficient.
```
double drag_coefficient;
```
math_engine_aerodynamic_input_f64_t.lift_coefficient
Finite nonnegative dimensionless lift coefficient.
```
double lift_coefficient;
```
math_engine_aerodynamic_input_f64_t.magnus_coefficient
rho*A*L*C_m*(omega x v) 에서 사용하는 dimensionless 계수다.
```
/** =rho*A*L*C_m*(omega x v)=에서 사용하는 dimensionless 계수다. */
    double magnus_coefficient;
```
math_engine_aerodynamic_input_f64_t.reserved_scalar
Reserved scalar; must be exactly 0.0.
```
double reserved_scalar;
```
math_engine_aerodynamic_input_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_motion_model_result_f64_t`

Force, acceleration, spin 또는 empirical scalar model의 versioned 결과다.

typedef struct math_engine_motion_model_result_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned result. */
    uint32_t struct_version; /**< =MATH_ENGINE_MOTION_MODEL_RESULT_F64_VERSION_1=. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_RESULT_FLAG_*= value/quality diagnostics. */
    uint32_t model_id; /**< One =math_engine_motion_model_id_t= identifying the model. */
    uint32_t model_version; /**< Semantic model version; currently 1. */
    uint32_t quality; /**< One =math_engine_motion_quality_t= for this value. */
    uint32_t reserved0; /**< Reserved for ABI growth; must be 0. */
    uint32_t reserved1; /**< Reserved for ABI growth; must be 0. */
    uint64_t frame_id; /**< Nonzero coordinate frame for vector outputs. */
    /** Load model에서는 total force(N), spin model에서는 angular velocity(rad/s)다. */
    math_engine_vec3_f64_t vector_value;
    /** Load model에서는 linear acceleration(m/s^2)다. */
    math_engine_vec3_f64_t secondary_vector;
    /** Load model에서는 Magnus force(N)다. */
    math_engine_vec3_f64_t tertiary_vector;
    /** Load model에서는 drag magnitude(N), spin/heuristic에서는 retention/scale이다. */
    double scalar_value;
    /** Load model에서는 lift magnitude(N)다. */
    double secondary_value;
    double residual; /**< Model-specific signed residual or clamp correction. */
    double error_bound; /**< Nonnegative absolute numerical error bound. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_motion_model_result_f64_t;

math_engine_motion_model_result_f64_t.struct_size
Exact byte size of this versioned result.
```
uint32_t struct_size;
```
math_engine_motion_model_result_f64_t.struct_version
MATH_ENGINE_MOTION_MODEL_RESULT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_motion_model_result_f64_t.flags
Bitwise MATH_ENGINE_RESULT_FLAG_* value/quality diagnostics.
```
uint32_t flags;
```
math_engine_motion_model_result_f64_t.model_id
One math_engine_motion_model_id_t identifying the model.
```
uint32_t model_id;
```
math_engine_motion_model_result_f64_t.model_version
Semantic model version; currently 1.
```
uint32_t model_version;
```
math_engine_motion_model_result_f64_t.quality
One math_engine_motion_quality_t for this value.
```
uint32_t quality;
```
math_engine_motion_model_result_f64_t.reserved0
Reserved for ABI growth; must be 0.
```
uint32_t reserved0;
```
math_engine_motion_model_result_f64_t.reserved1
Reserved for ABI growth; must be 0.
```
uint32_t reserved1;
```
math_engine_motion_model_result_f64_t.frame_id
Nonzero coordinate frame for vector outputs.
```
uint64_t frame_id;
```

math_engine_motion_model_result_f64_t.vector_value

Load model에서는 total force(N), spin model에서는 angular velocity(rad/s)다.

/** Load model에서는 total force(N), spin model에서는 angular velocity(rad/s)다. */
    math_engine_vec3_f64_t vector_value;

math_engine_motion_model_result_f64_t.secondary_vector

Load model에서는 linear acceleration(m/s^2)다.

/** Load model에서는 linear acceleration(m/s^2)다. */
    math_engine_vec3_f64_t secondary_vector;

math_engine_motion_model_result_f64_t.tertiary_vector

Load model에서는 Magnus force(N)다.

/** Load model에서는 Magnus force(N)다. */
    math_engine_vec3_f64_t tertiary_vector;

math_engine_motion_model_result_f64_t.scalar_value
Load model에서는 drag magnitude(N), spin/heuristic에서는 retention/scale이다.
```
/** Load model에서는 drag magnitude(N), spin/heuristic에서는 retention/scale이다. */
    double scalar_value;
```
math_engine_motion_model_result_f64_t.secondary_value
Load model에서는 lift magnitude(N)다.
```
/** Load model에서는 lift magnitude(N)다. */
    double secondary_value;
```
math_engine_motion_model_result_f64_t.residual
Model-specific signed residual or clamp correction.
```
double residual;
```
math_engine_motion_model_result_f64_t.error_bound
Nonnegative absolute numerical error bound.
```
double error_bound;
```
math_engine_motion_model_result_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_motion_candidate_kind_t`

Entity-free steering 후보 DTO의 종류다. 이 type은 entity 수명주기를 표현하지 않는다.

typedef enum math_engine_motion_candidate_kind {
    MATH_ENGINE_MOTION_CANDIDATE_INVALID = 0, /**< Uninitialized or unsupported candidate sentinel. */
    MATH_ENGINE_MOTION_CANDIDATE_SPRING = 1, /**< Spring-like attraction toward the desired separation. */
    MATH_ENGINE_MOTION_CANDIDATE_AVOIDANCE = 2, /**< Repulsive avoidance acceleration candidate. */
    MATH_ENGINE_MOTION_CANDIDATE_ENCIRCLEMENT = 3 /**< Tangential encirclement acceleration candidate. */
} math_engine_motion_candidate_kind_t;

math_engine_motion_candidate_kind_t.MATH_ENGINE_MOTION_CANDIDATE_INVALID
Uninitialized or unsupported candidate sentinel.
```
MATH_ENGINE_MOTION_CANDIDATE_INVALID = 0,
```
math_engine_motion_candidate_kind_t.MATH_ENGINE_MOTION_CANDIDATE_SPRING
Spring-like attraction toward the desired separation.
```
MATH_ENGINE_MOTION_CANDIDATE_SPRING = 1,
```
math_engine_motion_candidate_kind_t.MATH_ENGINE_MOTION_CANDIDATE_AVOIDANCE
Repulsive avoidance acceleration candidate.
```
MATH_ENGINE_MOTION_CANDIDATE_AVOIDANCE = 2,
```
math_engine_motion_candidate_kind_t.MATH_ENGINE_MOTION_CANDIDATE_ENCIRCLEMENT
Tangential encirclement acceleration candidate.
```
MATH_ENGINE_MOTION_CANDIDATE_ENCIRCLEMENT = 3,
```

`math_engine_motion_candidate_input_f64_t`

Consumer adapter가 순수 후보 kernel에 전달할 entity-free 입력 DTO다.

두 vector는 대상과 기준의 상대 위치(m)와 상대 속도(m/s)다. Parameter 의미는 versioned candidate kind가 정하며 이 TODO에서는 저장·callback 없이 layout과 검증만 고정한다.

typedef struct math_engine_motion_candidate_input_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned input. */
    uint32_t struct_version; /**< =MATH_ENGINE_MOTION_CANDIDATE_INPUT_F64_VERSION_1=. */
    uint32_t kind; /**< One non-invalid =math_engine_motion_candidate_kind_t=. */
    uint32_t unit_system; /**< Must be =MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1=. */
    uint64_t frame_id; /**< Nonzero frame shared by both relative vectors and output. */
    math_engine_vec3_f64_t relative_position_m; /**< Target-minus-reference displacement in metres. */
    math_engine_vec3_f64_t relative_velocity_mps; /**< Target-minus-reference velocity in m/s. */
    double primary_gain; /**< Finite nonnegative kind-specific position/radial gain. */
    double secondary_gain; /**< Finite nonnegative kind-specific velocity/tangential gain. */
    double desired_distance_m; /**< Finite nonnegative target separation in metres. */
    double acceleration_limit_mps2; /**< Finite positive acceleration magnitude limit in m/s^2. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_motion_candidate_input_f64_t;

math_engine_motion_candidate_input_f64_t.struct_size
Exact byte size of this versioned input.
```
uint32_t struct_size;
```
math_engine_motion_candidate_input_f64_t.struct_version
MATH_ENGINE_MOTION_CANDIDATE_INPUT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_motion_candidate_input_f64_t.kind
One non-invalid math_engine_motion_candidate_kind_t.
```
uint32_t kind;
```
math_engine_motion_candidate_input_f64_t.unit_system
Must be MATH_ENGINE_MOTION_UNIT_SYSTEM_SI_V1.
```
uint32_t unit_system;
```
math_engine_motion_candidate_input_f64_t.frame_id
Nonzero frame shared by both relative vectors and output.
```
uint64_t frame_id;
```
math_engine_motion_candidate_input_f64_t.relative_position_m
Target-minus-reference displacement in metres.
```
math_engine_vec3_f64_t relative_position_m;
```
math_engine_motion_candidate_input_f64_t.relative_velocity_mps
Target-minus-reference velocity in m/s.
```
math_engine_vec3_f64_t relative_velocity_mps;
```
math_engine_motion_candidate_input_f64_t.primary_gain
Finite nonnegative kind-specific position/radial gain.
```
double primary_gain;
```
math_engine_motion_candidate_input_f64_t.secondary_gain
Finite nonnegative kind-specific velocity/tangential gain.
```
double secondary_gain;
```
math_engine_motion_candidate_input_f64_t.desired_distance_m
Finite nonnegative target separation in metres.
```
double desired_distance_m;
```
math_engine_motion_candidate_input_f64_t.acceleration_limit_mps2
Finite positive acceleration magnitude limit in m/s^2.
```
double acceleration_limit_mps2;
```
math_engine_motion_candidate_input_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_motion_candidate_output_f64_t`

Consumer가 후보 값과 정책 score를 전달받기 위한 entity-free 출력 DTO다.

typedef struct math_engine_motion_candidate_output_f64 {
    uint32_t struct_size; /**< Exact byte size of this versioned output. */
    uint32_t struct_version; /**< =MATH_ENGINE_MOTION_CANDIDATE_OUTPUT_F64_VERSION_1=. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_RESULT_FLAG_*= status diagnostics. */
    uint32_t kind; /**< Candidate kind whose value this output carries. */
    uint64_t frame_id; /**< Nonzero frame of =acceleration_mps2=. */
    math_engine_vec3_f64_t acceleration_mps2; /**< Finite candidate acceleration in m/s^2. */
    double score; /**< Finite consumer-facing ranking score; larger/smaller policy is external. */
    double error_bound; /**< Finite nonnegative absolute acceleration error bound. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_motion_candidate_output_f64_t;

math_engine_motion_candidate_output_f64_t.struct_size
Exact byte size of this versioned output.
```
uint32_t struct_size;
```
math_engine_motion_candidate_output_f64_t.struct_version
MATH_ENGINE_MOTION_CANDIDATE_OUTPUT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_motion_candidate_output_f64_t.flags
Bitwise MATH_ENGINE_RESULT_FLAG_* status diagnostics.
```
uint32_t flags;
```
math_engine_motion_candidate_output_f64_t.kind
Candidate kind whose value this output carries.
```
uint32_t kind;
```
math_engine_motion_candidate_output_f64_t.frame_id
Nonzero frame of acceleration_mps2.
```
uint64_t frame_id;
```
math_engine_motion_candidate_output_f64_t.acceleration_mps2
Finite candidate acceleration in m/s^2.
```
math_engine_vec3_f64_t acceleration_mps2;
```
math_engine_motion_candidate_output_f64_t.score
Finite consumer-facing ranking score; larger/smaller policy is external.
```
double score;
```
math_engine_motion_candidate_output_f64_t.error_bound
Finite nonnegative absolute acceleration error bound.
```
double error_bound;
```
math_engine_motion_candidate_output_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

Macro와 constant

`MATH_ENGINE_AERODYNAMIC_INPUT_F64_VERSION_1`

Initial layout version for math_engine_aerodynamic_input_f64_t.

#define MATH_ENGINE_AERODYNAMIC_INPUT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MOTION_CANDIDATE_INPUT_F64_VERSION_1`

Initial layout version for math_engine_motion_candidate_input_f64_t.

#define MATH_ENGINE_MOTION_CANDIDATE_INPUT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MOTION_CANDIDATE_OUTPUT_F64_VERSION_1`

Initial layout version for math_engine_motion_candidate_output_f64_t.

#define MATH_ENGINE_MOTION_CANDIDATE_OUTPUT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MOTION_MODEL_RESULT_F64_VERSION_1`

Initial layout version for math_engine_motion_model_result_f64_t.

#define MATH_ENGINE_MOTION_MODEL_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MOTION_RESULT_F64_VERSION_1`

Initial layout version for math_engine_motion_result_f64_t.

#define MATH_ENGINE_MOTION_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MOTION_STATE_F64_VERSION_1`

Initial layout version for math_engine_motion_state_f64_t.

#define MATH_ENGINE_MOTION_STATE_F64_VERSION_1 UINT32_C(1)

Function

`math_engine_motion_state_f64_init`

Motion state를 지정 frame의 zero/identity SI 값으로 초기화한다.

매개변수 frame_id: 0이 아닌 caller-defined frame 식별자.
매개변수 out_state: 초기화할 caller-owned storage.
반환: 성공 또는 오류 status. 실패 시 output을 보존한다.
Math Engine ownership: out_state=caller
Math Engine nullable: out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_state_f64_init(
    uint64_t frame_id,
    math_engine_motion_state_f64_t* out_state);

`math_engine_motion_state_f64_validate`

Motion state의 version, SI unit, frame, finite 값과 unit quaternion을 검증한다.

매개변수 state: 검증할 borrowed motion state.
매개변수 context: quaternion unit-length와 finite 판정 tolerance를 제공하는 borrowed context.
반환: 모든 ABI·단위·frame·수치 조건을 만족하면 OK, 아니면 해당 음수 상태 code다.
Math Engine ownership: state=borrowed context=borrowed
Math Engine nullable: state=false context=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_state_f64_validate(
    const math_engine_motion_state_f64_t* state,
    const math_engine_context_t* context);

`math_engine_motion_result_f64_init`

Kinematics result storage를 version 1 empty 값으로 초기화한다.

매개변수 out_result: 초기화할 caller-owned result storage.
반환: 유효한 storage면 OK, null이면 INVALID_ARGUMENT이며 실패하면 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_result_f64_init(
    math_engine_motion_result_f64_t* out_result);

`math_engine_motion_linear_evaluate_f64`

상수 linear acceleration로 local interval 뒤 position과 velocity를 평가한다.

매개변수 state: 동일 frame의 초기 position·velocity·acceleration을 담은 borrowed state.
매개변수 local_interval_seconds: 0 이상의 finite local time interval(s).
매개변수 context: mode와 quaternion 검증 tolerance를 제공하는 borrowed context.
매개변수 out_result: 성공 시 전진된 state·residual·quality를 받는 caller-owned result.
반환: 유효한 state와 interval이면 OK, overflow·non-finite·ABI 오류는 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.

Angular fields와 orientation은 변경하지 않는다. Rigid attitude integration은 별도 integrator 계약의 책임이다. local_interval_seconds 는 finite이고 0 이상이어야 한다.

Math Engine ownership: state=borrowed context=borrowed out_result=caller
Math Engine nullable: state=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_linear_evaluate_f64(
    const math_engine_motion_state_f64_t* state,
    double local_interval_seconds,
    const math_engine_context_t* context,
    math_engine_motion_result_f64_t* out_result);

`math_engine_motion_relative_linear_f64`

같은 frame의 두 state를 같은 local interval에 평가한 subject-reference 값을 구한다.

매개변수 subject: 상대값의 피감수인 borrowed motion state.
매개변수 reference: 상대값의 기준인 borrowed motion state.
매개변수 local_interval_seconds: 두 state에 동일하게 적용할 0 이상의 finite interval(s).
매개변수 context: mode와 quaternion 검증 tolerance를 제공하는 borrowed context.
매개변수 out_result: 성공 시 relative position·velocity·acceleration state를 받는 output.
반환: Unit 또는 frame이 다르면 INVALID_ARGUMENT다. 실패 시 output을 보존한다.
Math Engine ownership: subject=borrowed reference=borrowed context=borrowed out_result=caller
Math Engine nullable: subject=false reference=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_relative_linear_f64(
    const math_engine_motion_state_f64_t* subject,
    const math_engine_motion_state_f64_t* reference,
    double local_interval_seconds,
    const math_engine_context_t* context,
    math_engine_motion_result_f64_t* out_result);

`math_engine_aerodynamic_input_f64_init`

Aerodynamic 입력 storage를 지정 frame의 SI version 1 값으로 초기화한다.

매개변수 frame_id: 0이 아닌 caller-defined coordinate frame ID.
매개변수 out_input: 초기화할 caller-owned aerodynamic input storage.
반환: frame과 storage가 유효하면 OK, 아니면 해당 음수 상태 code이며 실패하면 output을 보존한다.
Math Engine ownership: out_input=caller
Math Engine nullable: out_input=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_aerodynamic_input_f64_init(
    uint64_t frame_id,
    math_engine_aerodynamic_input_f64_t* out_input);

`math_engine_motion_model_result_f64_init`

Motion model result storage를 version 1 empty 값으로 초기화한다.

매개변수 out_result: 초기화할 caller-owned model result storage.
반환: 유효한 storage면 OK, null이면 INVALID_ARGUMENT이며 실패하면 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_model_result_f64_init(
    math_engine_motion_model_result_f64_t* out_result);

`math_engine_motion_aerodynamic_load_f64`

Quadratic drag, lift와 Magnus force를 합성하되 외부 gravity는 건드리지 않는다.

매개변수 input: flow·spin·물성·계수와 frame을 명시한 borrowed aerodynamic input.
매개변수 context: mode와 직교/zero-speed tolerance를 제공하는 borrowed context.
매개변수 out_result: 성공 시 force(N), acceleration(m/s^2)과 provenance를 받는 output.
반환: 유효한 SI 입력과 지원 mode면 OK, 음수 물성·non-finite·퇴화 lift 방향은 해당 음수 상태 code이며 실패하면 output을 보존한다.

Drag는 relative flow를 반대하고 lift는 flow에 수직이며 Magnus는 rho*A*L*C_m*(omega x v) 다. 모든 계수와 body/fluid 물성은 explicit input이다.

Math Engine ownership: input=borrowed context=borrowed out_result=caller
Math Engine nullable: input=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_aerodynamic_load_f64(
    const math_engine_aerodynamic_input_f64_t* input,
    const math_engine_context_t* context,
    math_engine_motion_model_result_f64_t* out_result);

`math_engine_motion_spin_decay_f64`

omega(t)=omega(0)*exp(-rate*t) spin decay를 local interval에 평가한다.

매개변수 angular_velocity_radps: 초기 right-hand angular velocity(rad/s).
매개변수 decay_rate_per_second: 0 이상의 exponential decay rate(1/s).
매개변수 local_interval_seconds: 0 이상의 finite local interval(s).
매개변수 frame_id: 0이 아닌 coordinate frame ID.
매개변수 context: mode와 exponential 평가 quality를 제공하는 borrowed context.
매개변수 out_result: 성공 시 감쇠된 angular velocity와 retention을 받는 output.
반환: finite 비음수 parameter와 유효한 frame이면 OK, 아니면 해당 음수 상태 code이며 실패하면 output을 보존한다.

time 0에서도 Magnus와 무관하게 입력 spin을 그대로 반환한다. Rate 단위는 1/s다.

Math Engine ownership: angular_velocity_radps=borrowed context=borrowed out_result=caller
Math Engine nullable: angular_velocity_radps=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_spin_decay_f64(
    const math_engine_vec3_f64_t* angular_velocity_radps,
    double decay_rate_per_second,
    double local_interval_seconds,
    uint64_t frame_id,
    const math_engine_context_t* context,
    math_engine_motion_model_result_f64_t* out_result);

`math_engine_motion_legacy_spin_drag_scale_f64`

Legacy spin/alignment drag 곡선을 explicit parameter로만 평가한다.

매개변수 spin_radps: right-hand spin vector(rad/s).
매개변수 velocity_mps: 같은 frame의 linear velocity(m/s).
매개변수 max_effective_spin_radps: curve가 clamp하는 양의 spin 크기(rad/s).
매개변수 max_reduction: 정렬 시 적용 가능한 0 이상 감소량.
매개변수 max_penalty: 역정렬 시 적용 가능한 0 이상 penalty.
매개변수 minimum_scale: 출력 scale의 finite 하한.
매개변수 maximum_scale: 출력 scale의 finite 상한이며 하한 이상이어야 한다.
매개변수 frame_id: 0이 아닌 coordinate frame ID.
매개변수 context: zero-speed tolerance와 mode를 제공하는 borrowed context.
매개변수 out_result: 성공 시 empirical scale과 error bound를 받는 caller-owned output.
반환: parameter 범위가 유효하면 OK, 아니면 해당 음수 상태 code이며 실패하면 output을 보존한다.

이 함수는 보편 물리 법칙이 아니며 결과 quality는 항상 EMPIRICAL_BOUNDED이고 UNCERTAIN flag를 갖는다. max_effective_spin, reduction, penalty와 output clamp를 caller가 명시한다.

Math Engine ownership: spin_radps=borrowed velocity_mps=borrowed context=borrowed out_result=caller
Math Engine nullable: spin_radps=false velocity_mps=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_legacy_spin_drag_scale_f64(
    const math_engine_vec3_f64_t* spin_radps,
    const math_engine_vec3_f64_t* velocity_mps,
    double max_effective_spin_radps,
    double max_reduction,
    double max_penalty,
    double minimum_scale,
    double maximum_scale,
    uint64_t frame_id,
    const math_engine_context_t* context,
    math_engine_motion_model_result_f64_t* out_result);

`math_engine_motion_candidate_input_f64_init`

Candidate input을 kind와 frame이 지정된 zero SI 값으로 초기화한다.

매개변수 kind: 초기화할 안정된 candidate kernel kind.
매개변수 frame_id: 0이 아닌 caller-defined coordinate frame ID.
매개변수 out_input: 초기화할 caller-owned candidate input storage.
반환: kind, frame과 storage가 유효하면 OK, 아니면 해당 음수 상태 code이며 실패하면 output을 보존한다.
Math Engine ownership: out_input=caller
Math Engine nullable: out_input=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_candidate_input_f64_init(
    math_engine_motion_candidate_kind_t kind,
    uint64_t frame_id,
    math_engine_motion_candidate_input_f64_t* out_input);

`math_engine_motion_candidate_input_f64_validate`

Candidate input의 version, unit, frame, finite 값과 parameter 범위를 검증한다.

매개변수 input: 검증할 borrowed entity-free candidate DTO.
반환: ABI·SI·frame·kind·parameter 계약을 모두 만족하면 OK, 아니면 해당 음수 상태 code다.
Math Engine ownership: input=borrowed
Math Engine nullable: input=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_candidate_input_f64_validate(
    const math_engine_motion_candidate_input_f64_t* input);

`math_engine_motion_candidate_output_f64_init`

Candidate output을 kind와 frame이 지정된 empty 값으로 초기화한다.

매개변수 kind: output이 대응할 안정된 candidate kernel kind.
매개변수 frame_id: 0이 아닌 caller-defined coordinate frame ID.
매개변수 out_output: 초기화할 caller-owned candidate output storage.
반환: kind, frame과 storage가 유효하면 OK, 아니면 해당 음수 상태 code이며 실패하면 output을 보존한다.
Math Engine ownership: out_output=caller
Math Engine nullable: out_output=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_motion_candidate_output_f64_init(
    math_engine_motion_candidate_kind_t kind,
    uint64_t frame_id,
    math_engine_motion_candidate_output_f64_t* out_output);

Math Engine Reference: Motion

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_motion_unit_system_t

math_engine_motion_model_id_t

math_engine_motion_quality_t

math_engine_motion_state_f64_t

math_engine_motion_result_f64_t

math_engine_aerodynamic_input_f64_t

math_engine_motion_model_result_f64_t

math_engine_motion_candidate_kind_t

math_engine_motion_candidate_input_f64_t

math_engine_motion_candidate_output_f64_t

Macro와 constant

MATH_ENGINE_AERODYNAMIC_INPUT_F64_VERSION_1

MATH_ENGINE_MOTION_CANDIDATE_INPUT_F64_VERSION_1

MATH_ENGINE_MOTION_CANDIDATE_OUTPUT_F64_VERSION_1

MATH_ENGINE_MOTION_MODEL_RESULT_F64_VERSION_1

MATH_ENGINE_MOTION_RESULT_F64_VERSION_1

MATH_ENGINE_MOTION_STATE_F64_VERSION_1

Function

math_engine_motion_state_f64_init

math_engine_motion_state_f64_validate

math_engine_motion_result_f64_init

math_engine_motion_linear_evaluate_f64

math_engine_motion_relative_linear_f64

math_engine_aerodynamic_input_f64_init

math_engine_motion_model_result_f64_init

math_engine_motion_aerodynamic_load_f64

math_engine_motion_spin_decay_f64

math_engine_motion_legacy_spin_drag_scale_f64

math_engine_motion_candidate_input_f64_init

math_engine_motion_candidate_input_f64_validate

math_engine_motion_candidate_output_f64_init