Usage

Usage¶

In a Jupyter Notebook¶

To display an OpenStudio model in a Jupyter notebook:

import openstudio
from effibemviewer import create_example_model, display_model

# model = openstudio.model.exampleModel()
# This helper creates a model with an incorrectly oriented surface and two stories
model = create_example_model(include_geometry_diagnostics=True)
display_model(
    model=model,
    height="500px",
    use_iframe=False,
    include_geometry_diagnostics=False,
    cdn=False,  # Set to True for better caching on re-runs
)

Parameters:

Parameter	Type	Default	Description
`model`	`openstudio.model.Model`	required	The OpenStudio model to display
`height`	`str`	`"500px"`	CSS height value for the viewer
`use_iframe`	`bool`	`False`	Use IFrame for nbclassic compatibility
`include_geometry_diagnostics`	`bool`	`False`	Show geometry diagnostic controls
`cdn`	`bool`	`False`	Load JS/CSS from CDN (better caching on re-runs)

Note

use_iframe=True is only needed if you are using jupyter nbclassic (not notebook V7 or lab)

Note

OpenStudio, as of 3.11.0, does NOT export geometry diagnostics in GLTF. This feature requires a patched version.

Generate Standalone HTML¶

To generate a standalone HTML file programmatically:

from effibemviewer import model_to_gltf_html
from pathlib import Path

html = model_to_gltf_html(model)
Path("viewer.html").write_text(html)

Parameters:

Parameter	Type	Default	Description
`model`	`openstudio.model.Model`	required	The OpenStudio model to render
`height`	`str`	`"100vh"`	CSS height value
`pretty_json`	`bool`	`False`	Format JSON with indentation
`include_geometry_diagnostics`	`bool`	`False`	Include geometry diagnostic info
`embedded`	`bool`	`True`	Inline JS/CSS in HTML
`cdn`	`bool`	`False`	Reference JS/CSS from jsDelivr CDN

Command Line Interface¶

Generate an HTML viewer from the command line:

usage: python -m effibemviewer [-h] [-m MODEL] [-g] [-o OUTPUT]
                               [--embedded | --cdn] [--pretty] [--loader]

Generate GLTF viewer HTML from OpenStudio model

options:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to the OpenStudio model file (optional, defaults
                        to an example model)
  -g, --geometry-diagnostics
                        Include geometry diagnostics (convex, correctly
                        oriented, etc.)
  -o OUTPUT, --output OUTPUT
                        Output HTML file path (default: viewer.html)
  --embedded            Embed JS library inline in HTML (default: generate
                        separate effibemviewer.js file)
  --cdn                 Reference JS library from CDN instead of embedding or
                        generating local file
  --pretty              Pretty-print the JSON output in the HTML (default:
                        compact JSON)
  --loader              Generate a loader HTML with file input instead of
                        embedding model data

Basic Usage¶

Generate a viewer with an OpenStudio model:

$ python -m effibemviewer --model mymodel.osm --output viewer.html

When --model is omitted, it uses a built-in example model:

$ python -m effibemviewer --output viewer.html

Options¶

Option	Description
`-m, --model PATH`	Path to OpenStudio model file (.osm)
`-o, --output PATH`	Output HTML file path (default: `viewer.html`)
`-g, --geometry-diagnostics`	Include geometry diagnostic controls
`--pretty`	Pretty-print JSON in the HTML output

Library Mode Options¶

By default, the CLI generates a separate effibemviewer.js and effibemviewer.css file alongside the HTML. You can change this behavior:

Option	Description
`--embedded`	Inline JS/CSS directly in the HTML file
`--cdn`	Reference JS/CSS from jsDelivr CDN (no local files needed)

Note

--embedded and --cdn are mutually exclusive.

Examples:

# Generate with external local files (default)
$ python -m effibemviewer -m model.osm -o viewer.html
# Creates: viewer.html, effibemviewer.js, effibemviewer.css

# Generate with embedded JS/CSS (single file, larger but portable)
$ python -m effibemviewer -m model.osm -o viewer.html --embedded
# Creates: viewer.html (self-contained)

# Generate with CDN references (smallest file, requires internet)
$ python -m effibemviewer -m model.osm -o viewer.html --cdn
# Creates: viewer.html (loads JS/CSS from cdn.jsdelivr.net)

Loader Mode¶

Generate an HTML page with a file input for loading local GLTF files, instead of embedding model data:

$ python -m effibemviewer --loader --output loader.html

This is useful for creating a standalone viewer that users can use to load their own GLTF files. No OpenStudio installation is required for loader mode.

# Loader with CDN (minimal deployment - just one HTML file)
$ python -m effibemviewer --loader --cdn --output loader.html