Search documentation of bb

# BB.Robot.Units (bb v0.17.0)

Copy Markdown View Source

Unit conversion functions for transforming `Localize.Unit` values into base SI floats.

All functions in this module convert from `Localize.Unit.t()` structs to native floats in SI base units, suitable for efficient numerical computation.

## Summary

### Functions

extract_float(unit)

Extract the numeric value from a `Localize.Unit` as a float.

to_kilogram_square_meters(unit)

Convert a moment of inertia unit to kg·m² (float).

to_kilogram_square_meters_or_nil(unit)
to_kilograms(unit)

Convert a mass unit to kilograms (float).

to_kilograms_or_nil(unit)
to_linear_damping(unit)

Convert a linear damping coefficient to N·s/m (float).

to_linear_damping_or_nil(unit)
to_meters(unit)

Convert a length unit to meters (float).

to_meters_or_nil(unit)

Convert an optional unit value to its base SI float, or return nil.

to_meters_per_second(unit)

Convert a linear velocity unit to meters per second (float).

to_meters_per_second_or_nil(unit)
to_meters_per_square_second(unit)

Convert a linear acceleration unit to metres per second squared (float).

to_meters_per_square_second_or_nil(unit)
to_newton(unit)

Convert a force unit to newtons (float).

to_newton_meters(unit)

Convert a torque unit to newton-meters (float).

to_newton_meters_or_nil(unit)
to_newtons(unit)

Convert a force unit to newtons (float).

to_newtons_or_nil(unit)
to_radians(unit)

Convert an angle unit to radians (float).

to_radians_or_nil(unit)
to_radians_per_second(unit)

Convert an angular velocity unit to radians per second (float).

to_radians_per_second_or_nil(unit)
to_radians_per_square_second(unit)

Convert an angular acceleration unit to radians per second squared (float).

to_radians_per_square_second_or_nil(unit)
to_rotational_damping(unit)

Convert a rotational damping coefficient to N·m·s/rad (float).

to_rotational_damping_or_nil(unit)

## Functions

# extract_float(unit)

    @spec extract_float(Localize.Unit.t()) :: float()

Extract the numeric value from a `Localize.Unit` as a float.

Handles integer, float, and `Decimal` values.

# to_kilogram_square_meters(unit)

    @spec to_kilogram_square_meters(Localize.Unit.t()) :: float()

Convert a moment of inertia unit to kg·m² (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilogram_square_meters(~u(0.5 kilogram_square_meter))
    0.5

# to_kilogram_square_meters_or_nil(unit)

    @spec to_kilogram_square_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_kilograms(unit)

    @spec to_kilograms(Localize.Unit.t()) :: float()

Convert a mass unit to kilograms (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilograms(~u(1000 gram))
    1.0

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilograms(~u(2.5 kilogram))
    2.5

# to_kilograms_or_nil(unit)

    @spec to_kilograms_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_linear_damping(unit)

    @spec to_linear_damping(Localize.Unit.t()) :: float()

Convert a linear damping coefficient to N·s/m (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_linear_damping(~u(1.5 newton_second_per_meter))
    1.5

# to_linear_damping_or_nil(unit)

    @spec to_linear_damping_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_meters(unit)

    @spec to_meters(Localize.Unit.t()) :: float()

Convert a length unit to meters (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters(~u(100 centimeter))
    1.0

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters(~u(1.5 meter))
    1.5

# to_meters_or_nil(unit)

    @spec to_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil

Convert an optional unit value to its base SI float, or return nil.

# to_meters_per_second(unit)

    @spec to_meters_per_second(Localize.Unit.t()) :: float()

Convert a linear velocity unit to meters per second (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters_per_second(~u(10 meter_per_second))
    10.0

# to_meters_per_second_or_nil(unit)

    @spec to_meters_per_second_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_meters_per_square_second(unit)

    @spec to_meters_per_square_second(Localize.Unit.t()) :: float()

Convert a linear acceleration unit to metres per second squared (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters_per_square_second(~u(9.81 meter_per_square_second))
    9.81

# to_meters_per_square_second_or_nil(unit)

    @spec to_meters_per_square_second_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_newton(unit)

    @spec to_newton(Localize.Unit.t()) :: float()

Convert a force unit to newtons (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newton(~u(5 newton))
    5.0

# to_newton_meters(unit)

    @spec to_newton_meters(Localize.Unit.t()) :: float()

Convert a torque unit to newton-meters (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newton_meters(~u(5 newton_meter))
    5.0

# to_newton_meters_or_nil(unit)

    @spec to_newton_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_newtons(unit)

    @spec to_newtons(Localize.Unit.t()) :: float()

Convert a force unit to newtons (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newtons(~u(10 newton))
    10.0

# to_newtons_or_nil(unit)

    @spec to_newtons_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_radians(unit)

    @spec to_radians(Localize.Unit.t()) :: float()

Convert an angle unit to radians (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians(~u(180 degree))
    :math.pi()

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians(~u(0 degree))
    0.0

# to_radians_or_nil(unit)

    @spec to_radians_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_radians_per_second(unit)

    @spec to_radians_per_second(Localize.Unit.t()) :: float()

Convert an angular velocity unit to radians per second (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians_per_second(~u(180 degree_per_second))
    :math.pi()

# to_radians_per_second_or_nil(unit)

    @spec to_radians_per_second_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_radians_per_square_second(unit)

    @spec to_radians_per_square_second(Localize.Unit.t()) :: float()

Convert an angular acceleration unit to radians per second squared (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians_per_square_second(~u(360 degree_per_square_second))
    :math.pi() * 2

# to_radians_per_square_second_or_nil(unit)

    @spec to_radians_per_square_second_or_nil(Localize.Unit.t() | nil) :: float() | nil

# to_rotational_damping(unit)

    @spec to_rotational_damping(Localize.Unit.t()) :: float()

Convert a rotational damping coefficient to N·m·s/rad (float).

Note: The DSL uses `newton_meter_second_per_degree` but we convert to radians for consistency with other angular quantities.

# to_rotational_damping_or_nil(unit)

    @spec to_rotational_damping_or_nil(Localize.Unit.t() | nil) :: float() | nil