\n\n[![NPM Package][npm]][npm-url]\n[![NPM Package][npm-downloads]][npm-url]\n\n**web-ifc** is a javascript library to read and write ifc files, at native speeds. **web-ifc** is part of the [That Open Company](https://thatopen.com) project, which aims to lower the threshold for developing open BIM applications.\n\n## Install\n\n`npm install web-ifc`\n\n## Quick setup\n\n```JavaScript\nconst WebIFC = require(\"web-ifc/web-ifc-api.js\");\n\n// initialize the API\nconst ifcApi = new WebIFC.IfcAPI();\n\n// initialize the library\nawait ifcApi.Init();\n\n// open a model from data\nlet modelID = ifcApi.OpenModel(/* IFC data as a string or UInt8Array */, /* optional settings object */, );\n\n// the model is now loaded! use modelID to fetch geometry or properties\n// checkout examples/usage for some details on how to read/write IFC\n\n// close the model, all memory is freed\nifcApi.CloseModel(modelID);\n\n```\n\nSee [examples](https://github.com/ThatOpen/engine_web-ifc/tree/main/examples/usage) for more details on how to use web-ifc.\n\n## Current Build\n\nThe current live build of web-ifc is available [here](https://thatopen.github.io/engine_web-ifc/build.zip). Using this allows you to test newest fixes before we make a release. If you wish to use this version then download the zip file and place the contents of the dist folder manually into your node_modules/web-ifc folder. I.e if you are using web-ifc-three then it will be node_modules/web-ifc-three/node_modules/web-ifc. Please note you must replace the javascript and the WASM.\n\n## Requirements\n\nThese are the requirements needed to build web-ifc (only for those that wish to build their own version).\n\n1. Node v16 or later\n2. NPM v7 or later\n3. EMSCRIPTEN v4.0.23 or later\n4. CMAKE v3.18 or later\n\n## Regression Testing\n\nWe have a library of test models in the tests/public folder. If you have a model you would like to contribute please open a PR.\n\nYou can run regression tests on all these models by running `npm run regression`. It will alert you if any of the sample model geometry has changed. If the change is correct you can refresh the regression tests by running `npm run regression-update`.\n\n## Building WASM module\n\n### Setting up emscripten and build system\n\nThe WASM library is built through emscripten, please see [the emscripten installation guide](https://emscripten.org/docs/getting_started/downloads.html) for information on how to set up emscripten. Afterwards `emsdk_env` needs to be in your path.\n\nTo build the WASM you also need CMAKE [see here](https://cmake.org/download/) and (on windows) MINGW [see here](https://sourceforge.net/projects/mingw/) - once installed (and in your path) run `npm run setup-mingw` to configure the environment for web-ifc.\n\n### WASM library\n\nRun `npm install` to install all dependencies.\n\nRun `npm run setup-env` whenever you open a new terminal, this will set up the required emscripten environment variables for you to compile code.\n\nRun `npm run build-release` to build a release version of the wasm binary and the accompanying web-ifc api. It will be placed in `./dist`.\n\nRelease builds enable SIMD, link-time optimization and\n[native WebAssembly exception handling](https://emscripten.org/docs/porting/exceptions.html#webassembly-exception-handling-based-support)\nduring both compilation and linking. Native exception handling reduces the\ncode-size and runtime overhead of C++ exceptions on modern WebAssembly engines.\n\nTo build for an older WebAssembly runtime without native exception support,\nconfigure the existing build directory once before running the same release command:\n\n```sh\nemcmake cmake -S src/cpp -B src/cpp/build_wasm -DEMSCRIPTEN=true -DCMAKE_BUILD_TYPE=Release -DWEB_IFC_WASM_NATIVE_EXCEPTIONS=OFF\nnpm run build-release\n```\n\nThe option applies to the browser, Node and multithreaded targets. It defaults to\n`ON`; setting it to `OFF` uses JavaScript-based exception handling instead. C++\nexception catching remains enabled in both modes. This option does not affect\nnative C++ builds.\n\nIf you wish to build the WASM with debugging enabled you can run `npm run build-debug`. This will enable you to inspect debugging information better when running web-ifc.\n\nRun `npm run dev` to launch a development server with a basic ifc file viewer.\n\n### Build Files\n\nThe output of the build process consts of the following files:\n\n1. web-ifc.wasm - The wasm (compiled C++) to run in the browser\n2. web-ifc-mt.wasm - The wasm (compiled C++) to run in the browser if multi-threading is supported.\n3. web-ifc-node.wasm - The wasm (compiled C++) to run in node\n4. web-ifc-api-node.js - Compiled javascript wrapper for the wasm to run in node.\n5. web-ifc-api-node.d.ts - Typescript definitions for the web-ifc api (for node)\n6. web-ifc-api.js - Compiled javascript wrapper for the wasm to run in browser.\n7. web-ifc-api.d.ts - Typescript definitions for the main web-ifc API\n8. ifc-schema.d.ts - Typescript definitions for the IFC schema\n9. helpers/properties.d.ts - Typescript definitions for the properties aspect of the web-ifc API\n10. helpers/log.d.ts - Typescript definitions for the logger aspect of the web-ifc API\n11. web-ifc-mt.worker.js - Webworker javascript to enable multi-threading in the browser.\n\n## Stand alone C++\n\nAlthough the primary focus of the library is to be used through WebAssembly in the browser/nodejs, the project can be used stand-alone as a c++ library or executable. See [here](https://github.com/ThatOpen/engine_web-ifc/blob/main/src/cpp/test/web-ifc-test.cpp) for a simple entry point to get started.\n\n[npm]: https://img.shields.io/npm/v/web-ifc\n[npm-url]: https://www.npmjs.com/package/web-ifc\n[npm-downloads]: https://img.shields.io/npm/dw/web-ifc\n","readmeFilename":"README.md"}