Running in the browser¶
goifc runs in a browser as two WebAssembly files that share one JSON contract:
goifc-build.wasmbuilds walls, the walls of a room, and slabs from numbers. One request holds a whole plan; the answer has the quantities, the faces, a GLB of the meshes and, on request, the SVG preview.goifc-read.wasmreads an IFC file. The answer has the import tree, a GLB and the parts you ask for.
Each runs in a Web Worker, so the page stays responsive. Load the reader only when someone opens a file: an editor that only drafts never downloads it. The numbers are the same as the Go library's: CI runs the whole contract suite compiled to WebAssembly and checks it gives the same bytes.
Get the files¶
Every release has six files:
| File | What it is |
|---|---|
goifc-build.wasm |
The builders (about 1.2 MB gzipped) |
goifc-read.wasm |
The IFC reader (about 1.2 MB gzipped) |
wasm_exec.js |
Go's WebAssembly loader, for the Go version that built them |
goifc.js |
The worker API below |
goifc-contract.schema.json |
The request and answers as JSON Schema |
SHA256SUMS |
Checksums of the five files above |
Check them before you serve them. First prove SHA256SUMS came from the
release workflow, run on the tag's commit; then check the other five files
against it:
tag=v0.19.0
gh attestation verify SHA256SUMS --repo blox-eng/goifc \
--signer-workflow blox-eng/goifc/.github/workflows/release.yml \
--source-digest "$(gh api "repos/blox-eng/goifc/commits/$tag" --jq .sha)"
sha256sum -c SHA256SUMS
Checking SHA256SUMS alone proves nothing: anyone who changes a file can
write new sums. Each of the six files has its own attestation too, so the
same gh attestation verify works on any one of them. Keep the six files
in one folder, and serve .wasm as Content-Type: application/wasm.
Build walls and slabs¶
import { createBuilder } from "/static/goifc/goifc.js";
const builder = await createBuilder({ base: "/static/goifc/" });
const { answer, glb } = await builder.build({
slabs: [{ id: "s1", outline: [[0, 0], [5, 0], [5, 4], [0, 4]], z: 0, thickness: 0.2 }],
});
answer is:
{
"goifcVersion": "v0.19.0",
"ok": true,
"walls": [],
"slabs": [
{
"id": "s1",
"quantities": { "area": 20, "perimeter": 18, "volume": 4 },
"top": {
"origin": [0, 0, 0], "u": [1, 0, 0], "v": [0, 1, 0], "normal": [0, 0, 1],
"outline": [[0, 0], [5, 0], [5, 4], [0, 4]],
"openings": []
}
}
]
}
glb is an ArrayBuffer: load it with any glTF loader. Each element is a
node named by its element id.
A request has three lists, walls, rooms and slabs, and preview.
Each item's fields are the Go builder's parameters (see
Building from numbers), in meters:
- wall:
id,edge(two[x, y]points),base,height,thicknessorlayers,side("left"or"right"),openings,joins. - room:
id,outline(the closed outline's points),base,height,thicknessorlayers,side,openings(one list per outline edge;nullor[]for none). - slab:
id,outline,z(the top),thicknessorlayers. - opening:
offset,sill,width,height, anddepthfor a niche (0 or left out cuts through). - join:
end("a"foredge[0],"b"foredge[1]) andwall, the id of the wall the end meets mid-wall: a wall item ("w1") or a room wall ("r1/2"). A wall has at most one join per end.
Give thickness or layers, never both. A field the contract does not
know is refused, so a typo never builds something different. Set
"preview": true to get answer.preview.svg, the
SVG preview of the whole plan.
Element ids¶
An id is 1 to 64 letters, digits or _ . : -, unique in the request.
Each built element gets an id from it:
| Item | Element ids |
|---|---|
| wall | w1 |
| wall in layers | w1/0, w1/1, … (measured face first) |
| room | r1/0, r1/1, … (wall i runs from point i to point i+1) |
| room in layers | r1/0/0, r1/0/1, … (wall, then layer) |
| slab | s1 |
| slab in layers | s1/0, s1/1, … (top first) |
Walls that meet mid-wall¶
A partition's end that meets another wall's face (a T) is declared in the
partition's joins. goifc cuts the end flush with the face and takes the
strip it covers off that face's net area. The through wall's
measuredJoins and otherJoins hold the area taken off its measured and
opposite faces, and measuredNet and otherNet already exclude it.
{
"walls": [
{ "id": "T", "edge": [[0, 0], [4, 0]], "base": 0, "height": 2.5, "thickness": 0.2, "side": "left" },
{ "id": "P", "edge": [[2, 3], [2, 0]], "base": 0, "height": 2.5, "thickness": 0.1, "side": "left",
"joins": [{ "end": "b", "wall": "T" }] }
]
}
Here T's measuredJoins is 0.25 and its measuredNet 9.75.
answer.walls lists the walls of walls and rooms, in request order;
answer.slabs lists the slabs.
three.js's GLTFLoader removes [ ] . : / from node names, so w1/0
loads as w10. Read the element id from node.userData.name: it keeps
the name as the GLB has it.
Read an IFC file¶
import { createReader } from "/static/goifc/goifc.js";
const reader = await createReader({ base: "/static/goifc/" });
const { answer, glb } = await reader.read(file); // a File, Blob, ArrayBuffer or Uint8Array
By default the answer has nodes, and glb holds the meshes. Ask for
more with include:
| Part | What it holds |
|---|---|
nodes |
The project, site, storeys and elements, parents first. Each has its class, name, quantities and where they came from, net area, material, type and bounding box. parentIndex points at an earlier node, null for the root. |
glb |
The meshes. Each node is named by the element's GlobalId. |
psets |
Each element's property sets, by the element's GlobalId. Storeys and other spatial nodes are not included. |
storeyPlans |
Each storey's floor plan outlines. |
typeLayers |
The layer build-up of each type, by type GlobalId. |
A part you did not ask for is absent from the answer. A value the file
does not have is null, never 0. answer.warnings lists what goifc could
not read, for example an element with no geometry.
When something is refused¶
A refused request has "ok": false and lists every geometry refusal at once.
A malformed field (a null or missing value, a join with no end or wall,
a thickness of 0, or both thickness and layers) is reported alone,
before any geometry runs:
{
"goifcVersion": "v0.19.0",
"ok": false,
"errors": [
{ "code": "overlaps", "item": "w1", "wall": 0, "opening": 1, "message": "wall 0 opening 1: overlaps" },
{ "code": "above_wall", "item": "w1", "wall": 0, "opening": 2, "message": "wall 0 opening 2: above_wall" }
]
}
item is the id you gave. wall is the outline edge (0 for a wall item)
and opening the index in its openings. A refused join has item (the
partition) and join, the index in its joins, instead of wall and
opening:
Match on code; message is for a person.
| Code | What to do |
|---|---|
too_wide |
The opening reaches or passes an end of the wall. Make it narrower, or move it in. |
overlaps |
The opening touches or overlaps an earlier one. Move them apart. |
above_wall |
The opening reaches or passes the top of the wall. Lower its sill or height. |
in_corner |
The opening cuts into a corner join of the room. Move it away from the corner. |
layer_sliver |
A niche's back lies under 1 mm from a layer boundary. Put it on the boundary or further from it. |
in_join |
The opening overlaps or touches a strip a partition's join covers on that face. Move it away from the join. |
unknown_wall |
A join names no wall or room wall of the request, or the partition itself. Check the wall id. |
not_on_face |
The joined end is not on a face of the wall it names, or the partition runs into the wall. Move the end onto the face, or turn the partition. |
too_shallow |
The two walls meet at under 15° or over 165°. Change the angle. |
off_wall |
The strip the partition covers leaves the face. Move the partition in from the wall's ends or edges. |
joins_overlap |
The strip overlaps or touches an earlier strip on the same face. Move the partitions apart. |
invalid_input |
The request or an item is malformed. message names the field. |
invalid_ifc |
The file is not IFC goifc can read. message says why. |
too_large |
A limit is exceeded. message names the size and the limit. |
nothing_to_draw |
The preview had no elements. Add one, or leave preview out. |
worker_failed |
From goifc.js only: the worker died, for example out of memory. The next request starts a fresh worker. |
goifc.js rejects its Promise, without asking the worker, with an Error
whose code is:
worker_failedwhen the worker died or was closed;too_largefor a file over the read limit;invalid_inputwhenreadgets something that is not a file, or anincludethat is not an array of part names.
Every other refusal is an answer with "ok": false.
Limits¶
- A build request: 16 MiB of JSON, 10,000 items and 100,000 elements (each layer and each room wall counts). Each item keeps the Go builders' limits.
- An IFC file: 48 MiB. Reading takes about 35 times the file's size in memory, and a browser tab gives WebAssembly at most 4 GiB. Read bigger files with the Go library on a server.
Versions¶
Every answer carries goifcVersion. The contract follows goifc's version:
a breaking change to it is a breaking goifc release. Load goifc.js,
wasm_exec.js and both .wasm files from the same release.