Initial implementation

.github/workflows/audit.yml

@@ -0,0 +1,33 @@
+# Audit dependencies against the RustSec Advisory DB (https://rustsec.org/advisories/)
+name: Audit
+
+on:
+  push:
+    paths:
+      # Run if workflow changes
+      - '.github/workflows/audit.yml'
+      # Run on changed dependencies
+      - '**/Cargo.toml'
+      - '**/Cargo.lock'
+      # Run if the configuration file changes
+      - '**/audit.toml'
+  # Rerun periodicly to pick up new advisories
+  schedule:
+    - cron: '0 0 * * *'
+  # Run manually
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Audit Rust Dependencies
+        uses: actions-rust-lang/audit@v1
+        with:
+          denyWarnings: true
+          createIssues: false

.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on: [push]
+
+permissions:
+  contents: read
+
+env:
+  RUST_BACKTRACE: 1
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt
+
+      - name: Check
+        run: cargo check --all
+
+      - name: Check featuresless
+        run: cargo check --all --no-default-features
+
+      - name: Clippy
+        run: cargo clippy --all
+
+      - name: Format
+        uses: actions-rust-lang/rustfmt@v1
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { rust: stable, os: ubuntu-latest }
+          - { rust: stable, os: windows-latest }
+          - { rust: stable, os: macos-latest }
+          - { rust: beta, os: ubuntu-latest }
+          # Turn this on once we have a MSRV (minimum supported rust version)
+          # - { rust: 1.70.0, os: ubuntu-latest }
+    name: Test Rust ${{ matrix.rust }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: ${{ matrix.rust }}
+
+      - name: Test
+        run: cargo test --all
+
+      - name: Build
+        run: cargo build --all --release
+
+      - name: C Examples
+        if: runner.os != 'Windows'
+        working-directory: ./omf-c/examples
+        run: bash ./build.sh
+
+      - name: C Examples (Windows)
+        if: runner.os == 'Windows'
+        working-directory: ./omf-c/examples
+        run: ./build.bat

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Build docs
+        run: |
+          cd docs
+          sh build.sh
+
+      - name: Fix permissions
+        run: |
+          chmod -c -R +rX "./site/" | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+
+      - name: Store artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: site/
+
+  deploy:
+    needs: docs
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -0,0 +1,24 @@
+# Generated by Cargo
+# will have compiled files and executables
+target/
+
+# Generated by CMake.
+omf-c/examples/build/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# Generated code.
+/site/
+/docs/schema/
+/docs/parquet/
+
+# Virtual environment for mkdocs
+/venv/

.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "cSpell.language": "en",
+    "cSpell.words": [
+        "colormap",
+        "colormaps",
+        "grayscale",
+        "octree",
+        "RGBA",
+        "struct",
+        "structs",
+        "subblock"
+    ],
+    "cmake.configureOnOpen": false
+}

Cargo.toml

@@ -0,0 +1,51 @@
+[package]
+name = "omf"
+version = "0.1.0-beta.1"
+description = "File reader and writer for Open Mining Format."
+authors = ["Tim Evans <[email protected]>"]
+license = "MIT"
+edition = "2021"
+publish = true
+exclude = ["/.github", "/.vscode"]
+
+[dependencies]
+bytes = { workspace = true, optional = true }
+chrono.workspace = true
+flate2.workspace = true
+image = { workspace = true, optional = true }
+parquet = { workspace = true, optional = true }
+schemars.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+zip.workspace = true
+
+[dev-dependencies]
+bytes.workspace = true
+regex.workspace = true
+
+[features]
+default = ["image", "parquet", "omf1"]
+image = ["dep:image"]
+parquet = ["dep:parquet", "dep:bytes"]
+omf1 = ["parquet"]
+
+[workspace]
+members = ["omf-c"]
+
+[workspace.dependencies]
+bytes = "1"
+cbindgen = { version = "0.26", default-features = false }
+chrono = { version = "0.4", default-features = false, features = ["serde"] }
+flate2 = "1.0"
+image = { version = "0.25", default-features = false, features = [
+    "png",
+    "jpeg",
+] }
+parquet = { version = "51", default-features = false, features = ["flate2"] }
+regex = "1"
+schemars = { version = "0.8", features = ["chrono"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["float_roundtrip"] }
+thiserror = "1"
+zip = { version = "2", default-features = false }

README.md

@@ -1,6 +1,16 @@
+[![CI](https://github.com/gmggroup/omf-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/gmggroup/omf-rust/actions/workflows/ci.yml)
+[![Audit](https://github.com/gmggroup/omf-rust/actions/workflows/audit.yml/badge.svg)](https://github.com/gmggroup/omf-rust/actions/workflows/audit.yml)
+
 # OMF
 
-A library for reading a writing files in Open Mining Format 2.0.
+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
 
@@ -28,6 +38,7 @@ plus a wrapper to use that library from C.
     - 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.
@@ -44,3 +55,36 @@ 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](https://www.rust-lang.org/tools/install).
+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](https://www.mkdocs.org/).
+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/`.

docs/build.bat

@@ -0,0 +1,8 @@
+@echo off
+python -m pip install -r requirements.txt || exit /b
+cd ..
+cargo test -p omf --lib -- --ignored update_schema_docs || exit /b
+cargo doc --no-deps || exit /b
+python -m mkdocs build || exit /b
+mv ./target/doc ./site/rust || exit /b
+rm ./site/rust/.lock || exit /b

docs/build.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/sh
+set -e
+python -m pip install -r requirements.txt
+cd ..
+cargo test -p omf --lib -- --ignored update_schema_docs
+cargo doc --no-deps
+python -m mkdocs build
+mv ./target/doc ./site/rust
+rm ./site/rust/.lock