From 5837b24f7b3880e6de92cb9aef05bb1a2c999a5c Mon Sep 17 00:00:00 2001 From: mie Date: Wed, 11 Nov 2026 01:55:00 +0300 Subject: [PATCH] docs: add DocFX site configuration and GitHub Pages deployment workflow --- .config/dotnet-tools.json | 13 +++++ .github/workflows/docs.yml | 58 +++++++++++++++++++ .gitignore | 4 ++ docfx.json | 27 +++++++++ docs/getting-started.md | 113 +++++++++++++++++++++++++++++++++++++ docs/index.md | 38 +++++++++++++ docs/public-api.md | 44 +++++++++++++++ docs/toc.yml | 13 +++++ 8 files changed, 310 insertions(+) create mode 100644 .config/dotnet-tools.json create mode 100644 .github/workflows/docs.yml create mode 100644 docfx.json create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/public-api.md create mode 100644 docs/toc.yml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 0000000..1490bfb --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.81.0", + "commands": [ + "docfx" + ], + "rollForward": false + } + } +} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..adaab88 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +name: Docs + +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'docfx.json' + - '.config/dotnet-tools.json' + - 'src/IfcIO/**' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/**' + - 'docfx.json' + - '.config/dotnet-tools.json' + - 'src/IfcIO/**' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 + with: + dotnet-version: | + 8.0.x + 10.0.x + - run: dotnet tool restore + - run: dotnet docfx docfx.json --warningsAsErrors + # manifest.json records the build machine paths and is not part of the site. + - run: rm -f _site/manifest.json + - uses: actions/upload-pages-artifact@v5 + with: + path: _site + + deploy: + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index 5202046..be51501 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,7 @@ TestResults/ *.log __pycache__/ *.pyc + +# Documentation site (DocFX output and generated API pages) +_site/ +docs/api/ diff --git a/docfx.json b/docfx.json new file mode 100644 index 0000000..af85fd5 --- /dev/null +++ b/docfx.json @@ -0,0 +1,27 @@ +{ + "metadata": [ + { + "src": [ + { "src": "src/IfcIO", "files": ["IfcIO.csproj"] } + ], + "dest": "docs/api", + "properties": { "TargetFramework": "net10.0" }, + "outputFormat": "apiPage" + } + ], + "build": { + "content": [ + { "src": "docs", "files": ["*.md", "toc.yml", "api/**/*.yml", "api/**/*.md"] } + ], + "resource": [ + { "src": "docs", "files": ["images/**"] } + ], + "output": "_site", + "globalMetadata": { + "_appTitle": "IfcIO", + "_appFooter": "IfcIO is licensed under the MIT License. Not affiliated with buildingSMART.", + "_enableSearch": true + }, + "template": ["default", "modern"] + } +} diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..5e0874a --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,113 @@ +--- +title: Getting started +--- + +# Getting Started with IfcIO + +## Installation + +### NuGet Package + +Install the `IfcIO` library package in your .NET project: + +```bash +dotnet add package IfcIO +``` + +### Global CLI Tool + +Install the `ifcio` command line tool globally: + +```bash +dotnet tool install --global IfcIO.Cli +``` + +--- + +## Quick Examples + +### Reading an IFC File + +```csharp +using IfcIO; + +// Open any .ifc or compressed .ifczip file +var model = IfcModel.Open("Building.ifc"); + +Console.WriteLine($"Project: {model.Project?.Name}"); +Console.WriteLine($"Total elements: {model.Elements.Count}"); + +foreach (var storey in model.Storeys) +{ + Console.WriteLine($"Storey: {storey.Name} (Elevation: {storey.Elevation}m)"); +} +``` + +### Building an IFC4 Model Programmatically + +```csharp +using IfcIO; +using IfcIO.Geometry; + +var model = new IfcModel(IfcSchemaVersion.Ifc4) +{ + ProjectName = "Commercial Office Tower", + Author = "Engineering Team", + Organization = "IOExtend" +}; + +var groundFloor = model.AddStorey("Ground Floor", elevation: 0.0); + +// Add a wall with modern IFC4 mesh tessellation +groundFloor.AddWall("Exterior Wall 1", new IfcMeshGeometry(vertices, indices)); + +// Export to ISO 10303-21 STEP physical file +model.Save("OfficeTower.ifc"); + +// Or save compressed as .ifczip +model.SaveZip("OfficeTower.ifczip"); +``` + +### Exporting to glTF 2.0 (GLB) and Wavefront OBJ + +```csharp +using IfcIO; +using IfcIO.Exporters; + +var model = IfcModel.Open("Building.ifc"); + +// Binary glTF 2.0 for 3D web viewers and game engines +IfcGlbExporter.Export(model, "Building.glb"); + +// Wavefront OBJ +IfcObjExporter.Export(model, "Building.obj"); +``` + +--- + +## CLI Usage + +Run standard operations from your terminal: + +```bash +# Display summary info, schema version, and element counts +ifcio info Building.ifc + +# Convert IFC to binary glTF 2.0 and Wavefront OBJ +ifcio export Building.ifc --glb scene.glb --obj scene.obj + +# Compress IFC to .ifczip +ifcio pack Building.ifc -o Building.ifczip + +# Extract IFC from .ifczip +ifcio unpack Building.ifczip -o Building.ifc + +# Run 3D geometric clash detection with proximity clustering +ifcio clash Arch.ifc Mep.ifc -o Clashes.json --bcf Clashes.bcfzip --group proximity + +# Compare two IFC model revisions (added, deleted, modified) +ifcio diff Baseline.ifc Revision.ifc -o Changes.json --bcf RevisionChanges.bcfzip + +# Validate ISO 10303-21 STEP structure and export BCF issues +ifcio validate Building.ifc --bcf Issues.bcfzip +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a12250d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,38 @@ +--- +title: IfcIO +--- + +# IfcIO + +**IfcIO** is a fast, 100% managed .NET library for building, reading, and exporting **Industry Foundation Classes** (`.ifc`) files compliant with **IFC2x3 Coordination View V2.0** and **IFC4 Design Transfer / Reference View** without third-party dependencies or native code. + +Built clean-room under the [IOExtend](https://github.com/IOExtend) organization as the shared open-standards IFC foundation for AEC/BIM projects (including [NwcIO](https://github.com/IOExtend/NwcIO) and [RvtIO](https://github.com/IOExtend/RvtIO)). + +## Key Features + +- **Full Model Ingestion & Export (`IfcModel`)**: + - Reconstruct complete spatial hierarchy (Project, Site, Building, Storeys), elements, properties, materials, and 3D meshes from any `.ifc` or `.ifczip` file. + - Multi-line STEP statement accumulation and quote-aware tokenization in `StepReader` and high-throughput streaming in `StepWriter`. +- **IFC4 Modern Mesh Tessellation (`IfcTriangulatedFaceSet`)**: + - Encodes geometry using compact `IfcTriangulatedFaceSet` and `IfcCartesianPointList3D` under representation type `'Tessellation'` for IFC4 exports (>60% smaller file sizes than legacy faceted B-Rep). +- **Direct 3D Exporters (glTF 2.0 & Wavefront OBJ)**: + - Instant conversion of any IFC model to binary glTF 2.0 (`.glb`) with PBR metallic-roughness materials and vertex normals, or Wavefront OBJ (`.obj` + `.mtl`). +- **PKZip Compressed IFC (`.ifczip`)**: + - Built-in transparent compression and decompression for standard `.ifczip` archives with zero native dependencies. +- **Cross-Platform CLI Tool (`ifcio`)**: + - Global .NET CLI tool (`IfcIO.Cli` on NuGet) providing `info`, `export`, `pack`, `unpack`, `clash`, `diff`, `view`, and `validate` commands. +- **buildingSMART 22-Character GlobalId (`IfcGuid`)**: + - Standard base64-like buildingSMART encoding (`0-9, A-Z, a-z, _, $`). Bidirectional conversion between 128-bit `.NET Guid` and 22-character IFC GlobalId. +- **3D Geometric Clash Detection & Revision Diff**: + - Built-in Möller triangle collision, proximity clustering, structural grid location assignment, revision comparison, and buildingSMART BCF 2.1 zip reporting. + +The library targets .NET 8 and .NET 10, uses 100% pure managed code with zero native dependencies, and supports Windows, Linux, and macOS. + +## Where to go next + +- [Getting started](getting-started.md): install the package or CLI tool and run a first export or model query. +- [Public API](public-api.md): supported surface and key entry points of the library. +- [API reference](api/IfcIO.yml): complete API documentation generated directly from XML source docstrings. +- [Source on GitHub](https://github.com/IOExtend/IfcIO) and [DeepWiki](https://deepwiki.com/IOExtend/IfcIO) for an automated architectural overview of the repository. + +IfcIO is licensed under the MIT License and is an independent implementation of the ISO 10303-21 STEP and buildingSMART specifications. buildingSMART and IFC are registered trademarks of buildingSMART International Ltd. diff --git a/docs/public-api.md b/docs/public-api.md new file mode 100644 index 0000000..ddb1076 --- /dev/null +++ b/docs/public-api.md @@ -0,0 +1,44 @@ +--- +title: Public API +--- + +# Public API Surface + +The `IfcIO` package is the supported surface listed here. + +## Core Model & Hierarchy + +| Type | Description | +|---|---| +| `IfcModel` | Central model container managing spatial hierarchy (Project, Site, Building, Storey), elements, materials, property sets, and geometry representations. Opens and writes `.ifc` and `.ifczip` files. | +| `IfcElement` | Base BIM product element representing walls, slabs, columns, beams, doors, windows, pipes, ducts, and generic components. | +| `IfcStorey`, `IfcBuilding`, `IfcSite`, `IfcProject` | Spatial structure hierarchy components with coordinates, elevations, and relationships. | +| `IfcGuid` | buildingSMART 22-character compressed GlobalId encoder/decoder with bidirectional conversion to 128-bit .NET `Guid`. | + +## Geometry & Representation + +| Type | Description | +|---|---| +| `IfcMeshGeometry` | 3D polygonal triangle mesh data structure holding double-precision vertices, normals, and face index buffers. | +| `IfcTriangulatedFaceSet` | Modern IFC4 compact tessellation geometry generator (`IfcCartesianPointList3D`). | +| `IfcFacetedBrep` | Standard IFC2x3 faceted boundary representation (`IfcClosedShell`, `IfcFace`, `IfcPolyLoop`). | +| `IfcProfileDef` | 2D parametric profile definitions (rectangle, circle, I-shape, L-shape, composite). | + +## Import & Export + +| Type | Description | +|---|---| +| `StepReader` | Low-level ISO 10303-21 STEP physical file parser supporting multi-line statements and quote escapes. | +| `StepWriter` | High-throughput ISO 10303-21 STEP physical file serializer. | +| `IfcGlbExporter` | Binary glTF 2.0 exporter generating specification-compliant `.glb` files with PBR materials. | +| `IfcObjExporter` | Wavefront OBJ geometry exporter with MTL material library generation. | +| `IfcZipArchive` | Pure managed PKZip container compression and decompression for `.ifczip` files. | + +## Coordination & Validation + +| Type | Description | +|---|---| +| `IfcClashDetector` | Broad-phase spatial index and narrow-phase Möller triangle collision engine for IFC models. | +| `IfcDiffEngine` | Revision comparison engine detecting added, deleted, and modified IFC elements and geometry shifts. | +| `IfcValidator` | Structural STEP syntax and buildingSMART schema conformance validator. | +| `IfcBcfExporter` | buildingSMART BIM Collaboration Format (BCF 2.1 `.bcfzip`) issue and viewpoint generator. | diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..9382dcb --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,13 @@ +- name: Getting started + href: getting-started.md +- name: Guides + href: public-api.md + items: + - name: Public API + href: public-api.md +- name: API reference + href: api/ +- name: GitHub + href: https://github.com/IOExtend/IfcIO +- name: DeepWiki + href: https://deepwiki.com/IOExtend/IfcIO