Conway

Conway powers Bldrs Share, bringing high-quality, precision CAD to the web. This cutting-edge CAD engine, designed specifically for IFC and STEP formats, offers advanced geometric representation, enabling teams to open and visualize intricate models with exceptional accuracy and speed.

Conway includes two major subcomponents:

• IFC-gen, a mostly autogenerated TypeScript framework (~400kloc) for full API coverage parsing of the IFC 2x3, 4 compliant *.ifc files, and initial support for STEP AP2xx *.step files to support Automotive and 3D-printing applications. This is based on original work by hypar-io/IFC-gen, further developed by bldrs-ai for Conway. The runtime is fully open-source in this project. Please contact us for full access to our generation pipeline.
• conway-geom WASM core, bldrs-ai’s rewrite of web-ifc, engineered for high-performance and to support the full suite of open CAD standards within the IFC and STEP families.

Getting Started

Codex Setup

1. Ignore the below and refer to AGENTS.md.

Windows Setup

1. Install MinGW-64 and add g++.exe location to your PATH variable.

MacOS Setup

1. Install the gmake and node dependencies via Homebrew (brew install gmake node).

EMSDK Setup

1. Clone the EMSDK repo and add it to your path (see their instructions)
2. Conway is using 3.1.72

> cd $EMSDK
> ./emsdk install 3.1.72
> ./emsdk activate 3.1.72
> cd $CONWAY
conway> emcc -v
emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.72 (437140d149d9c977ffc8b09dbaf9b0f5a02db190)
...

Initial Build

Clone the Conway repository, then in the root directory of the repository:

# Make sure EMSDK environment is set up.
yarn setup
yarn build
yarn test

Example Uses

You can now load your IFC files. From the Conway root:

1. yarn browser model.ifc
2. yarn validator model.ifc "IFCWINDOW.OverallHeight <= 1500"

See the full example docs at Browser.md and Validator.md

Development

Update your client with changes since your last sync:

git pull
yarn setup

For the full build of both conway (TypeScript) and conway-geom (WASM subproject):

yarn build

Build just conway, not conway-geom, e.g. for updating just the Conway API or tools:

yarn build-incremental

For a full, clean rebuild:

yarn build-rebuild

You can also run the tests with jest:

yarn test

And finally, using the watch functionality, you can also have the code automatically rebuild on change and also re-run the tests using:

yarn build-test-watch

Production NPM Build

yarn test
yarn build                      # stamps build version string
grep '"version"' package.json   # should see the new version string, 1 more than what the repo shows in GH
npm pack

Push to Production: H3 & Share

The following process works the same for headless-three and Share.

Do H3 first, then Share

cp bldrs-ai-conway-<VERSION>.tgz $H3_DIR
cd $H3_DIR
git fetch upstream # or origin if not on fork
git checkout -b conway-<VERSION> upstream/main
rm bldrs-ai-conway-<OLD VERSION>.tgz
## OLD WAY: yarn remove @bldrs-ai/conway
## OLD WAY: yarn add ./bldrs-ai-conway-<VERSION>.tgz
## New way: edit package.json dep for conway to point to new filename.
yarn install
yarn build && yarn test
yarn serve
# Smoke test local candidate: load all sample models, load local model, exercise dialogs, etc.
git add . ; git ci -m 'Upgrad of conway from <OLD VERSION> to <VERSION>'
git push origin HEAD
# 1) Send PR for review
# 2) On merge, Netlify will detect and build and deploy to prod; watch deploy logs on Netlify
# 3) Smoke test prod.  Same as above
# 4) Post to #bot or #share "New Conway <VERSION> in prod" with linked changelist

IFC Parser Console Test Application

Conway has a test application for parsing IFC step files to see the performance and included entity types at src/core/ifc/ifc_command_line_main.ts.

You can set up an alias to reference the latest package or build from source and use yarn cli:

alias conway='yarn cli'
OR
alias conway='npx --package=@bldrs-ai/conway@latest exec cli'

It can be run with:

conway [ifc file path]
# To output geometry
conway -g [ifc file path]
# Use -m 1024 for larger files

CLI Geometry Output Options

You can now output various geometry formats using the CLI:

conway [ifc file path] [options]

Examples:

• Output all geometry (default GLTF + GLB):

  conway index.ifc --geometry

• Output only GLTF:

  conway index.ifc --geometry --gltf

• Output only GLB:

  conway index.ifc --geometry --glb

• Output GLTF with Draco compression:

  conway index.ifc --geometry --gltf-draco

• Output GLB with Draco compression:

  conway index.ifc --geometry --glb-draco

• Run geometry processing without saving output files:

  conway index.ifc --geometry --nooutput

You can also combine flags as needed. For example:

conway index.ifc --geometry --gltf-draco --glb-draco

Run conway --help for the full list of available flags and options.

The included index.ifc in the repo is recommended for testing.

Profiling WASM Builds in Node

Profiling Conway, including building a Conway-Geom WASM binary with DWARF information and generating a flame graph with WASM symbols, is possible via the following steps:

1. Run build-profile-conway_geom from Conway's package.json
2. Profile your app:

node --prof --experimental-specifier-resolution=node /Users/soar/Documents/GitHub/conway/compiled/src/ifc/ifc_command_line_main.js /Users/soar/Downloads/Schependomlaan.ifc -g

3. An isolate*.log file will be generated. Run:

node --prof-process --preprocess -j isolate*.log > v8.json # generate a V8 log

4. Go to https://mapbox.github.io/flamebearer/ and drop the log file to see a detailed flame graph.

Problems with renaming in GIT merges

Because of the large number of files in conway that are code changes sometimes causing large modifications in merges, especially if generation locations are changed, it's sometimes necessary to up the limit of the number of renames in the git config for merging. It can be done like so:

git config merge.renameLimit 99999

You may also wish to use a low rename threshold no-commit merge strategy for some of these situations to increase likelyhood that files will be related in the merge process and to track some of the more complicated changes:

git merge -X rename-threshold=25 --no-commit

Regression Testing Framework

Conway also has a regression testing framework, which can be run on individual model files in a digest or verbose mode, or as a large batch across several models at the same time. For more details see the documentation.

Release Steps

1. Build Conway with yarn build via the above steps depending on your platform.
2. Run the performance test script, instructions outlined in the performance documentation
3. Run the regression testing batch script, instructions outlined in the regression documentation
4. Run yarn create-release-candidate <major | minor> <GITHUB_PAT>. This package release is by default tagged "latest".
5. Send PR with updated version + benchmarks and await approval.
6. Once approved, Go to GitHub, select the new tagged version, and create a release from it. This means we also have changelogs for patch level releases.
7. Once release has been deployed into Share, tag package as stable.