elm-geometry 3 is out! This release is the result of many months of work (and tons of useful feedback and contributions from the community) updating
elm-geometry to keep track of both units and coordinate systems at compile time. This builds on
elm-units to keep track of (for example) whether a given
Point2d is in on-screen units (pixels) or real-world units (meters), or even some other kind of custom unit like tiles in a tile-based 2D game. Keeping track of coordinate systems is similar but unique to
elm-geometry; this lets you keep track of things like whether a given point is defined in (for example) ‘local’ or ‘global’ coordinates, and is useful especially in more complex applications. Functions are also provided to convert between different units, and between different coordinate systems, in a rigorous and type-safe way.
These changes will break any code that uses
elm-geometry 1.x, and may require a fair bit of work to update. For example, where before you might have written
import Point2d point = Point2d.fromCoordinates ( 200, 300 )
you might now instead write
import Point2d import Pixels exposing (pixels) point = Point2d.xy (pixels 200) (pixels 300)
or perhaps just
import Point2d point = Point2d.pixels 200 300
In addition, most functions that returned a
Float now generally return a
Quantity Float units, which means you will need to either convert those values to a
Float using functions like
Length.inMeters, or work directly with the values using functions from the
Quantity module. For example, where before you might have written
if Point2d.distanceFrom p1 p2 > 10 then ...
you might now write something like
if Point2d.distanceFrom p1 p2 |> Quantity.greaterThan (Length.meters 10) then ...
As a result, while I certainly recommend using version 3 for all new projects, it may not be worth the effort to update existing apps -
elm-geometry 1.x still works fine and has no known bugs, and I’m happy to support it for the foreseeable future. That said, if you have a published package that currently uses
elm-geometry 1.x (or the temporary, never-officially-published 2.x) then it would be great if you could update it to use 3.x. I’m hoping that
elm-geometry 3.x can be an “LTS” release that can reliably be used as a base for other packages, so it would be great to get all published packages using it to avoid dependency conflicts/ecosystem fragmentation. I’m happy to help with this process by answering questions or submitting PRs; please reach out to me (@ianmackenzie) on Slack!
I’m currently working on some high-level documentation for
elm-geometry (based on the excellent
elm-pages) that will complement the API reference documentation and discuss units, coordinate systems and other topics like 2D and 3D transformations in more detail; in the meantime, check out the README for a brief discussion of units and coordinate systems, and the release notes to get a sense of what’s changed since 1.x (you’ll have to look at the release notes for both 2.0.0 and 3.0.0 to get the full picture).
Happy to answer any questions either here or in the #geometry channel on the Elm Slack!