Elements

Projects

Name	Description
Elements	The core elements library containing base geometric types.
Elements.Benchmarks	Benchmarks and tracing for Elements.
Elements.CodeGeneration	Methods for converting JSON schema of Element types to C#.
Elements.Components	Component creation for Elements.
Elements.Serialization.DXF	Methods for serializing a `Model` to and from DXF.
Elements.Serialization.IFC	Methods for serializing a `Model` to IFC.

Words of Warning

The Elements library is currently undergoing rapid development and breaking API changes. Until we achieve a 1.0 release, we are playing a little fast and loose with semantic versioning. Updates will be written to the CHANGELOG.

Getting Started

In a .net core project:

> dotnet add package Hypar.Elements

In Visual Studio:

PM> Install-Package Hypar.Elements

Documentation

Find the documentation here.

Examples

The best examples are those provided in the tests, where we demonstrate usage of almost every function in the library.

What

Elements is a cross-platform library for creating building elements. It's meant to be used by architects, engineers, and other building professionals who want to write code that generates buildings.

When we started Hypar we needed a library that would generate building elements and run at the core of each function on the platform. Because we don't like rebuilding the wheel, we looked around for existing libraries that fulfilled the following requirements:

The library must be small and fast. Elements is currently ~300kb and we're working every day to make it smaller.
The library must run in micro-services on Linux.
The library must have great visual documentation. If we're going to pass this library on as a recommendation to developers on Hypar, we want great docs.
The library must be free of dependencies on host applications like Rhino or Revit or geometry kernels like Open Cascade which, while really cool, become a black box in your system.
The library must be able to serialize data to formats like JSON, IFC,and glTF, that are useful to architects, engineers, contractors, and people building real-time visualization applications for AEC.
The library must be written in a language that supports developer productivity through things like type safety, and which supports code re-use in other popular AEC applications like Dynamo, Grasshopper, Revit, and Unity.
Serialization and deserialization of types that extend Element should be possible provided that those types are made up of primitives defined in this library.

We couldn't find anything quite right. So we started building this.

Design Principles

There is one base type: Element.
- Elements have a unique identifier and a name.
Elements is a C# library presently, but we expect that Element types will be used in other languages in the future. Therefore, we shouldn't rely on capabilities of C# (ex: attributes) to convey meaning of the types or their properties.
The core Element types will be defined in exactly the same way that third-party types will be defined.
- It is possible that over time these types (ex: Beam, Column, Wall, etc.) are removed from the library and only made available as schemas from which user elements can be derived.

Geometry

Elements contains a very simple BREP geometry kernel, and a small set of geometric types like vectors, lines, and polygons. Elements uses a right-handed coordinate system with +Z "up". Elements is unitless except as indicated when calling a geometric method (ex: arcs requires angles in degrees).

We are often asked whether the Elements library supports the ____ geometry kernel. It does not. Yet. The geometry kernel that we've created for Elements is a very simple BREP kernel which does "flat stuff with holes in it" really well. We think Nurbs are sexy, and we'll definitely support more curvy stuff in the future, it's just that the effort required to support ____ geometry kernel for micro-services running in the cloud is not small. Good geometry kernels are also usually large, expensive, and not open source, so they introduce a lot of concerns which are orthogonal to why we built this library in the first place. If you are interested in using Elements with another geometry library, we love pull requests.

Precision

Geometry operations in Elements use Vector3.Epsilon=1e-05 to compare values that should be considered equal. This is important as geometric operations using floating point numbers are imprecise. In addition, .NET will return different values for these operations on different systems. We have seen intersection tests that pass on a mac and fail on linux. Please use the provided methods like double.IsAlmostEqualTo(...), Vector3.IsZero(), and Vector3.IsAlmostEqualTo(...) which account for precision.

Donate

Hypar Elements is open source and will remain so forever. Your donation will directly support the development of the Hypar Elements. Hypar Elements has been demonstrated to work in Revit add-ins, Unity projects, and as Lambdas running on AWS. Send us a donation and open a feature request telling us what you'd like it to do.

Build

You'll only need to do this if you want to contribute to the library, otherwise you can use the NuGet package that is published regularly.

dotnet build

Test

dotnet test

Benchmark

cd Elements.Benchmarks
dotnet run -c Release

Building the Documentation

cd doc
docfx -f --serve

Third Party Libraries and Specifications

Updating the Changelog

We use CHANGELOG.md to provide a list of changes to Elements. The easiest way to compile this log for new releases is to look at the commits that occurred between changes. This can be done as follows: git log --pretty=oneline v0.3.6...v0.3.7, where the tags are changed appropriately.

radumg / Elements