superdeclarative_geometry

Description:

superdeclarative geometry

SuperDeclarative Geometry #
First-class support for angles, polar coordinates, and related math.

If you get value from this package, please consider supporting SuperDeclarative!


Get Started #

dependencies:
superdeclarative_geometry: ^[VERSION]
copied to clipboard

Quick Reference #
Angles #
Create an Angle from degrees or radians:
final degreesToRadians = Angle.fromDegrees(45);
final radiansToDegrees = Angle.fromRadians(pi / 4);
copied to clipboard
Retrieve Angle values as degrees or radians:
myAngle.degrees;
myAngle.radians;
copied to clipboard
Determine an Angle's direction and force it to be positive or negative:
myAngle.isPositive;
myAngle.isNegative;

myAngle.makePositive(); // Ex: -270° -> 90°
myAngle.makeNegative(); // Ex: 270° -> -90°
copied to clipboard
Determine the category of an Angle:
myAngle.isAcute;
myAngle.isObtuse;
myAngle.isReflexive;
myAngle.category;
copied to clipboard
Determine if two Angles are equivalent, regardless of direction:
Angle.fromDegrees(90).isEquivalentTo(Angle.fromDegrees(-270));
copied to clipboard
Invert, add, subtract, multiply, and divide Angles:
-Angle.fromDegrees(30);

Angle.fromDegrees(30) + Angle.fromDegrees(15);

Angle.fromDegrees(30) - Angle.fromDegrees(15);

Angles.fromDegrees(45) * 2;

Angles.fromDegrees(90) / 2;
copied to clipboard
Rotate an Angle:
final Rotation rotation = myAngle.rotate(Angle.fromDegrees(150));
copied to clipboard

Rotations #
Angles are confined to values in (-360°, 360°). For values beyond this range, the concept of a Rotation is provided.
A Rotation is almost identical to an Angle except that a Rotation can be arbitrarily large in the positive or negative direction. This allows for the accumulation of turns over time.
Create a Rotation:
final rotation = Rotation.fromDegrees(540);
copied to clipboard
Add, subtract, multiply, and divide Rotations just like Angles.
Reduce a Rotation to an Angle:
Rotation.fromDegrees(540).reduceToAngle();
copied to clipboard

Polar Coordinates #
Define polar coordinates by a radius and an angle, or by a Cartesian point:
PolarCoord(100, PolarCoord.fromDegrees(45));

CartesianPolarCoords.fromPoint(Point(0, 100));
copied to clipboard
Add, subtract, multiply, and divide PolarCoords:
PolarCoord(100, Angle.fromDegrees(45)) + PolarCoord(200, Angle.fromDegrees(135));

PolarCoord(100, Angle.fromDegrees(45)) - PolarCoord(200, Angle.fromDegrees(135));

PolarCoord(100, Angle.fromDegrees(15)) * 2;

PolarCoord(200, Angle.fromDegrees(30)) / 2;
copied to clipboard
Map a PolarCoord to a Cartesian Point:
// Map to Cartesian coordinates.
final Point point = PolarCoord(100, Angle.fromDegrees(45)).toCartesian();
copied to clipboard

Cartesian Orientations #
Different use-cases treat angles in different ways.
Mathematics treats the positive x-axis as a 0° angle and treats positive angles as running counter-clockwise.
Flutter app screens treat the positive x-axis as a 0° angle, but then treats positive angles as running clockwise.
Ship navigation treats the positive y-axis as a 0° angle and then treats positive angles as running clockwise.
Each of these situations apply a different orientation when mapping an angle, or a polar coordinate, to a location in Cartesian space. This concept of orientation is supported by superdeclarative_geometry by way of CartesianOrientations.
Both Angle and PolarCoord support CartesianOrientation mappings.
final polarCoord = PolarCoord(100, Angle.fromDegrees(30));

// Treat angles like a Flutter screen.
// This point is 30° clockwise from the x-axis.
final screenPoint = polarCoord.toCartesian(); // defaults to "screen" orientation

// Treat angles like mathematics.
// This point is 30° counter-clockwise from the x-axis.
final mathPoint = polarCoord.toCartesian(orientation: CartesianOrientation.math);

// Treat angles like navigators.
// This point is 30° clockwise from the y-axis.
final navigationPoint = polarCoord.toCartesian(orientation: CartesianOrientation.navigation);
copied to clipboard
You can define a custom CartesianOrientation by implementing the interface. Then, you can pass an instance of your custom orientation into PolarCoord's toCartesian() method.