HelixToolkit.Nex.Geometries 1.2.0

# HelixToolkit.Nex.Geometries

The `HelixToolkit.Nex.Geometries` package is a core component of the HelixToolkit-Nex 3D graphics engine, designed to handle geometric data structures and operations. It provides functionality for managing, processing, and rendering geometric data, including vertices, indices, and vertex properties. This package is essential for creating and manipulating 3D models within the HelixToolkit-Nex engine.

## Overview

The `HelixToolkit.Nex.Geometries` package is responsible for:
- Managing geometric data through the `Geometry` class, which includes vertices, indices, and vertex properties.
- Providing utilities for normal calculation, tangent generation, and buffer management.
- Supporting serialization and deserialization of geometric data.
- Implementing octree structures for efficient spatial queries and hit testing.
- Integrating with the HelixToolkit-Nex ECS architecture for dynamic and static geometry management.

## Key Types

| Type                       | Description                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `Geometry`                 | Represents a 3D geometry with vertices, indices, and vertex properties.                             |
| `VertexProperties`         | Struct containing normal, texture coordinates, and tangent information for a vertex.                |
| `GeometryBufferType`       | Enum defining the types of buffers used in a geometry, such as vertex, index, and color buffers.    |
| `GeometryManager`          | Manages a pool of geometry resources with automatic ID assignment and lifecycle management.         |
| `HitTestContext`           | Provides context for performing hit tests, including ray and screen point information.              |
| `HitTestResult`            | Represents the result of a hit test, including distance, hit point, and normal at the hit location. |
| `IOctreeBasic`             | Interface for basic octree operations, used for spatial queries and hit testing.                    |
| `StaticMeshGeometryOctree` | Static octree implementation for mesh geometries, optimizing spatial queries and hit tests.         |
| `GeometryJsonConverter`    | JSON converter for serializing and deserializing `Geometry` objects.                                |
| `TangentGenerator`         | Static class for generating tangent vectors for geometries that lack them.                          |

## Usage Examples

### Creating and Managing Geometry

```csharp
var vertices = new FastList<Vector4>
{
    new Vector4(0, 0, 0, 1),
    new Vector4(1, 0, 0, 1),
    new Vector4(0, 1, 0, 1)
};

var indices = new FastList<uint> { 0, 1, 2 };

var geometry = new Geometry(vertices, indices, Topology.Triangle);
geometry.UpdateNormals();
TangentGenerator.ComputeTangents(geometry);

Performing a Hit Test

var renderMatrices = ... // Obtain IRenderMatrices instance
var ray = new Ray(new Vector3(0, 0, -1), Vector3.UnitZ);
var hitPoint = new Vector2(100, 100);

var hitTestContext = new HitTestContext(renderMatrices, ray, hitPoint);
var hits = new List<HitTestResult>();

if (geometry.HitTest(hitTestContext, entity, geometry, Matrix.Identity, ref hits))
{
    foreach (var hit in hits)
    {
        Console.WriteLine($"Hit at distance: {hit.Distance}");
    }
}

Serializing Geometry

var options = new JsonSerializerOptions
{
    Converters = { new GeometryJsonConverter() }
};

string json = JsonSerializer.Serialize(geometry, options);
var deserializedGeometry = JsonSerializer.Deserialize<Geometry>(json, options);

Architecture Notes

• Design Patterns: The package uses the Entity Component System (ECS) architecture for managing dynamic and static geometries, built on the custom HelixToolkit.Nex.ECS framework.
• Dependencies: It relies on other HelixToolkit-Nex packages such as HelixToolkit.Nex.Graphics for rendering and HelixToolkit.Nex.Maths for mathematical operations.
• Octree Implementation: The package includes several octree implementations for efficient spatial queries, such as StaticMeshGeometryOctree and StaticPointGeometryOctree.
• Serialization: Custom JSON converters are provided for Geometry and VertexProperties to facilitate serialization and deserialization.

Recent Changes

• VertexProperties Struct:
  • The Tangent field has been updated to a Vector4 to include handedness information, aligning with the glTF specification.
  • Introduced DefaultTangent for initializing tangents with a default right-handed bitangent.
• Geometry Class:
  • Updated buffer management logic to use HasAllFlags for checking buffer types.
  • Buffer debug names have been updated for clarity.
  • Removed redundant event publishing logic from property change handlers.
• GeometryManager API:
  • Introduced UploadMeshInfoDynamic method for uploading mesh information to the GPU.
  • Added LastIndex property to track the last object index in the pool.
• TangentGenerator Class:
  • New static class for generating tangent vectors for geometries using the Lengyel algorithm.
• Serialization:
  • Updated VertexPropsJsonConverter to handle Vector4 tangents.
• Platform Configurations: Added new build configurations for LinuxDebug and LinuxRelease to support cross-platform development.