opensolid/geometry

Note: if you're upgrading from 1.x, make sure to check out the release notes!

opensolid/geometry is an Elm package for working with 2D and 3D geometry. It provides a wide variety of geometric data types such as points, vectors, arcs, spline curves and coordinate frames, along with functions for transforming and combining them in many different ways. You can:

Rotate points around axes in 3D
Mirror triangles across 3D planes
Project 3D geometry into 2D sketch planes
Measure distances and angles between different objects
Convert objects between different coordinate systems
Compose complex 2D/3D transformations
...and much more!

A wide variety of data types are supported:

Point2d, Point3d, Vector2d, Vector3d, Direction2d, Direction3d
Axis2d, Axis3d, Plane3d
Frame2d, Frame3d, SketchPlane3d
BoundingBox2d, BoundingBox3d
LineSegment2d, LineSegment3d, Triangle2d, Triangle3d
Polyline2d, Polyline3d, Polygon2d
Circle2d, Circle3d, Arc2d, Arc3d
QuadraticSpline2d, QuadraticSpline3d, CubicSpline2d, CubicSpline3d

A large range of geometric functionality is included, such as various forms of constructors...

Point3d.fromCoordinates ( 1, 4, 5 )

Direction2d.fromAngle (degrees 30)

Point3d.midpoint p1 p2

Triangle2d.fromVertices ( p1, p2, p3 )

-- fit a plane through three points
Plane3d.throughPoints ( p1, p2, p3 )

Axis3d.with
    { originPoint = Point3d.origin
    , direction = Direction3d.z
    }

Arc2d.fromEndpoints
    { startPoint = p1
    , endPoint = p2
    , radius = 3
    , sweptAngle = Arc2d.smallPositive
    }

QuadraticSpline3d.fromControlPoints ( p1, p2, p3 )

CubicSpline2d.hermite
    ( startPoint, startDerivative )
    ( endPoint, endDerivative )

...point/vector arithmetic...

Vector3d.sum v1 v2

-- the vector from the point p1 to the point p2
Vector2d.from p1 p2

Vector3d.crossProduct v1 v2

Vector2d.length vector

-- distance of a point from the origin point (0, 0)
point |> Point2d.distanceFrom Point2d.origin

...2D/3D transformations...

Vector2d.rotateBy (degrees 45) vector

Point2d.rotateAround Point2d.origin (degrees 45) point

Point3d.mirrorAcross Plane3d.xy point

Vector3d.projectionIn Direction3d.z vector

Triangle3d.rotateAround Axis3d.x (degrees 45) triangle

lineSegment
    |> LineSegment3d.mirrorAcross Plane3d.yz
    |> LineSegment3d.projectOnto Plane3d.xy

Plane3d.offsetBy 3 Plane3d.xy

...and conversions between coordinate systems:

rotatedFrame =
    Frame2d.xy |> Frame2d.rotateBy (degrees 30)

-- convert from global coordinates to local coordinates
-- (relative to the given coordinate frame)
Vector2d.relativeTo rotatedFrame vector

-- convert from local coordinates (relative to the given
-- coordinate frame) to global coordinates
Point2d.placeIn rotatedFrame point

-- convert from global 3D coordinates to local 2D
-- coordinates in the given sketch plane
point2d =
    Point3d.projectInto SketchPlane3d.yz point3d

-- convert from local 2D coordinates in the given
-- sketch plane back to global 3D coordinates
point3d =
    Point3d.on SketchPlane3d.yz point2d

Support is also provided for encoding/decoding values to and from JSON.

Installation

Assuming you have installed Elm and started a new project, use elm-package to install opensolid/geometry, either by running

elm package install opensolid/geometry

in a command prompt inside your project directory or by adding

"opensolid/geometry": "2.0.0 <= v < 3.0.0"

to the dependencies field in your project's elm-package.json.

Documentation

Full API documentation is available for each module. Most modules are associated with a particular data type (for example, the Point3d module contains functions for creating and manipulating Point3d values).

Usage details

Following the Elm package design guidelines, most OpenSolid modules are designed to be imported using as and then used as prefixes for the functions and values that they define. Types are designed to be imported unqualified using exposing:

import OpenSolid.Point3d as Point3d exposing (Point3d)
import OpenSolid.Axis3d as Axis3d exposing (Axis3d)

rotatedPoint : Point3d
rotatedPoint =
    Point3d.rotateAround Axis3d.x (degrees 30) originalPoint

Related projects

opensolid/svg lets you create and manipulate SVG drawings using the data types from this package.
opensolid/linear-algebra-interop provides interop support between this package and elm-community/linear-algebra.

Questions? Comments?

Please open a new issue if you run into a bug, if any documentation is missing/incorrect/confusing, or if there's a new feature that you would find useful. For general questions about using OpenSolid, try:

Sending me (@ianmackenzie) a message on the Elm Slack - even if you don't have any particular questions right now, just come say hello!
Posting to the r/elm subreddit
Posting to the elm-discuss Google Group (somewhat less active than Slack and Reddit, but I still follow it regularly if you prefer e-mail)
Or if you happen to be in the New York area, come on out to the Elm NYC meetup =)

You can also find me on Twitter (@ianemackenzie), where I occasionally post OpenSolid-related stuff like demos or new releases. Have fun, and don't be afraid to ask for help!

jeslyvarghese / geometry