{"id":16509772,"url":"https://github.com/andrewisen-tikab/three-bcf","last_synced_at":"2025-06-20T21:34:18.091Z","repository":{"id":178620960,"uuid":"661837002","full_name":"andrewisen-tikab/three-bcf","owner":"andrewisen-tikab","description":"A BIM Collaboration Format (BCF) writer for three.js","archived":false,"fork":false,"pushed_at":"2023-10-22T18:58:58.000Z","size":35362,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-06-04T02:23:10.300Z","etag":null,"topics":["bcf","bim","ifc","three-js","threejs"],"latest_commit_sha":null,"homepage":"https://andrewisen-tikab.github.io/three-bcf/example/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewisen-tikab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-03T19:09:26.000Z","updated_at":"2024-12-13T03:23:24.000Z","dependencies_parsed_at":"2023-09-29T15:42:12.189Z","dependency_job_id":"388a998a-9c5e-49a4-b521-1a9537184e37","html_url":"https://github.com/andrewisen-tikab/three-bcf","commit_stats":null,"previous_names":["andrewisen-tikab/three-bcf"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/andrewisen-tikab/three-bcf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewisen-tikab%2Fthree-bcf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewisen-tikab%2Fthree-bcf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewisen-tikab%2Fthree-bcf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewisen-tikab%2Fthree-bcf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewisen-tikab","download_url":"https://codeload.github.com/andrewisen-tikab/three-bcf/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewisen-tikab%2Fthree-bcf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261020561,"owners_count":23098179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcf","bim","ifc","three-js","threejs"],"created_at":"2024-10-11T15:52:22.959Z","updated_at":"2025-06-20T21:34:13.068Z","avatar_url":"https://github.com/andrewisen-tikab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# three-bcf\n\nA BIM Collaboration Format (BCF) writer for three.js\n\n[![PR Checker](https://github.com/andrewisen-tikab/three-bcf/actions/workflows/pr.yml/badge.svg)](https://github.com/andrewisen-tikab/three-bcf/actions/workflows/pr.yml)\n\nthree-bcf is:\n\n-   Simple to use, yet\n-   Highly opinionated\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/example.gif?raw=true\" width=\"100%\" /\u003e\n\n## Getting Started\n\n### Installing\n\n```bash\nnpm install three-bcf\n```\n\nor\n\n```bash\nyarn add three-bcf\n```\n\n### Web Worker\n\n`three-bcf` uses a web worker to create the BCF file.\n\nTo get started, copy the `worker.js` file into your project's public folder.\n\nIn other words:\n\n\u003e `worker.js` should be treated as a static file.\n\nYou can find the file inside the `dist` folder (inside the `node_modules/three-bcf` folder).\n\nOnce added, simply create a new `ThreeBCF` object and reference the worker's path.\n\n#### Example\n\nThe path might look something like this:\n\n```ts\nimport * as BCF from 'three-bcf';\n\nconst workerUrl = 'path/to/worker.js';\n\nconst bcf = new BCF.ThreeBCF({\n    workerURL,\n});\n```\n\n### Checking that the worker is working\n\n`ThreeBCF` will send a message to the worker to check that everything is working as intended.\n\n\u003e THREE.BCF: Sending 'test' message to worker thread\n\nIf everything is working as intended, the worker should respond with:\n\n\u003e THREE.BCF.WORKER: Got test message from main thread. Sending response to main thread\n\nFinally, the main thread should receive the response and tell you that everything is working as intended.\n\n\u003e THREE.BCF: Got message from worker thread. Everything's fine!\n\nIf that works, then you can continue to the next step.\nIf not, then you have configured the worker incorrectly.\n\n## Usage\n\n### Namespaces\n\nThis library uses namespaces to avoid name collisions.\nBegin by importing everything from `three-bcf`.\n\n```ts\nimport * as BCF from 'three-bcf';\n```\n\nThen, use the different namespace to access the different parts of the library.\n\n```ts\nconst topic = new BCF.THREE.Topic();\n```\n\n### Creating a topic\n\nSimply create a topic and add the relevant data (params) to it.\n\n```ts\nconst topic = new BCF.THREE.Topic(); // The topic is empty at this point§\ntopic.set(params);\n\n// Store the topic somewhere.\n// In this case, we store it in an array.\ntopics.push(topic);\n```\n\n### Create a BCF\n\nWhen you are ready to create a BCF file, begin by serializing all topic.\n\n```ts\nconst data = topics.map((topic) =\u003e {\n    topic.toJSON();\n});\n\n// Then, call the createBCF method\nbcf.createBCF({\n    type: 'begin',\n    topics: data,\n});\n```\n\nThis will tell the web worker to create a BCF file.\n\n## Example\n\nA full SPA example can be found in the `example` folder.\nIt's a somewhat complicated three.js scene with React on top of it.\n\nYou don't need to know React, but it helps if you want to understand the code.\nCheck out the `state` folder to see how the data is stored and manipulated.\n\nThe so-called `slice` is a part of `react-redux`, and contains all the bits and pieces needed to create a BCF file yourself.\n\nAlso, you can also try it out here:\n\n[https://andrewisen-tikab.github.io/three-bcf/example/](https://andrewisen-tikab.github.io/three-bcf/example/)\n\n## Docs\n\nAuto-generated docs can be found here:\n[https://andrewisen-tikab.github.io/three-bcf/docs/](https://andrewisen-tikab.github.io/three-bcf/docs/)\n\n## Design Structure\n\nThe following diagram shows the intended design structure of `three-bcf`.\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/design.png?raw=true\" width=\"100%\" /\u003e\n\nThe source of the data should always (!) come from a database or state.\nThis data should be highly serializable!\n\nThe structure of the code mimics this design.\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/structure.png?raw=true\" width=\"100%\" /\u003e\n\n### Core\n\nAt the bottom you'll find the `core`.\nThe `core` namespace is where you find everything related to the core of the library.\nThe core features most of the BCF interfaces as so-called [zod](https://github.com/colinhacks/zod) schemas.\n\nUse parts of this namespace to create your own implementation of the library.\n\n### Three\n\nOn top of the core, you'll find the `three` layer.\n\nAll actions performed on the actual \"BCF data\" should be done in a `three.js` context (!!!).\nThis means that the BIM models used, cameras position, math operations, etc. etc. are done in terms of `three.js` (!!!).\n\nThis layer is a highly opinionated one!\n\n### ThreeBCF\n\nFinally, on top of the three layer, you'll find the `ThreeBCF` layer.\n\nThis layers is the main entry point for the library and is a high-level \"API\" for creating BCF files.\n\nIf this workflow doesn't fit your needs, you can always grab individual parts from each layer use them as you see fit.\n\n## Contributing\n\nModify the code is somewhat complicated. For example, if you want to edit the `core` and add a new property to the BCF file, you need to do the following:\n\n1. Modify the `core`.\n\nUpdate `TopicSchema_Core` found inside `src/core/topic.ts`.\nN.B: The library used `zod` to create a schema for the BCF file.\n\n```ts\nconst TopicSchema_Core = BCFBaseSchema.extend({\n    /**\n     * Comment goes here\n     */\n    newProperty: z.string(),\n});\n```\n\n2. Modify the `three` layer.\n\nUpdate `Topic` found inside `src/three/topic.ts`.\n\nSimply:\n\n-   Add a new property\n-   Update the constructor\n-   Update getters and setters\n-   Update the `check` method(s)\n\n3. Modify the `ThreeBCF` layer.\n\nFinally, navigate to the `createZipAsync` function inside `src/three-bcf/zip.ts`.\nDepending on the type of property you added, you need to update the `factory`.\n\nE.g. `MarkupFactory_XML`.\n\nSimply update the factory's `create` method to use the new property.\n\n```ts\n.up()\n.ele('newProperty')\n.txt(e.newProperty)\n```\n\n4. Update the `example`\n\nFinally, update the `example` to use the new property.\nThis part can be a bit tricky depending on the property you added.\n\nSimply ask for help if you get stuck!\n\n## Dependency Graph\n\nAs stated before, everything consists of three layers.\n\n-   Core\n-   Three\n-   ThreeBCF\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/dependency-graph-01.svg?raw=true\" width=\"100%\" /\u003e\n\nInside each folder, you'll find a `index.ts` file.\nIt should export everything that's is needed from that layer if you want to make your own library.\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/dependency-graph-02.svg?raw=true\" width=\"100%\" /\u003e\n\nThis image below shows the dependency graph of the all the code.\n\n\u003cimg src=\"https://github.com/andrewisen-tikab/three-bcf/blob/dev/resources/dependency-graph-02.svg?raw=true\" width=\"100%\" /\u003e\n\n## Tests\n\nTesting is done locally with `cypress`.\n\n## Status\n\nThis is a work in progress. It's not production ready.\nThere are still a lot of things that needs to be done!\n\n## Remarks\n\nThis uses BCF version 3.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewisen-tikab%2Fthree-bcf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewisen-tikab%2Fthree-bcf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewisen-tikab%2Fthree-bcf/lists"}