[wpiunits] Add subproject for a Java typesafe unit system (#5371)
# Background
Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs.
Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so).
# API
There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class.
A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values.
A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)`
# Examples
These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model)
```java
// Using raw units
Encoder encoder = ...
int kPulsesPerRev = 2048;
double kWheelDiameterMeters = Units.inchesToMeters(6);
double kGearRatio = 10.86;
// always have to remember this encoder will output in meters!
encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev));
Command driveDistance(double distance) {
// have to know the distance argument needs to be in meters!
return run(this::driveStraight).until(() -> encoder.getDistance() >= distance);
}
// Oops! This will go 16 feet, not 5!
Command driveFiveFeet = driveDistance(5);
Command driveOneMeter = driveDistance(1);
```
```java
// Using wpiunits
Encoder encoder = ...
int kPulsesPerRev = 2048;
Measure<Distance> kWheelDiameter = Inches.of(6);
double kGearRatio = 10.86;
encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev));
Command driveDistance(Measure<Distance> distance) {
// Measure#gte automatically handles unit conversions
return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance));
}
// Users HAVE to be explicit about their units
Command driveFiveFeet = driveDistance(Feet.of(5));
Command driveOneMeter = driveDistance(Meters.of(1));
```
```java
SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius));
SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit));
```
```java
var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined
var InchPerSecond = Inch.per(Second);
PIDController<Distance, ElectricPotential> heightController = new PIDController<>(
/* kP */ Volts.of(0.2).per(Inch),
/* kI */ Volts.of(0.002).per(InchSecond),
/* kD */ Volts.of(0.008).per(InchPerSecond)
);
var elevatorTop = Feet.of(4).plus(Inches.of(6.125));
elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop));
```
2023-07-23 17:18:17 -04:00
|
|
|
// Copyright (c) FIRST and other WPILib contributors.
|
|
|
|
|
// Open Source Software; you can modify and/or share it under the terms of
|
|
|
|
|
// the WPILib BSD license file in the root directory of this project.
|
|
|
|
|
|
|
|
|
|
package edu.wpi.first.units;
|
|
|
|
|
|
|
|
|
|
import java.util.Objects;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A specialization of {@link Measure} that allows for mutability. This is intended to be used for
|
2023-11-23 12:57:58 -06:00
|
|
|
* memory use reasons (such as on the memory-restricted roboRIO 1 or 2 or SBC coprocessors) and
|
[wpiunits] Add subproject for a Java typesafe unit system (#5371)
# Background
Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs.
Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so).
# API
There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class.
A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values.
A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)`
# Examples
These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model)
```java
// Using raw units
Encoder encoder = ...
int kPulsesPerRev = 2048;
double kWheelDiameterMeters = Units.inchesToMeters(6);
double kGearRatio = 10.86;
// always have to remember this encoder will output in meters!
encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev));
Command driveDistance(double distance) {
// have to know the distance argument needs to be in meters!
return run(this::driveStraight).until(() -> encoder.getDistance() >= distance);
}
// Oops! This will go 16 feet, not 5!
Command driveFiveFeet = driveDistance(5);
Command driveOneMeter = driveDistance(1);
```
```java
// Using wpiunits
Encoder encoder = ...
int kPulsesPerRev = 2048;
Measure<Distance> kWheelDiameter = Inches.of(6);
double kGearRatio = 10.86;
encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev));
Command driveDistance(Measure<Distance> distance) {
// Measure#gte automatically handles unit conversions
return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance));
}
// Users HAVE to be explicit about their units
Command driveFiveFeet = driveDistance(Feet.of(5));
Command driveOneMeter = driveDistance(Meters.of(1));
```
```java
SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius));
SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit));
```
```java
var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined
var InchPerSecond = Inch.per(Second);
PIDController<Distance, ElectricPotential> heightController = new PIDController<>(
/* kP */ Volts.of(0.2).per(Inch),
/* kI */ Volts.of(0.002).per(InchSecond),
/* kD */ Volts.of(0.008).per(InchPerSecond)
);
var elevatorTop = Feet.of(4).plus(Inches.of(6.125));
elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop));
```
2023-07-23 17:18:17 -04:00
|
|
|
* should NOT be exposed in the public API for a class that uses it.
|
|
|
|
|
*
|
2023-11-23 12:57:58 -06:00
|
|
|
* <p>The advantage of using this class is to reuse one instance of a measurement object, as opposed
|
|
|
|
|
* to instantiating a new immutable instance every time an operation is performed. This will reduce
|
|
|
|
|
* memory pressure, but comes at the cost of increased code complexity and sensitivity to race
|
|
|
|
|
* conditions if misused.
|
[wpiunits] Add subproject for a Java typesafe unit system (#5371)
# Background
Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs.
Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so).
# API
There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class.
A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values.
A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)`
# Examples
These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model)
```java
// Using raw units
Encoder encoder = ...
int kPulsesPerRev = 2048;
double kWheelDiameterMeters = Units.inchesToMeters(6);
double kGearRatio = 10.86;
// always have to remember this encoder will output in meters!
encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev));
Command driveDistance(double distance) {
// have to know the distance argument needs to be in meters!
return run(this::driveStraight).until(() -> encoder.getDistance() >= distance);
}
// Oops! This will go 16 feet, not 5!
Command driveFiveFeet = driveDistance(5);
Command driveOneMeter = driveDistance(1);
```
```java
// Using wpiunits
Encoder encoder = ...
int kPulsesPerRev = 2048;
Measure<Distance> kWheelDiameter = Inches.of(6);
double kGearRatio = 10.86;
encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev));
Command driveDistance(Measure<Distance> distance) {
// Measure#gte automatically handles unit conversions
return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance));
}
// Users HAVE to be explicit about their units
Command driveFiveFeet = driveDistance(Feet.of(5));
Command driveOneMeter = driveDistance(Meters.of(1));
```
```java
SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius));
SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit));
```
```java
var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined
var InchPerSecond = Inch.per(Second);
PIDController<Distance, ElectricPotential> heightController = new PIDController<>(
/* kP */ Volts.of(0.2).per(Inch),
/* kI */ Volts.of(0.002).per(InchSecond),
/* kD */ Volts.of(0.008).per(InchPerSecond)
);
var elevatorTop = Feet.of(4).plus(Inches.of(6.125));
elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop));
```
2023-07-23 17:18:17 -04:00
|
|
|
*
|
|
|
|
|
* <p>Any unsafe methods are prefixed with {@code mut_*}, such as {@link #mut_plus(Measure)} or
|
|
|
|
|
* {@link #mut_replace(Measure)}. These methods will change the internal state of the measurement
|
|
|
|
|
* object, and as such can be dangerous to use. They are primarily intended for use to track
|
|
|
|
|
* internal state of things like sensors
|
|
|
|
|
*
|
|
|
|
|
* @param <U> the type of the unit of measure
|
|
|
|
|
*/
|
|
|
|
|
public final class MutableMeasure<U extends Unit<U>> implements Measure<U> {
|
|
|
|
|
private double m_magnitude;
|
|
|
|
|
private double m_baseUnitMagnitude;
|
|
|
|
|
private U m_unit;
|
|
|
|
|
|
|
|
|
|
private MutableMeasure(double initialMagnitude, double baseUnitMagnitude, U unit) {
|
|
|
|
|
m_magnitude = initialMagnitude;
|
|
|
|
|
m_baseUnitMagnitude = baseUnitMagnitude;
|
|
|
|
|
m_unit = unit;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Creates a new mutable measure that is a copy of the given one.
|
|
|
|
|
*
|
|
|
|
|
* @param <U> the type of the units of measure
|
|
|
|
|
* @param measure the measure to create a mutable copy of
|
|
|
|
|
* @return a new mutable measure with an initial state equal to the given measure
|
|
|
|
|
*/
|
|
|
|
|
public static <U extends Unit<U>> MutableMeasure<U> mutable(Measure<U> measure) {
|
|
|
|
|
return new MutableMeasure<>(measure.magnitude(), measure.baseUnitMagnitude(), measure.unit());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Creates a new mutable measure with a magnitude of 0 in the given unit.
|
|
|
|
|
*
|
|
|
|
|
* @param <U> the type of the units of measure
|
|
|
|
|
* @param unit the unit of measure
|
|
|
|
|
* @return a new mutable measure
|
|
|
|
|
*/
|
|
|
|
|
public static <U extends Unit<U>> MutableMeasure<U> zero(U unit) {
|
|
|
|
|
return mutable(unit.zero());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Creates a new mutable measure in the given unit with a magnitude equal to the given one in base
|
|
|
|
|
* units.
|
|
|
|
|
*
|
|
|
|
|
* @param <U> the type of the units of measure
|
|
|
|
|
* @param baseUnitMagnitude the magnitude of the measure, in terms of the base unit of measure
|
|
|
|
|
* @param unit the unit of measure
|
|
|
|
|
* @return a new mutable measure
|
|
|
|
|
*/
|
|
|
|
|
public static <U extends Unit<U>> MutableMeasure<U> ofBaseUnits(
|
|
|
|
|
double baseUnitMagnitude, U unit) {
|
|
|
|
|
return new MutableMeasure<>(unit.fromBaseUnits(baseUnitMagnitude), baseUnitMagnitude, unit);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Creates a new mutable measure in the given unit with a magnitude in terms of that unit.
|
|
|
|
|
*
|
|
|
|
|
* @param <U> the type of the units of measure
|
|
|
|
|
* @param relativeMagnitude the magnitude of the measure
|
|
|
|
|
* @param unit the unit of measure
|
|
|
|
|
* @return a new mutable measure
|
|
|
|
|
*/
|
|
|
|
|
public static <U extends Unit<U>> MutableMeasure<U> ofRelativeUnits(
|
|
|
|
|
double relativeMagnitude, U unit) {
|
|
|
|
|
return new MutableMeasure<>(relativeMagnitude, unit.toBaseUnits(relativeMagnitude), unit);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public double magnitude() {
|
|
|
|
|
return m_magnitude;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public double baseUnitMagnitude() {
|
|
|
|
|
return m_baseUnitMagnitude;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public U unit() {
|
|
|
|
|
return m_unit;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// UNSAFE
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Sets the new magnitude of the measurement. The magnitude must be in terms of the {@link
|
|
|
|
|
* #unit()}.
|
|
|
|
|
*
|
|
|
|
|
* @param magnitude the new magnitude of the measurement
|
|
|
|
|
*/
|
|
|
|
|
public void mut_setMagnitude(double magnitude) {
|
|
|
|
|
m_magnitude = magnitude;
|
|
|
|
|
m_baseUnitMagnitude = m_unit.toBaseUnits(magnitude);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Sets the new magnitude of the measurement. The magnitude must be in terms of the base unit of
|
|
|
|
|
* the current unit.
|
|
|
|
|
*
|
|
|
|
|
* @param baseUnitMagnitude the new magnitude of the measurement
|
|
|
|
|
*/
|
|
|
|
|
public void mut_setBaseUnitMagnitude(double baseUnitMagnitude) {
|
|
|
|
|
m_baseUnitMagnitude = baseUnitMagnitude;
|
|
|
|
|
m_magnitude = m_unit.fromBaseUnits(baseUnitMagnitude);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Overwrites the state of this measure and replaces it with values from the given one.
|
|
|
|
|
*
|
|
|
|
|
* @param other the other measure to copy values from
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_replace(Measure<U> other) {
|
|
|
|
|
m_magnitude = other.magnitude();
|
|
|
|
|
m_baseUnitMagnitude = other.baseUnitMagnitude();
|
|
|
|
|
m_unit = other.unit();
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Overwrites the state of this measure with new values.
|
|
|
|
|
*
|
|
|
|
|
* @param magnitude the new magnitude in terms of the new unit
|
|
|
|
|
* @param unit the new unit
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_replace(double magnitude, U unit) {
|
|
|
|
|
this.m_magnitude = magnitude;
|
|
|
|
|
this.m_baseUnitMagnitude = unit.toBaseUnits(magnitude);
|
|
|
|
|
this.m_unit = unit;
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Increments the current magnitude of the measure by the given value. The value must be in terms
|
|
|
|
|
* of the current {@link #unit() unit}.
|
|
|
|
|
*
|
|
|
|
|
* @param raw the raw value to accumulate by
|
|
|
|
|
* @return the measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_acc(double raw) {
|
|
|
|
|
this.m_magnitude += raw;
|
|
|
|
|
this.m_baseUnitMagnitude += m_unit.toBaseUnits(raw);
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Increments the current magnitude of the measure by the amount of the given measure.
|
|
|
|
|
*
|
|
|
|
|
* @param other the measure whose value should be added to this one
|
|
|
|
|
* @return the measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_acc(Measure<U> other) {
|
|
|
|
|
m_baseUnitMagnitude += other.baseUnitMagnitude();
|
|
|
|
|
|
|
|
|
|
// can't naively use m_magnitude += other.in(m_unit) because the units may not
|
|
|
|
|
// be scalar multiples (eg adding 0C to 100K should result in 373.15K, not 100K)
|
|
|
|
|
m_magnitude = m_unit.fromBaseUnits(m_baseUnitMagnitude);
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Math
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Adds another measurement to this one. This will mutate the object instead of generating a new
|
|
|
|
|
* measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param other the measurement to add
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_plus(Measure<U> other) {
|
|
|
|
|
return mut_plus(other.magnitude(), other.unit());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Adds another measurement to this one. This will mutate the object instead of generating a new
|
|
|
|
|
* measurement object. This is a denormalized version of {@link #mut_plus(Measure)} to avoid
|
|
|
|
|
* having to wrap raw numbers in a {@code Measure} object and pay for an object allocation.
|
|
|
|
|
*
|
|
|
|
|
* @param magnitude the magnitude of the other measurement.
|
|
|
|
|
* @param unit the unit of the other measurement
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_plus(double magnitude, U unit) {
|
|
|
|
|
mut_setBaseUnitMagnitude(m_baseUnitMagnitude + unit.toBaseUnits(magnitude));
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Subtracts another measurement to this one. This will mutate the object instead of generating a
|
|
|
|
|
* new measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param other the measurement to add
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_minus(Measure<U> other) {
|
|
|
|
|
return mut_minus(other.magnitude(), other.unit());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Subtracts another measurement to this one. This will mutate the object instead of generating a
|
|
|
|
|
* new measurement object. This is a denormalized version of {@link #mut_minus(Measure)} to avoid
|
|
|
|
|
* having to wrap raw numbers in a {@code Measure} object and pay for an object allocation.
|
|
|
|
|
*
|
|
|
|
|
* @param magnitude the magnitude of the other measurement.
|
2023-10-20 18:14:14 -07:00
|
|
|
* @param unit the unit of the other measurement
|
[wpiunits] Add subproject for a Java typesafe unit system (#5371)
# Background
Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs.
Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so).
# API
There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class.
A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values.
A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)`
# Examples
These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model)
```java
// Using raw units
Encoder encoder = ...
int kPulsesPerRev = 2048;
double kWheelDiameterMeters = Units.inchesToMeters(6);
double kGearRatio = 10.86;
// always have to remember this encoder will output in meters!
encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev));
Command driveDistance(double distance) {
// have to know the distance argument needs to be in meters!
return run(this::driveStraight).until(() -> encoder.getDistance() >= distance);
}
// Oops! This will go 16 feet, not 5!
Command driveFiveFeet = driveDistance(5);
Command driveOneMeter = driveDistance(1);
```
```java
// Using wpiunits
Encoder encoder = ...
int kPulsesPerRev = 2048;
Measure<Distance> kWheelDiameter = Inches.of(6);
double kGearRatio = 10.86;
encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev));
Command driveDistance(Measure<Distance> distance) {
// Measure#gte automatically handles unit conversions
return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance));
}
// Users HAVE to be explicit about their units
Command driveFiveFeet = driveDistance(Feet.of(5));
Command driveOneMeter = driveDistance(Meters.of(1));
```
```java
SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius));
SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit));
```
```java
var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined
var InchPerSecond = Inch.per(Second);
PIDController<Distance, ElectricPotential> heightController = new PIDController<>(
/* kP */ Volts.of(0.2).per(Inch),
/* kI */ Volts.of(0.002).per(InchSecond),
/* kD */ Volts.of(0.008).per(InchPerSecond)
);
var elevatorTop = Feet.of(4).plus(Inches.of(6.125));
elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop));
```
2023-07-23 17:18:17 -04:00
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_minus(double magnitude, U unit) {
|
|
|
|
|
return mut_plus(-magnitude, unit);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Multiplies this measurement by some constant value. This will mutate the object instead of
|
|
|
|
|
* generating a new measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param multiplier the multiplier to scale the measurement by
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_times(double multiplier) {
|
|
|
|
|
mut_setBaseUnitMagnitude(m_baseUnitMagnitude * multiplier);
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Multiplies this measurement by some constant value. This will mutate the object instead of
|
|
|
|
|
* generating a new measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param multiplier the multiplier to scale the measurement by
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_times(Measure<? extends Dimensionless> multiplier) {
|
|
|
|
|
return mut_times(multiplier.baseUnitMagnitude());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Divides this measurement by some constant value. This will mutate the object instead of
|
|
|
|
|
* generating a new measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param divisor the divisor to scale the measurement by
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_divide(double divisor) {
|
|
|
|
|
mut_setBaseUnitMagnitude(m_baseUnitMagnitude / divisor);
|
|
|
|
|
return this;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Divides this measurement by some constant value. This will mutate the object instead of
|
|
|
|
|
* generating a new measurement object.
|
|
|
|
|
*
|
|
|
|
|
* @param divisor the divisor to scale the measurement by
|
|
|
|
|
* @return this measure
|
|
|
|
|
*/
|
|
|
|
|
public MutableMeasure<U> mut_divide(Measure<? extends Dimensionless> divisor) {
|
|
|
|
|
return mut_divide(divisor.baseUnitMagnitude());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public Measure<U> copy() {
|
|
|
|
|
return new ImmutableMeasure<>(m_magnitude, m_baseUnitMagnitude, m_unit);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public String toString() {
|
|
|
|
|
return toShortString();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public boolean equals(Object o) {
|
|
|
|
|
if (this == o) {
|
|
|
|
|
return true;
|
|
|
|
|
}
|
|
|
|
|
if (!(o instanceof Measure)) {
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
Measure<?> that = (Measure<?>) o;
|
|
|
|
|
return Objects.equals(m_unit, that.unit()) && this.isEquivalent(that);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public int hashCode() {
|
|
|
|
|
return Objects.hash(m_magnitude, m_unit);
|
|
|
|
|
}
|
|
|
|
|
}
|