Embed a plan: `<bldg-viewer>`

One tag shows a bldg plan in any web page: a blog post, a client portal, your docs. Floor plan, reflected ceiling plan, roof plan, elevations, sections and 3D, drawn by the same engine as the editor. Free to embed on any site, commercial ones included (bldg Viewer License), no account, no server of ours: the plan stays where you put it.

<script type="module" src="https://cdn.jsdelivr.net/npm/@usebldg/viewer@0.1.0/dist/bldg-viewer.js"></script>
<bldg-viewer src="house.bldg.json"></bldg-viewer>

That is the whole embed: the plan of the lowest level, with a small switcher (Plan, 3D and the level). This one reads the demo house's plan file:

Drag to pan, Ctrl (⌘) + scroll to zoom, double-click to fit; click or tap a room, door or window for its details. On a touch screen: pinch to zoom, two fingers to move the plan (one finger still scrolls the page until you have zoomed in), double-tap to fit. Open the demo house in the editor.

One tag, one view

The attributes pick the view; tabs picks the switcher's buttons, or none at all for a figure.

Attribute	Values	Default
`src`	a plan (`.bldg.json`) or a viewer file (`.viewer.json`, below); or put either inside the tag in a `<script type="application/json">`
`view`	`plan` · `rcp` (the Ceiling tab: the reflected ceiling plan) · `roof` (the Roof tab) · `3d` · `elevation` · `section`	`plan`
`level`	a level id (plan and RCP)	the lowest level
`elevation`	`N` · `S` · `E` · `W`, or an elevation view's id	`S`
`section`	a section view's id	the first section
`camera`	`sw` · `se` · `ne` · `nw` (the 3D view from that side, looking down at the building) · `top`	framed from the south-east
`tabs`	a comma list of the views above, or `none`: no switcher, a static figure	`plan,3d` (and the view asked for)
`engine`	the folder holding the engine (`dist/engine/`), for a plan source when it is not beside the script (a bundler)	beside the script

<bldg-viewer src="house.viewer.json" view="3d"
  camera="sw" tabs="plan,elevation,3d"></bldg-viewer>

<bldg-viewer src="house.viewer.json"
  view="elevation" elevation="S" tabs="none"></bldg-viewer>

Plans, elevations and sections are SVG drawings (light, sharp at any zoom, selectable text). three.js and the 3D view load only when 3D is shown.

A plan file or a viewer file

A plan (house.bldg.json, the file the editor's Save writes) is drawn in the browser by the bldg engine, WebAssembly fetched once from beside the script (about 3 MB gzipped). Edit the plan, reload the page, the views follow.

A viewer file (house.viewer.json) holds every view already drawn: each level's plan and ceiling plan, the roof plan, the elevations, the sections and the 3D model. No engine is fetched; the demo house's is 378 kB, 50 kB gzipped. Make one in the editor: Share ▾ › Embed in a web page… › Download viewer file (Pre-drawn, the default). Make it again after the plan changes.

Offline: one HTML file

The editor's Embed › Download offline HTML writes one file that opens by double-click, with no network and no server: the viewer file and the viewer itself inline (no WebAssembly). Send it to a client by email; it shows the plan, the elevations and the 3D view. The demo house as an offline file (1.1 MB, 249 kB gzipped).

From the editor

In the editor, Share ▾ › Embed in a web page… shows the tag for the view on screen (its tab, level, side or section, and the 3D camera's nearest preset), with Copy, the plan or viewer file to put beside your page, and Download offline HTML. Share keeps the view too: the link it copies opens on the same tab, level and camera.

Sizes

File (npm package `@usebldg/viewer`, `dist/`)	Raw	gzip	Loaded
`bldg-viewer.js`	50 kB	18 kB	always
`bldg-viewer-3d.js` (three.js)	684 kB	179 kB	the first time 3D is shown
`engine/bldg_wasm_bg.wasm`	8.8 MB	2.9 MB	only for a plan (`.bldg.json`) source
`bldg-viewer.standalone.js`	731 kB	197 kB	offline files carry it inline

Details

Keyboard and screen readers. The switcher is a tab list (arrow keys, Home, End); each drawing is an image named after the plan and the view; the 3D canvas takes the arrows (orbit), + and − (zoom), F (fit) and Enter (the piece in the middle, in words). Motion stops under reduce motion.
Size. 440 px high by default; set your own (style="height:600px"). A static drawing (tabs="none") takes the drawing's own proportions.
With a bundler. Add the npm package @usebldg/viewer to your site, then import "@usebldg/viewer". Viewer files work as they are. A plan source needs the engine, which bundlers do not copy: copy node_modules/@usebldg/viewer/dist/engine/ to your public folder and set engine="/engine/" on the tag, or use viewer files.
Content-Security-Policy. A viewer file needs only the script's origin in script-src (and the file's in connect-src); the viewer's styles are constructed stylesheets, which style-src allows. A plan source also runs the engine (WebAssembly) in a worker made from a blob: add 'wasm-unsafe-eval' to script-src, worker-src blob:, and the engine's origin in script-src and connect-src.
Safe with files you did not make. A viewer file's drawings are cleaned before they are shown: drawing elements only, no script, event handlers, links or outside addresses. A page may show viewer files its users upload.
Events. bldg-load, bldg-view (the view shown, in the attributes' words) and bldg-error; element.show({view: "3d", camera: "nw"}) switches from script.
Open in bldg. When the source carries the plan, the switcher links to the editor, read-only, on the same view. The plan travels in the link's # part, which browsers do not send to the server.
The drawings are the engine's: what the plan stores, nothing inferred. Code checks are not shown here; in the editor they are an aid, not an approval.
Licence. The viewer and the engine it loads are free to use and embed on any website, commercial ones included, under the bldg Viewer License; the npm package carries the same text and the notices of what it bundles (three.js, the engine's Rust libraries).

bldg · Editor · Editor guide · Viewer · Format · Benchmarks · Limitations · Terms · Privacy · hello@usebldg.com

Embed a plan: <bldg-viewer>