Geometry Basics refactor

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     branches:
       - master
+      - sd/simple-mesh
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

Project.toml

@@ -9,7 +9,9 @@ Extents = "411431e0-e8b7-467b-b5e0-f676ba4f2910"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]
 Aqua = "0.8"
@@ -20,7 +22,9 @@ GeoJSON = "0.7, 0.8"
 IterTools = "1.3.0"
 LinearAlgebra = "<0.0.1,1"
 OffsetArrays = "1"
+PrecompileTools = "1.0"
 Random = "<0.0.1,1"
+StaticArrays = "0.6, 1"
 Test = "<0.0.1,1"
 julia = "1.6"
 

docs/make.jl

@@ -10,11 +10,10 @@ makedocs(format=Documenter.HTML(prettyurls=get(ENV, "CI", "false") == "true"),
          pages=[
                 "index.md",
                 "primitives.md",
-                "rectangles.md",
                 "polygons.md",
                 "meshes.md",
                 "decomposition.md",
-                "metadata.md",
+                "static_array_types.md",
                 "api.md"
                ],
          modules=[GeometryBasics])

docs/src/decomposition.md

@@ -1,89 +1,26 @@
 # Decomposition
 
-
-## GeometryBasics Mesh interface
-
-GeometryBasics defines an interface to decompose abstract geometries into
-points and triangle meshes.
-This can be done for any arbitrary primitive, by overloading the following interface:
-
-```julia
-
-function GeometryBasics.coordinates(rect::Rect2, nvertices=(2,2))
-    mini, maxi = extrema(rect)
-    xrange, yrange = LinRange.(mini, maxi, nvertices)
-    return ivec(((x,y) for x in xrange, y in yrange))
-end
-
-function GeometryBasics.faces(rect::Rect2, nvertices=(2, 2))
-    w, h = nvertices
-    idx = LinearIndices(nvertices)
-    quad(i, j) = QuadFace{Int}(idx[i, j], idx[i+1, j], idx[i+1, j+1], idx[i, j+1])
-    return ivec((quad(i, j) for i=1:(w-1), j=1:(h-1)))
-end
-```
-Those methods, for performance reasons, expect you to return an iterator, to make
-materializing them with different element types allocation free. But of course,
-can also return any `AbstractArray`.
-
-With these methods defined, this constructor will magically work:
-
-```julia
-rect = Rect2(0.0, 0.0, 1.0, 1.0)
-m = GeometryBasics.mesh(rect)
-```
-If you want to set the `nvertices` argument, you need to wrap your primitive in a `Tesselation`
-object:
-```julia
-m = GeometryBasics.mesh(Tesselation(rect, (50, 50)))
-length(coordinates(m)) == 50^2
-```
-
-As you can see, `coordinates` and `faces` are also defined on a mesh
-```julia
-coordinates(m)
-faces(m)
-```
-But will actually not be an iterator anymore. Instead, the mesh constructor uses
-the `decompose` function, that will collect the result of coordinates and will
-convert it to a concrete element type:
-```julia
-decompose(Point2f, rect) == convert(Vector{Point2f}, collect(coordinates(rect)))
-```
-The element conversion is handled by `simplex_convert`, which also handles convert
-between different face types:
-```julia
-decompose(QuadFace{Int}, rect) == convert(Vector{QuadFace{Int}}, collect(faces(rect)))
-length(decompose(QuadFace{Int}, rect)) == 1
-fs = decompose(GLTriangleFace, rect)
-fs isa Vector{GLTriangleFace}
-length(fs) == 2 # 2 triangles make up one quad ;)
-```
-`mesh` uses the most natural element type by default, which you can get with the unqualified Point type:
-```julia
-decompose(Point, rect) isa Vector{Point{2, Float64}}
-```
-You can also pass the element type to `mesh`:
-```julia
-m = GeometryBasics.mesh(rect, pointtype=Point2f, facetype=QuadFace{Int})
-```
-You can also set the uv and normal type for the mesh constructor, which will then
-calculate them for you, with the requested element type:
-```julia
-m = GeometryBasics.mesh(rect, uv=Vec2f, normaltype=Vec3f)
-```
-
-As you can see, the normals are automatically calculated,
-the same is true for texture coordinates. You can overload this behavior by overloading
-`normals` or `texturecoordinates` the same way as coordinates.
-`decompose` works a bit different for normals/texturecoordinates, since they dont have their own element type.
-Instead, you can use `decompose` like this:
-```julia
-decompose(UV(Vec2f), rect)
-decompose(Normal(Vec3f), rect)
-# the short form for the above:
-decompose_uv(rect)
-decompose_normals(rect)
-```
-You can also use `triangle_mesh`, `normal_mesh` and `uv_normal_mesh` to call the
-`mesh` constructor with predefined element types (Point2/3f, Vec2/3f), and the requested attributes.
+## decompose functions
+
+The `decompose` functions allow you to grab certain data from an `AbstractGeometry` like a mesh or primitive and convert it to a requested type, if possible.
+They can also be used to convert an array of e.g. faces into a different face type directly.
+The default decomposition implemented by GeoemtryBasics are:
+- `decompose(::Type{<: Point}, source)` which collects data from `source` using `coordinates(source)` and converts it to the given point type.
+- `decompose_normals([::Type{<: Vec},] source) = decompose([::Type{Normals{<: Vec}}},] source)` which collects data with `normals(source)` and converts it to the given Vec type.
+- `decompose_uv([::Type{<: Vec},] source) = decompose([::Type{UV{<: Vec}}},] source)` which collects data with `texturecoordinates(source)` and converts it to the given Vec type. This function also exists with `UVW` texture coordinates.
+- `decompose(::Type{<: AbstractFace}, source)` which collects data with `faces(source)` and converts it to the given face type. 
+
+### Extending decompose
+
+For `decompose` to work there needs to be a conversion from some element type to some target type. 
+GeometryBasics relies on `GeometryBasics.convert_simplex(TargetType, value)` for this.
+If you want to add new types to decompose, e.g. a new face type, you will need to add a method to that function.
+
+## Primitive decomposition
+
+GeometryBasics defines an interface to decompose geometry primitives into vertex attributes and faces.
+The interface includes four functions:
+- `coordinates(primitive[, nvertices])` which produces the positions associated with the primitive
+- `faces(primitive[, nvertices])` which produces the faces which connect the vertex positions to a mesh
+- `normals(primitive[, nvertices])` which optionally provide normal vectors of the primitive
+- `texturecoordinates(primitive[, nvertices])` which optional provide texture coordinates (uv/uvw) of the primitive

docs/src/index.md

@@ -22,56 +22,20 @@ p2 = Point(1, 3);
 p3 = Point(4, 4);
 ```
 
-Geometries can carry metadata:
-
-```@repl quickstart
-poi = meta(p1, city="Abuja", rainfall=1221.2)
-```
-
-Metadata is stored in a NamedTuple and can be retrieved as such:
-
-```@repl quickstart
-meta(poi)
-```
-
-Specific metadata attributes can be directly retrieved:
-
-```@repl quickstart
-poi.rainfall
-```
-
-To remove the metadata and keep only the geometry, use `metafree`:
-
-```@repl quickstart
-metafree(poi)
-```
-
-Geometries have predefined metatypes:
-
-```@repl quickstart
-multipoi = MultiPointMeta([p1], city="Abuja", rainfall=1221.2)
-```
-
-Connect the points with lines:
+Connect pairs of points as line segments:
 
 ```@repl quickstart
 l1 = Line(p1, p2)
 l2 = Line(p2, p3);
 ```
 
-Connect the lines in a linestring:
-
-```@repl quickstart
-LineString([l1, l2])
-```
-
-Linestrings can also be constructed directly from points:
+Or connect multiple points as a linestring:
 
 ```@repl quickstart
 LineString([p1, p2, p3])
 ```
 
-The same goes for polygons:
+You can also create polygons from points:
 
 ```@repl quickstart
 Polygon(Point{2, Int}[(3, 1), (4, 4), (2, 4), (1, 2), (3, 1)])
@@ -89,57 +53,20 @@ Decompose the rectangle into two triangular faces:
 rect_faces = decompose(TriangleFace{Int}, rect)
 ```
 
-Decompose the rectangle into four vertices:
+Decompose the rectangle into four positions:
 
 ```@repl quickstart
-rect_vertices = decompose(Point{2, Float64}, rect)
+rect_positions = decompose(Point{2, Float64}, rect)
 ```
 
 Combine the vertices and faces into a triangle mesh:
 
 ```@repl quickstart
-mesh = Mesh(rect_vertices, rect_faces)
+mesh = Mesh(rect_positions, rect_faces)
 ```
 
 Use `GeometryBasics.mesh` to get a mesh directly from a geometry:
 
 ```@repl quickstart
 mesh = GeometryBasics.mesh(rect)
 ```
-
-
-## Aliases
-
-GeometryBasics exports common aliases for Point, Vec, Mat and Rect:
-
-### Vec
-
-|        |`T`(eltype) |`Float64` |`Float32` |`Int`     |`UInt`    |
-|--------|------------|----------|----------|----------|----------|
-|`N`(dim)|`Vec{N,T}`  |`Vecd{N}` |`Vecf{N}` |`Veci{N}` |`Vecui{N}`|
-|`2`     |`Vec2{T}`   |`Vec2d`   |`Vec2f`   |`Vec2i`   |`Vec2ui`  |
-|`3`     |`Vec3{T}`   |`Vec3d`   |`Vec3f`   |`Vec3i`   |`Vec3ui`  |
-
-### Point
-
-|        |`T`(eltype) |`Float64` |`Float32` |`Int`     |`UInt`    |
-|--------|------------|----------|----------|----------|----------|
-|`N`(dim)|`Point{N,T}`|`Pointd{N}`|`Pointf{N}`|`Pointi{N}`|`Pointui{N}`|
-|`2`     |`Point2{T}` |`Point2d` |`Point2f` |`Point2i` |`Point2ui`|
-|`3`     |`Point3{T}` |`Point3d` |`Point3f` |`Point3i` |`Point3ui`|
-
-### Mat
-
-|        |`T`(eltype) |`Float64` |`Float32` |`Int`     |`UInt`    |
-|--------|------------|----------|----------|----------|----------|
-|`N`(dim)|`Mat{N,T}`  |`Matd{N}` |`Matf{N}` |`Mati{N}` |`Matui{N}`|
-|`2`     |`Mat2{T}`   |`Mat2d`   |`Mat2f`   |`Mat2i`   |`Mat2ui`  |
-|`3`     |`Mat3{T}`   |`Mat3d`   |`Mat3f`   |`Mat3i`   |`Mat3ui`  |
-
-### Rect
-
-|        |`T`(eltype) |`Float64` |`Float32` |`Int`     |`UInt`    |
-|--------|------------|----------|----------|----------|----------|
-|`N`(dim)|`Rect{N,T}` |`Rectd{N}`|`Rectf{N}`|`Recti{N}`|`Rectui{N}`|
-|`2`     |`Rect2{T}`  |`Rect2d`  |`Rect2f`  |`Rect2i`  |`Rect2ui` |
-|`3`     |`Rect3{T}`  |`Rect3d`  |`Rect3f`  |`Rect3i`  |`Rect3ui` |

docs/src/meshes.md

@@ -1,24 +1,80 @@
 # Meshes
 
-## Types
+GeometryBasics defines two mesh types to work with - `Mesh` and `MetaMesh`
 
-* [`AbstractMesh`](@ref)
-* [`Mesh`](@ref)
+## Mesh
+
+```@docs; canonical=false
+Mesh
+```
+
+You can get data from a mesh using a few interface functions:
+- `vertex_attributes(mesh) = mesh.vertex_attributes`
+- `coordinates(mesh) = mesh.vertex_attributes[:position]`
+- `normals(mesh) = mesh.vertex_attributes[:normal]`
+- `texturecoordinates(mesh) = mesh.vertex_attributes[:uv]`
+- `faces(mesh) = mesh.faces`
+
+You can also grab the contents of `mesh.vertex_attributes` as if they were fields of the `Mesh`, e.g. `mesh.position` works.
+
+### FaceView
+
+As mentioned above, a vertex attribute can be a `FaceView`.
+A `FaceView` is simply defined as a vector of data and a vector of faces:
+
+```julia
+struct FaceView{T, AVT <: AbstractVector{T}, FVT <: AbstractVector{<: AbstractFace}}
+    data::AVT
+    faces::FVT
+end
+```
+
+Its purpose is to allow you to add data that needs to be defined per vertex but does not match the vertex structure used by `mesh.faces`.
+
+As a minimal example consider a mesh that is just one triangle, i.e. 3 position and one triangle face `TriangleFace(1,2,3)`.
+Let's say we want to add a flat color to the triangle.
+In this case we only have one color, but our face refers to 3 different vertices (3 different positions).
+To avoid duplicating the color data, we can instead define a new triangle face `TriangleFace(1)` and add the color attribute as a `FaceView([color], [TriangleFace(1)])`.
+If we ever need the mesh to be defined with just one common set of faces, i.e. no FaceView and appropriately duplicated vertex data, we can use `clear_faceviews(mesh)` to generate it.
+
+On a larger scale this can be useful for memory and performance reason, e.g. when you do calculations with vertex attributes.
+It can also simplify some definitions, like for example `Rect3`.
+In that case we have 8 positions and 6 normals with FaceViews, or 24 without (assuming per-face normals). 
+
+
+## MetaMesh
+
+A `MetaMesh` is given by
+
+```julia
+struct MetaMesh{Dim, T, M <: AbstractMesh{Dim, T}} <: AbstractMesh{Dim, T}
+    mesh::M
+    meta::Dict{Symbol, Any}
+end
+```
+
+where `meta` may contain any data you want to include with a mesh.
+For example, you could include group names or material data corresponding to `mesh.views`.
 
 ## How to create a mesh
 
-### Meshing.jl
+### GeometryBasics
 
-### MeshIO.jl
+In GeometryBasics you mainly create meshes from primitives using a few constructors:
+- `triangle_mesh(primitive)` generates the most basic mesh (i.e. positions and faces)
+- `normal_mesh(primitive)` generates a mesh with normals (generated if the primitive doesn't implement `normal()`)
+- `uv_mesh(primitive)` generates a mesh with texture coordinates (generated if the primitive doesn't implement `texturecoordinates()`)
+- `uv_normal_mesh(primitive)` generates a mesh with normals and texture coordinates
 
-The [`MeshIO.jl`](https://github.com/JuliaIO/MeshIO.jl) package provides load/save support for several file formats which store meshes.
+Each of these constructors also includes keyword arguments for setting types, i.e. `pointtype`, `facetype`, `normaltype` and `uvtype` as appropriate.
+Of course you can also construct a mesh directly from data, either with there various `Mesh()` or `GeometryBasics.mesh()` constructors.
+The latter also include a `pointtype` and `facetype` conversion.
 
-## How to access data
+Finally there is also a `merge(::Vector{Mesh})` function which combines multiple meshes into a single one.
+Note that this doesn't remove any data (e.g. hidden or duplicate vertices), and may remove `FaceView`s if they are incompatible between meshes.
 
-The following functions can be called on an [`AbstractMesh`](@ref) to access its underlying data.
+### Meshing.jl
 
-* [`faces`](@ref)
-* [`coordinates`](@ref)
-* `texturecoordinates`
-* [`normals`](@ref)
+### MeshIO.jl
 
+The [`MeshIO.jl`](https://github.com/JuliaIO/MeshIO.jl) package provides load/save support for several file formats which store meshes.