Skip to content

Latest commit

 

History

History
90 lines (64 loc) · 2.98 KB

README.md

File metadata and controls

90 lines (64 loc) · 2.98 KB
Raw

CI Audit

OMF

A library for reading and writing files in Open Mining Format 2.0. Also supports translating OMF 1 files to OMF 2.

OMF file version: 2.0-beta.1

Crate version: 0.1.0-beta.1

Warning: this is pre-release code.

What is OMF

OMF is an open-source serialization format and library to support data interchange across the entire mining community. Its goal is to standardize file formats and promote collaboration.

This repository provides a file format specification and a Rust library for reading and writing files, plus a wrapper to use that library from C.

What OMF Stores

Elements

  • Points.
  • Line segments.
  • Triangulated surfaces.
  • Grid surfaces.
    • Regular or tensor grid spacing.
    • Any orientation.
  • Block models, with optional sub-blocks.
    • Regular or tensor grid spacing.
    • Any orientation.
    • Regular sub-blocks that lie on a grid within their parent, with octree or arbitrary layout.
    • Free-form sub-blocks that don't lie on any grid.
  • Composite elements made out of any of the above.

Attributes

  • Floating-point or signed integer values.
  • Date and date-time values.
  • Category values, storing an index used to look up name, color, or other sub-attributes.
  • Boolean or filter values.
  • 2D and 3D vectors.
  • Text values.
  • Color values.
  • Projected texture images.
  • UV mapped texture images.

Attributes values can be valid or null. They can be attached to different parts of each element type, such as the vertices vs. faces of a surface, or the parent blocks vs. sub-blocks of a block model.

Compiling

First install Rust. Run cargo build --all --release in the root directory to build the release version of the Rust crate and C wrapper. The C wrapper build will place omf.h and the platform-specific shared library files (e.g.: omfc.dll and omfc.dll.lib for Windows) in target/release.

You can the --release argument off to build a debug version. This may be useful for debugging C code that calls into OMF for example, but it will be slow.

For the Rust tests, run cargo test --all.

To build and run the C examples:

  1. Run cargo build --all --release first.
  2. Change directory into omf-c/examples/.
  3. Run build.bat on Windows or build.sh on Linux/MacOS.

This will build all examples, run them, and compare the results to the benchmarks.

Documentation

The documentation is built with MkDocs. To build locally:

  1. Create and activate a Python virtual environment.
  2. Change directory into docs/.
  3. Run build.bat on Windows or build.sh on Linux/MacOS.

This will install the required dependencies, then build the file format, Rust, and C documentation into site/.