Primitives

Primitive{M,CRS}

We say that a geometry is a primitive when it can be expressed as a single entity with no parts (a.k.a. atomic). For example, a sphere is a primitive described in terms of a mathematical expression involving a metric and a radius. See https://en.wikipedia.org/wiki/Geometric_primitive.

Point(x, [y, z])
Point((x, [y, z]))

A point with Cartesian coordinates in length units (default to meters). The coordinates y and z are optional for 2D and 3D points, respectively.

Point(CRS(...))

A point with coordinates in a specified coordinate reference system (CRS). Please check CoordRefSystems.jl for available coordinate reference systems.

Point{M}(CRS(...))

Optionally, specify the manifold M of the point. The default manifold is 𝔼{dim} (Euclidean space). It can also be 🌐 in which case the point is interpreted as a point on the surface of the Earth (or any other spheroid).

Examples

# points in 2D Euclidean space
Point(1.0, 2.0) # meter units by default
Point(1.0m, 2.0m) # double precision as expected
Point(1f0m, 2f0m) # single precision as expected
Point(1m, 2m) # integer is converted to float by design

# points in 3D Euclidean space
Point(1km, 2km, 3km) # specify kilometer units
Point(1m, 2ft, 3in) # mixed units are promoted

# points on the surface of the Earth
Point(LatLon(0.0, 0.0)) # degree units by default
Point(LatLon(0.0°, 0.0°)) # specify units explicitly

# specify manifold explicitly
Point{🌐}(convert(Cartesian, LatLon(0.0, 0.0)))

Notes

Integer coordinates are not supported because most geometric processing algorithms assume a continuous space. The conversion to float avoids InexactError and other unexpected results.

to(point)

Return the vector from the origin to the point.

-(A::Point, B::Point)

Return the Vec associated with the direction from point B to point A.

+(A::Point, v::Vec)
+(v::Vec, A::Point)

Return the point at the end of the vector v placed at a reference (or start) point A.

-(A::Point, v::Vec)
-(v::Vec, A::Point)

Return the point at the end of the vector -v placed at a reference (or start) point A.

Ray(p, v)

A ray originating at point p, pointed in direction v. It can be called as r(t) with t > 0 to cast it at p + t * v.

Line(a, b)

A line passing through points a and b.

See also Segment.

BezierCurve(points)

A recursive Bézier curve with control points points. See https://en.wikipedia.org/wiki/Bézier_curve.

A point on the Bézier curve b can be evaluated by calling b(t) with t between 0 and 1. The evaluation method defaults to DeCasteljau's algorithm for accurate evaluation. Horner's method, faster with a large number of points but less precise, can be used via b(t, Horner()).

Examples

BezierCurve([(0.,0.),(1.,-1.)])

ParametrizedCurve(fun, range = (0.0, 1.0))

A parametrized curve is a curve defined by a function fun that maps a (unitless) parameter t in the given range to a Point in space.

Examples

ParametrizedCurve(t -> Point(cos(t), sin(t)), (0, 2π))

Plane(p, u, v)

A plane embedded in R³ passing through point p, defined by non-parallel vectors u and v.

Plane(p, n)

Alternatively specify point p and a given normal vector n to the plane.

Box(min, max)

A (geodesic) box with min and max points on a given manifold.

Examples

Construct a 3D box using points with Cartesian coordinates:

Box((0, 0, 0), (1, 1, 1))

Likewise, construct a 2D box on the plane:

Box((0, 0), (1, 1))

Construct a geodesic box on the ellipsoid:

Box(Point(LatLon(0, 0)), Point(LatLon(1, 1)))

Ball(center, radius)

A ball with center and radius.

See also Sphere.

Sphere(center, radius)

A sphere with center and radius.

See also Ball.

Ellipsoid(radii, center=(0, 0, 0), rotation=I)

A 3D ellipsoid with given radii, center and rotation.

Disk(plane, radius)

A disk embedded in 3-dimensional space on a given plane with given radius.

See also Circle.

Circle(plane, radius)

A circle embedded in 3-dimensional space on a given plane with given radius.

See also Disk.

Cylinder(bottom, top, radius)

A solid circular cylinder embedded in R³ with given radius, delimited by bottom and top planes.

Cylinder(start, finish, radius)

Alternatively, construct a right circular cylinder with given radius along the segment with start and finish end points.

Cylinder(start, finish)

Or construct a right circular cylinder with unit radius along the segment with start and finish end points.

Cylinder(radius)

Finally, construct a right vertical circular cylinder with given radius.

See https://en.wikipedia.org/wiki/Cylinder.

See also CylinderSurface.

CylinderSurface(bottom, top, radius)

A circular cylinder surface embedded in R³ with given radius, delimited by bottom and top planes.

CylinderSurface(start, finish, radius)

Alternatively, construct a right circular cylinder surface with given radius along the segment with start and finish end points.

CylinderSurface(start, finish)

Or construct a right circular cylinder surface with unit radius along the segment with start and finish end points.

CylinderSurface(radius)

Finally, construct a right vertical circular cylinder surface with given radius.

See https://en.wikipedia.org/wiki/Cylinder.

See also Cylinder.

Cone(base, apex)

A cone with base disk and apex. See https://en.wikipedia.org/wiki/Cone.

See also ConeSurface.

ConeSurface(base, apex)

A cone surface with base disk and apex. See https://en.wikipedia.org/wiki/Cone.

See also Cone.

Frustum(bot, top)

A frustum (truncated cone) with bot and top disks. See https://en.wikipedia.org/wiki/Frustum.

See also FrustumSurface.

FrustumSurface(bot, top)

A frustum (truncated cone) surface with bot and top disks. See https://en.wikipedia.org/wiki/Frustum.

See also Frustum.

Torus(center, direction, major, minor)

A torus centered at center with axis of revolution directed by direction and with radii major and minor.

ParaboloidSurface(apex, radius, focallength)

A paraboloid surface embedded in R³ and extending up to a distance radius from its focal axis, which is aligned along the z direction and passes through apex (the apex of the paraboloid). The equation of the paraboloid is the following:

\[f(x, y) = \frac{(x - x_0)^2 + (y - y_0)^2}{4f} + z_0\qquad\text{for } x^2 + y^2 < r^2,\]

where $(x_0, y_0, z_0)$ is the apex of the parabola, $f$ is the focal length, and $r$ is the clip radius.

ParaboloidSurface(apex, radius)

This creates a paraboloid surface with focal length equal to 1.

ParaboloidSurface(apex)

This creates a paraboloid surface with focal length equal to 1 and a rim with unit radius.

ParaboloidSurface()

Same as above, but here the apex is at Apex(0, 0, 0).

See also https://en.wikipedia.org/wiki/Paraboloid.