GeometryBasics.jl

GeometryBasics.jl provides a standard set of basic geometry types designed for interoperability and performance. It is intended to serve as a foundation for graphics/plotting, finite element analysis (FEA), geographic applications, and general geometry manipulation.

Key features include:

• Support for metadata attached to geometries.
• Compatibility with query frameworks.
• Support for various memory layouts.
• A 'Julian' API designed to allow performant C-interop.

Note: This package is the intended replacement for the discontinued GeometryTypes.jl.

The Tessellation type is a wrapper for primitives that specifies how dense the resulting mesh should be. It allows you to pass a density parameter (like vertex counts or grid dimensions) to the primitive's generation functions.

• For shapes like Cylinder, you can pass an integer representing the number of vertices per circle.
• For Rect2, you can pass a tuple (nx, ny) representing the number of vertices in the x and y directions.

using GeometryBasics

# 32 vertices for each circle in the cylinder
t = Tessellation(Cylinder(Point3f(0), Point3f(0,0,1), 0.2), 32)
normal_mesh(t)

# 8 vertices in x direction by 6 in y direction for a Rect2
t = Tessellation(Rect2(Point2f(0), Vec2f(1)), (8, 6))
triangle_mesh(t)

GeometryBasics provides an interface for decomposing geometry primitives into vertex attributes and faces. If you are implementing a new primitive, you should provide implementations for the following four functions:

• coordinates(primitive[, nvertices]): Produces the positions associated with the primitive.
• faces(primitive[, nvertices]): Produces the faces that connect the vertex positions to a mesh.
• normals(primitive[, nvertices]): (Optional) Provides normal vectors of the primitive.
• texturecoordinates(primitive[, nvertices]): (Optional) Provides texture coordinates (UV or UVW).

FaceView allows you to attach data to a mesh that uses a different indexing scheme than the main mesh.faces. This is useful for memory efficiency when you want to avoid duplicating vertex data for attributes that are constant across a face (like a single color for a triangle).

Key concepts:

• Efficiency: Instead of duplicating a color for every vertex in a triangle, you can define a FaceView with one color and a face that refers to a single index.
• Expansion: If you need to convert a mesh with FaceViews into a standard mesh with duplicated vertex data, use expand_faceviews(mesh).
• Convenience: For common per-face data scenarios, use the per_face function.

GeometryBasics provides its own set of small, optimized static vectors and matrices to accelerate geometric calculations. These types are designed to behave similarly to StaticArrays.jl and are used throughout the library.

The core types are:

• Point{N,T}: A point in $N$ dimensions with element type $T$. It subtypes StaticVector{N,T} and AbstractVector{T}.
• Vec{N,T}: A vector in $N$ dimensions with element type $T$. It subtypes StaticVector{N,T} and AbstractVector{T}.
• Mat{Row, Column, T, L}: A matrix with specified rows, columns, element type $T$, and layout $L$. It subtypes AbstractMatrix{T}.

Point{N,T} <: StaticVector{N,T} <: AbstractVector{T}
Vec{N,T} <: StaticVector{N,T} <: AbstractVector{T}
Mat{Row, Column, T, L} <: AbstractMatrix{T}

To provide a specialized, more efficient, or exact bounding box for a new geometry type, implement the Rect{N, T}(geom) method.

Key implementation details:

1. Method Signature: All bounding box calls funnel into Rect{N, T}(geom). The parameters N (dimension) and T (type) default to the dimension and type of the input AbstractGeometry{N, T}.
2. Dimension Constraints: The user-requested dimension N can be less than or equal to the geometry's dimension.
3. Validation: Use GeometryBasics.bbox_dim_check(user_dim, geom_dim) to validate that the requested bounding box dimension is compatible with the geometry's dimension.

function Rect{N, T}(a::HyperSphere{N2}) where {N, N2, T}
    GeometryBasics.bbox_dim_check(N, N2)
    return Rect{N, T}(minimum(a), widths(a))
end

To build the project documentation on your local machine, you must first instantiate the documentation project located in the docs/ directory. Follow these steps in your terminal:

1. Open a Julia REPL pointing to the docs project: julia --project=docs/
2. Instantiate the dependencies: pkg> instantiate
3. Develop the current package: pkg> dev .
4. Run the build script: julia --project=docs/ docs/make.jl

Running docs/make.jl will also execute the doctests defined in the Markdown files. Ensure your doctests are compatible with the Julia version specified in the project's CI configuration.

# Step 1: Enter the docs project
julia --project=docs/

# Inside the Julia REPL:
pkg> instantiate
pkg> dev .

# Step 2: Build the docs from the shell
julia --project=docs/ docs/make.jl

GeometryBasics.jl provides a standard set of geometry types designed for metadata support, query frameworks, and various memory layouts. It serves as a replacement for the discontinued GeometryTypes.jl and is suitable for graphics, finite element analysis, and geographic applications.

To get started, load the package and use the provided constructors for points, lines, and polygons.

using GeometryBasics

# Create points
p1 = Point(3, 1)
p2 = Point(1, 3)
p3 = Point(4, 4)

# Create line segments
l1 = Line(p1, p2)
l2 = Line(p2, p3)

# Create a linestring from multiple points
ls = LineString([p1, p2, p3])

# Create a polygon from points
poly = Polygon(Point{2, Int}[(3, 1), (4, 4), (2, 4), (1, 2), (3, 1)])

# Create a rectangle (Rect) using vectors for origin and dimensions
rect = Rect(Vec(0.0, 0.0), Vec(1.0, 1.0))