3D vector utility used throughout JSim physics. More...

#include <vector.hpp>

Classes
struct	DragVector
	Directional drag force vector and validity metadata. More...
struct	DragForceDetails
	Expanded drag diagnostics for force computation. More...

Public Member Functions
constexpr	Vector3 () noexcept
	Constructs a zero vector.
constexpr	Vector3 (double x_, double y_, double z_) noexcept
	Constructs a vector from component values.
constexpr	Vector3 (const Vector3 &) noexcept=default
constexpr	Vector3 (Vector3 &&) noexcept=default
constexpr Vector3 &	operator= (const Vector3 &) noexcept=default
constexpr Vector3 &	operator= (Vector3 &&) noexcept=default
constexpr Vector3	operator+ (const Vector3 &o) const noexcept
	Returns component-wise sum.
constexpr Vector3	operator- (const Vector3 &o) const noexcept
	Returns component-wise difference.
constexpr Vector3	operator* (double s) const noexcept
	Returns this vector scaled by a scalar.
constexpr Vector3	operator/ (double s) const noexcept
	Returns this vector divided by a scalar.
Vector3 &	operator+= (const Vector3 &o) noexcept
	Adds o component-wise into this vector.
Vector3 &	operator-= (const Vector3 &o) noexcept
	Subtracts o component-wise from this vector.
Vector3 &	operator*= (double s) noexcept
	Multiplies each component by s.
Vector3 &	operator/= (double s) noexcept
	Divides each component by s.
constexpr bool	operator== (const Vector3 &o) const noexcept
	Exact component-wise equality comparison.
constexpr bool	operator!= (const Vector3 &o) const noexcept
	Exact component-wise inequality comparison.
constexpr double	norm2 () const noexcept
	Returns squared magnitude: $x^2+y^2+z^2$.
double	norm () const noexcept
	Returns Euclidean magnitude.
Vector3	normalized () const noexcept
	Returns the normalized direction vector.
constexpr bool	isZero (double eps=1e-12) const noexcept
	Checks whether the vector is near zero magnitude.
bool	hasNaN () const noexcept
	Returns true when any component is NaN.
void	toArray (double arr[3]) const noexcept
	Writes components to a 3-element array.
Vector3	clamp (const Vector3 &min, const Vector3 &max) const noexcept
	Clamps each component into the inclusive [min, max] range.
constexpr double	dot (const Vector3 &o) const noexcept
	Returns dot product with o.
Vector3	cross (const Vector3 &o) const noexcept
	Returns cross product with o.
double	planarSpeed () const noexcept
	Returns magnitude of the XY projection.
constexpr Vector3	xy () const noexcept
	Returns this vector projected onto the XY plane (z=0).
Vector3	planarDir () const noexcept
	Returns normalized XY direction with z=0.
Vector3	projectOnto (const Vector3 &axis) const noexcept
	Projects this vector onto another axis.
Vector3	reflect (const Vector3 &n) const noexcept
	Reflects this vector across a normalized plane normal.
Vector3	torque (const Vector3 &r) const noexcept
	Computes torque from a force applied at offset r.
constexpr Vector3	operator- () const noexcept
	Returns the additive inverse of this vector.
double &	operator[] (size_t i)
	Returns a mutable component by index.
const double &	operator[] (size_t i) const
	Returns a const component by index.

Static Public Member Functions
static Vector3	fromArray (const double arr[3]) noexcept
	Builds a vector from a 3-element array.
static double	distance (const Vector3 &a, const Vector3 &b) noexcept
	Returns Euclidean distance between two vectors treated as points.
static Vector3	lerp (const Vector3 &a, const Vector3 &b, double t) noexcept
	Linearly interpolates from a to b.
static Vector3	magnusForce (const Vector3 &velocity, const Vector3 &omega, double k=1e-4) noexcept
	Computes the Magnus lift force omega x v scaled by k.
static DragForceDetails	dragForceDetailed (const Vector3 &v, double Cd, double A, double rho=1.225, double linear_drag_coefficient_n_per_mps=0.0) noexcept
	Computes drag force details for a body moving through air.
static Vector3	dragForce (const Vector3 &v, double Cd, double A, double rho=1.225) noexcept
	Computes the total drag force vector for a velocity and body.
static Vector3	dynamicGravity (const Vector3 &velocity, const Vector3 &spin, double g=9.81, double magnusCoeff=1e-4, double gravityEffect=1.0) noexcept
	Combines gravity with an optional Magnus lift contribution.
static constexpr Vector3	zero () noexcept
	Returns the zero vector.
static constexpr Vector3	unitX () noexcept
	Returns the +X basis vector.
static constexpr Vector3	unitY () noexcept
	Returns the +Y basis vector.
static constexpr Vector3	unitZ () noexcept
	Returns the +Z basis vector.
static Vector3	tractionForce (const Vector3 &normal, double frictionCoeff, double normalForce) noexcept
	Computes a traction/friction force aligned with the supplied normal.

Public Attributes
double	x
	X component.
double	y
	Y component.
double	z
	Z component.

Friends
std::ostream &	operator<< (std::ostream &os, const Vector3 &v)
	Streams the vector in a fixed-width bracketed format.

Detailed Description

3D vector utility used throughout JSim physics.

This type stores Cartesian coordinates in SI units when used with simulation state (meters, meters/second, radians/second, newtons, etc.). The math helpers are unit-agnostic, but callers should keep units consistent.

Constructor & Destructor Documentation

◆ Vector3() [1/4]

frcsim::Vector3::Vector3 ( )

inlineconstexprnoexcept

Constructs a zero vector.

◆ Vector3() [2/4]

frcsim::Vector3::Vector3	(	double	x_,
		double	y_,
		double	z_ )

inlineconstexprnoexcept

Constructs a vector from component values.

Parameters

x_	X component.
y_	Y component.
z_	Z component.

◆ Vector3() [3/4]

frcsim::Vector3::Vector3 ( const Vector3 & )

constexprdefaultnoexcept

◆ Vector3() [4/4]

frcsim::Vector3::Vector3 ( Vector3 && )

constexprdefaultnoexcept

Member Function Documentation

◆ clamp()

Vector3 frcsim::Vector3::clamp	(	const Vector3 &	min,
		const Vector3 &	max ) const

inlinenoexcept

Clamps each component into the inclusive [min, max] range.

◆ cross()

Vector3 frcsim::Vector3::cross ( const Vector3 & o ) const

inlinenoexcept

Returns cross product with o.

◆ distance()

double frcsim::Vector3::distance	(	const Vector3 &	a,
		const Vector3 &	b )

inlinestaticnoexcept

Returns Euclidean distance between two vectors treated as points.

◆ dot()

double frcsim::Vector3::dot ( const Vector3 & o ) const

inlineconstexprnoexcept

Returns dot product with o.

◆ dragForce()

Vector3 frcsim::Vector3::dragForce	(	const Vector3 &	v,
		double	Cd,
		double	A,
		double	rho = 1.225 )

inlinestaticnoexcept

Computes the total drag force vector for a velocity and body.

Parameters

v	Body velocity in meters per second.
Cd	Drag coefficient.
A	Reference area in square meters.
rho	Air density in kilograms per cubic meter.

Returns: Drag force vector in newtons.

◆ dragForceDetailed()

DragForceDetails frcsim::Vector3::dragForceDetailed	(	const Vector3 &	v,
		double	Cd,
		double	A,
		double	rho = 1.225,
		double	linear_drag_coefficient_n_per_mps = 0.0 )

inlinestaticnoexcept

Computes drag force details for a body moving through air.

Parameters

v	Body velocity in meters per second.
Cd	Drag coefficient.
A	Reference area in square meters.
rho	Air density in kilograms per cubic meter.
linear_drag_coefficient_n_per_mps	Optional linear drag term.

Returns: Detailed drag force breakdown and validity state.

◆ dynamicGravity()

Vector3 frcsim::Vector3::dynamicGravity	(	const Vector3 &	velocity,
		const Vector3 &	spin,
		double	g = 9.81,
		double	magnusCoeff = 1e-4,
		double	gravityEffect = 1.0 )

inlinestaticnoexcept

Combines gravity with an optional Magnus lift contribution.

Parameters

velocity	Object velocity in meters per second.
spin	Angular velocity in radians per second.
g	Gravity magnitude in meters per second squared.
magnusCoeff	Magnus coefficient applied to the lift term.
gravityEffect	Multiplier applied to the gravity vector.

Returns: Gravity plus Magnus acceleration expressed as a force-like vector.

◆ fromArray()

Vector3 frcsim::Vector3::fromArray ( const double arr[3] )

inlinestaticnoexcept

Builds a vector from a 3-element array.

◆ hasNaN()

bool frcsim::Vector3::hasNaN ( ) const

inlinenoexcept

Returns true when any component is NaN.

◆ isZero()

bool frcsim::Vector3::isZero ( double eps = 1e-12 ) const

inlineconstexprnoexcept

Checks whether the vector is near zero magnitude.

Parameters

eps	Absolute tolerance on magnitude.

◆ lerp()

Vector3 frcsim::Vector3::lerp	(	const Vector3 &	a,
		const Vector3 &	b,
		double	t )

inlinestaticnoexcept

Linearly interpolates from a to b.

Parameters

a	Start vector.
b	End vector.
t	Interpolation ratio where 0 is a and 1 is b.

◆ magnusForce()

Vector3 frcsim::Vector3::magnusForce	(	const Vector3 &	velocity,
		const Vector3 &	omega,
		double	k = 1e-4 )

inlinestaticnoexcept

Computes the Magnus lift force omega x v scaled by k.

Parameters

velocity	Linear velocity in meters per second.
omega	Angular velocity in radians per second.
k	Magnus coefficient in SI units.

Returns: Lift force vector in newtons.

◆ norm()

double frcsim::Vector3::norm ( ) const

inlinenoexcept

Returns Euclidean magnitude.

◆ norm2()

double frcsim::Vector3::norm2 ( ) const

inlineconstexprnoexcept

Returns squared magnitude: $x^2+y^2+z^2$.

◆ normalized()

Vector3 frcsim::Vector3::normalized ( ) const

inlinenoexcept

Returns the normalized direction vector.

Returns: Unit vector in the same direction, or zero for near-zero input.

◆ operator!=()

bool frcsim::Vector3::operator!= ( const Vector3 & o ) const

inlineconstexprnoexcept

Exact component-wise inequality comparison.

◆ operator*()

Vector3 frcsim::Vector3::operator* ( double s ) const

inlineconstexprnoexcept

Returns this vector scaled by a scalar.

◆ operator*=()

Vector3 & frcsim::Vector3::operator*= ( double s )

inlinenoexcept

Multiplies each component by s.

◆ operator+()

Vector3 frcsim::Vector3::operator+ ( const Vector3 & o ) const

inlineconstexprnoexcept

Returns component-wise sum.

◆ operator+=()

Vector3 & frcsim::Vector3::operator+= ( const Vector3 & o )

inlinenoexcept

Adds o component-wise into this vector.

◆ operator-() [1/2]

Vector3 frcsim::Vector3::operator- ( ) const

inlineconstexprnoexcept

Returns the additive inverse of this vector.

◆ operator-() [2/2]

Vector3 frcsim::Vector3::operator- ( const Vector3 & o ) const

inlineconstexprnoexcept

Returns component-wise difference.

◆ operator-=()

Vector3 & frcsim::Vector3::operator-= ( const Vector3 & o )

inlinenoexcept

Subtracts o component-wise from this vector.

◆ operator/()

Vector3 frcsim::Vector3::operator/ ( double s ) const

inlineconstexprnoexcept

Returns this vector divided by a scalar.

Note: Returns zero when s is effectively zero.

◆ operator/=()

Vector3 & frcsim::Vector3::operator/= ( double s )

inlinenoexcept

Divides each component by s.

Note: Sets the vector to zero when s is effectively zero.

◆ operator=() [1/2]

Vector3 & frcsim::Vector3::operator= ( const Vector3 & )

constexprdefaultnoexcept

◆ operator=() [2/2]

Vector3 & frcsim::Vector3::operator= ( Vector3 && )

constexprdefaultnoexcept

◆ operator==()

bool frcsim::Vector3::operator== ( const Vector3 & o ) const

inlineconstexprnoexcept

Exact component-wise equality comparison.

◆ operator[]() [1/2]

double & frcsim::Vector3::operator[] ( size_t i )

inline

Returns a mutable component by index.

Parameters

i	Component index: 0 for x, 1 for y, 2 for z.

Returns: Reference to the selected component.

◆ operator[]() [2/2]

const double & frcsim::Vector3::operator[] ( size_t i ) const

inline

Returns a const component by index.

Parameters

i	Component index: 0 for x, 1 for y, 2 for z.

Returns: Const reference to the selected component.

◆ planarDir()

Vector3 frcsim::Vector3::planarDir ( ) const

inlinenoexcept

Returns normalized XY direction with z=0.

Returns: Unit planar direction, or zero when planar magnitude is near zero.

◆ planarSpeed()

double frcsim::Vector3::planarSpeed ( ) const

inlinenoexcept

Returns magnitude of the XY projection.

◆ projectOnto()

Vector3 frcsim::Vector3::projectOnto ( const Vector3 & axis ) const

inlinenoexcept

Projects this vector onto another axis.

Parameters

axis	Axis to project onto.

Returns: Vector component of this vector along axis.

◆ reflect()

Vector3 frcsim::Vector3::reflect ( const Vector3 & n ) const

inlinenoexcept

Reflects this vector across a normalized plane normal.

Parameters

n	Unit normal of the reflection plane.

Returns: Reflected vector.

◆ toArray()

void frcsim::Vector3::toArray ( double arr[3] ) const

inlinenoexcept

Writes components to a 3-element array.

◆ torque()

Vector3 frcsim::Vector3::torque ( const Vector3 & r ) const

inlinenoexcept

Computes torque from a force applied at offset r.

Parameters

r	Lever arm from the reference point to the application point.

Returns: Torque vector r x F.

◆ tractionForce()

Vector3 frcsim::Vector3::tractionForce	(	const Vector3 &	normal,
		double	frictionCoeff,
		double	normalForce )

inlinestaticnoexcept

Computes a traction/friction force aligned with the supplied normal.

Parameters

normal	Contact normal direction (expected normalized).
frictionCoeff	Unitless friction coefficient.
normalForce	Normal force magnitude in newtons.

Returns: Traction vector in newtons.

◆ unitX()

constexpr Vector3 frcsim::Vector3::unitX ( )

inlinestaticconstexprnoexcept

Returns the +X basis vector.

◆ unitY()

constexpr Vector3 frcsim::Vector3::unitY ( )

inlinestaticconstexprnoexcept

Returns the +Y basis vector.

◆ unitZ()

constexpr Vector3 frcsim::Vector3::unitZ ( )

inlinestaticconstexprnoexcept

Returns the +Z basis vector.

◆ xy()

Vector3 frcsim::Vector3::xy ( ) const

inlineconstexprnoexcept

Returns this vector projected onto the XY plane (z=0).

◆ zero()

constexpr Vector3 frcsim::Vector3::zero ( )

inlinestaticconstexprnoexcept

Returns the zero vector.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Vector3 &	v )

friend

Streams the vector in a fixed-width bracketed format.

Member Data Documentation

◆ x

double frcsim::Vector3::x

X component.

Examples: /home/runner/work/JSim/JSim/vendordep/src/main/driver/include/frcsim/field/goal_structure.hpp.

◆ y

double frcsim::Vector3::y

Y component.

Examples: /home/runner/work/JSim/JSim/vendordep/src/main/driver/include/frcsim/field/goal_structure.hpp.

◆ z

double frcsim::Vector3::z

Z component.

Examples: /home/runner/work/JSim/JSim/vendordep/src/main/driver/include/frcsim/field/goal_structure.hpp.

The documentation for this struct was generated from the following file:

src/main/driver/include/frcsim/math/vector.hpp

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Vector3() [1/4]

◆ Vector3() [2/4]

◆ Vector3() [3/4]

◆ Vector3() [4/4]

Member Function Documentation

◆ clamp()

◆ cross()

◆ distance()

◆ dot()

◆ dragForce()

◆ dragForceDetailed()

◆ dynamicGravity()

◆ fromArray()

◆ hasNaN()

◆ isZero()

◆ lerp()

◆ magnusForce()

◆ norm()

◆ norm2()

◆ normalized()

◆ operator!=()

◆ operator*()

◆ operator*=()

◆ operator+()

◆ operator+=()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator-=()

◆ operator/()

◆ operator/=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ planarDir()

◆ planarSpeed()

◆ projectOnto()

◆ reflect()

◆ toArray()

◆ torque()

◆ tractionForce()

◆ unitX()

◆ unitY()

◆ unitZ()

◆ xy()

◆ zero()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ x

◆ y

◆ z