mirror of
https://github.com/IfcOpenShell/IfcOpenShell.git
synced 2026-09-23 11:32:40 +00:00
Add Bonsai Viewer docs
Create a standalone Sphinx docs tree for Bonsai Viewer and migrate the Autodesk connector Markdown documentation into RST.\n\nGenerated with the assistance of an AI coding tool.
This commit is contained in:
Dion Moult
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@echo ""
|
||||
@echo "You can also do 'make server' to launch html server for previously built html docs."
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
server:
|
||||
python -m http.server 8080 --directory $(BUILDDIR)/html
|
||||
.PHONY: server Makefile
|
||||
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
@import url("https://fonts.googleapis.com/css2?family=Nunito:wght@200;300;400;500;600;700;800&display=swap");
|
||||
@import url('https://fonts.googleapis.com/css2?family=Inconsolata:wght@200;300;400;500;600;700&display=swap');
|
||||
|
||||
h1, h2, h3, h4 {
|
||||
font-weight: normal;
|
||||
color: #7cbf33;
|
||||
background: -webkit-linear-gradient(0deg, #7cbf33, #049344);
|
||||
background-clip: border-box;
|
||||
-webkit-background-clip: text;
|
||||
-webkit-text-fill-color: transparent;
|
||||
}
|
||||
|
||||
a {
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.toc-tree .reference:hover {
|
||||
color: #d98014;
|
||||
}
|
||||
|
||||
.sidebar-brand-text {
|
||||
font-size: 1rem;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.blockbutton {
|
||||
max-width: 500px;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.blockbutton a {
|
||||
display: block;
|
||||
padding-top: 15px;
|
||||
padding-bottom: 15px;
|
||||
border-radius: 5px;
|
||||
background: #40b74c;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
color: #fff;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.blockbutton a:hover {
|
||||
background: #70ba35;
|
||||
}
|
||||
|
||||
.blockbutton a.download code {
|
||||
background: none !important;
|
||||
border: none !important;
|
||||
color: inherit !important;
|
||||
font-family: inherit !important;
|
||||
font-size: inherit !important;
|
||||
font-weight: bold;
|
||||
padding: 0 !important;
|
||||
}
|
||||
|
||||
.highlight .hll {
|
||||
background-color: #ffc2;
|
||||
}
|
||||
|
||||
section img {
|
||||
display: block;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
box-shadow: rgba(0, 0, 0, 0.24) 0px 3px 8px;
|
||||
border-radius: 5px;
|
||||
}
|
||||
|
||||
.location-scene img {
|
||||
display: inline;
|
||||
border-radius: 0px;
|
||||
box-shadow: none;
|
||||
vertical-align: middle;
|
||||
margin-top: -3px;
|
||||
}
|
||||
|
||||
.location-scene p {
|
||||
margin: 0.75rem;
|
||||
}
|
||||
|
||||
.location-scene {
|
||||
border: 1px solid var(--color-admonition-title);
|
||||
background-color: var(--color-admonition-title-background);
|
||||
border-radius: 5px;
|
||||
font-style: italic;
|
||||
color: var(--color-admonition-text);
|
||||
}
|
||||
|
||||
img.transparent {
|
||||
width: auto;
|
||||
height: auto;
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
img.icon {
|
||||
width: auto;
|
||||
height: auto;
|
||||
border-radius: 0px;
|
||||
box-shadow: none;
|
||||
vertical-align: middle;
|
||||
}
|
||||
|
||||
.content figure figcaption>p {
|
||||
font-style: italic;
|
||||
font-size: small;
|
||||
color: #808080;
|
||||
}
|
||||
|
||||
span.menuselection {
|
||||
border: 1px solid var(--color-admonition-title);
|
||||
background-color: var(--color-admonition-title-background);
|
||||
color: var(--color-admonition-text);
|
||||
border-radius: 5px;
|
||||
padding-left: 3px;
|
||||
padding-right: 3px;
|
||||
}
|
||||
|
||||
.toc-cards {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
|
||||
grid-gap: 20px;
|
||||
list-style-type: none;
|
||||
margin-bottom: 24px;
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
|
||||
import os
|
||||
from datetime import datetime
|
||||
|
||||
|
||||
project = "Bonsai Viewer"
|
||||
copyright = f"2020-{datetime.now().year} IfcOpenShell Contributors"
|
||||
author = "IfcOpenShell Contributors"
|
||||
|
||||
cwd = os.path.dirname(os.path.realpath(__file__))
|
||||
with open(os.path.join(cwd, "..", "..", "..", "VERSION"), "r") as f:
|
||||
release = f.read().strip()
|
||||
|
||||
|
||||
extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinx_copybutton"]
|
||||
|
||||
autosectionlabel_prefix_document = True
|
||||
autosectionlabel_maxdepth = 2
|
||||
|
||||
templates_path = []
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
|
||||
|
||||
|
||||
html_theme = "furo"
|
||||
html_static_path = ["_static"]
|
||||
html_css_files = ["custom.css"]
|
||||
|
||||
pygments_style = "one-dark"
|
||||
pygments_dark_style = "one-dark"
|
||||
|
||||
html_favicon = "https://ifcopenshell.org/assets/images/logo.png"
|
||||
html_logo = "https://ifcopenshell.org/assets/images/logo.png"
|
||||
html_theme_options = {
|
||||
"source_repository": "https://github.com/IfcOpenShell/IfcOpenShell/",
|
||||
"source_branch": "v0.8.0",
|
||||
"source_directory": "src/bonsaiviewer/docs/",
|
||||
"light_css_variables": {
|
||||
"color-brand-primary": "#39b54a",
|
||||
"color-brand-content": "#39b54a",
|
||||
"color-brand-visited": "#d9e021",
|
||||
"color-background-primary": "#f7f7f6",
|
||||
"color-background-secondary": "#eeeeec",
|
||||
"color-background-border": "#cfd0cb",
|
||||
"color-foreground-primary": "#2e3436",
|
||||
"color-sidebar-item-background--hover": "#f7f7f6",
|
||||
"color-link": "#39b54a",
|
||||
"color-link--visited": "#39b54a",
|
||||
"color-link--hover": "#d98014",
|
||||
"color-link--visited--hover": "#d98014",
|
||||
"color-admonition-text": "#651fff",
|
||||
"font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji",
|
||||
},
|
||||
"dark_css_variables": {
|
||||
"color-brand-primary": "#39b54a",
|
||||
"color-brand-content": "#39b54a",
|
||||
"color-brand-visited": "#d9e021",
|
||||
"color-background-primary": "#2e3436",
|
||||
"color-background-border": "#2e3436",
|
||||
"color-foreground-primary": "#eeeeec",
|
||||
"color-sidebar-item-background--hover": "#2e3436",
|
||||
"color-link": "#39b54a",
|
||||
"color-link--visited": "#39b54a",
|
||||
"color-link--hover": "#d98014",
|
||||
"color-link--visited--hover": "#d98014",
|
||||
"color-admonition-text": "#EEEEEC",
|
||||
"font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji",
|
||||
},
|
||||
"footer_icons": [
|
||||
{
|
||||
"name": "IfcOpenShell",
|
||||
"url": "https://ifcopenshell.org",
|
||||
"html": """
|
||||
<img src="https://ifcopenshell.org/assets/images/logo.png" style="width: auto;" />
|
||||
""",
|
||||
"class": "",
|
||||
},
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/bonsaiviewer/docs",
|
||||
"html": """
|
||||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
|
||||
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
|
||||
</svg>
|
||||
""",
|
||||
"class": "",
|
||||
},
|
||||
],
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
Autodesk Connector
|
||||
==================
|
||||
|
||||
The Autodesk connector integrates Bonsai Viewer with Autodesk Forma, APS, and
|
||||
Docs. It implements the cloud connector protocol and runs as a separate process
|
||||
that Bonsai Viewer launches and communicates with over standard input and
|
||||
standard output.
|
||||
|
||||
The connector UI is built with CustomTkinter. The Python runtime used for
|
||||
development or packaging must include ``tkinter``. On Gentoo, make sure
|
||||
``dev-lang/python`` is built with ``USE="tk"``.
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
From the repository root:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd src/bonsaiviewer-autodesk
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -e .
|
||||
|
||||
Run
|
||||
---
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
bonsaiviewer-autodesk
|
||||
|
||||
The connector launches without configuration. On first run, open the settings
|
||||
dialog, or set the ``APS_CLIENT_ID`` environment variable, to configure the
|
||||
Autodesk client ID and OAuth callback port.
|
||||
|
||||
For direct protocol testing, send newline-delimited JSON-RPC 2.0 requests on
|
||||
standard input:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{"jsonrpc":"2.0","id":"0","method":"open_settings"}
|
||||
{"jsonrpc":"2.0","id":"1","method":"pull_ifcfed_interactive"}
|
||||
{"jsonrpc":"2.0","id":"2","method":"pull_models","params":[{"display_name":"foo.ifc","id":"abc","source":{"connector":"autodesk","hub_id":"b.hub","project_id":"b.proj","item_id":"urn:adsk...","version_id":"latest"}}]}
|
||||
{"jsonrpc":"2.0","id":"3","method":"push_ifcfed_interactive","params":{"path":"/tmp/project.ifcfed"}}
|
||||
{"jsonrpc":"2.0","id":"4","method":"push_ifcfed","params":{"path":"/tmp/project.ifcfed","manifest":{"connector":"autodesk","hub_id":"b.hub","project_id":"b.proj","item_id":"urn:adsk..."}}}
|
||||
|
||||
Bonsai Viewer is expected to launch this binary once per session and keep it
|
||||
alive until shutdown. Closing the connector's standard input triggers a clean
|
||||
exit.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The connector reads the Autodesk client ID from these places, in order:
|
||||
|
||||
1. ``APS_CLIENT_ID`` environment variable.
|
||||
2. ``settings.json`` in the connector config directory, written by the settings
|
||||
dialog.
|
||||
|
||||
The OAuth callback host is always ``localhost``. The callback port defaults to
|
||||
``8080`` and can be changed in the settings dialog.
|
||||
|
||||
The config directory is platform-specific:
|
||||
|
||||
- Linux: ``~/.config/bonsaiviewer-autodesk/``
|
||||
- macOS: ``~/Library/Application Support/bonsaiviewer-autodesk/``
|
||||
- Windows: ``%APPDATA%\bonsaiviewer-autodesk\``
|
||||
|
||||
OAuth tokens are stored in the OS keychain, keyed by the client ID. Changing
|
||||
the client ID starts a fresh sign-in session. The keychain backend is Secret
|
||||
Service on Linux, Keychain on macOS, and Credential Manager on Windows.
|
||||
|
||||
Cache
|
||||
-----
|
||||
|
||||
The connector owns its own cache. On Linux, resolved files live under:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
~/.cache/bonsaiviewer-autodesk/
|
||||
ifcfeds/<hash>/<name>.ifcfed[.manifest]
|
||||
models/<hash>/<filename>
|
||||
|
||||
Each resolved file is the sole child in its directory so Bonsai Viewer can
|
||||
write sidecar files, such as ``.ifcview``, next to it without colliding. A new
|
||||
resolved model version lands in a fresh ``models/<hash>/`` directory. Old cache
|
||||
directories may be removed manually to clear space.
|
||||
|
||||
Status
|
||||
------
|
||||
|
||||
Implemented:
|
||||
|
||||
- strict JSON-RPC 2.0 host over stdio
|
||||
- APS PKCE sign-in with keyring-backed token storage
|
||||
- hub, project, and folder browsing
|
||||
- ``pull_ifcfed_interactive``, ``pull_ifcfed``, ``pull_models``, and
|
||||
``pull_models_interactive``
|
||||
- ``push_ifcfed_interactive``, ``push_ifcfed``,
|
||||
``push_model_interactive``, and ``push_model``
|
||||
- ``open_settings`` for client ID, callback port, and sign-out
|
||||
- connector-managed cache with one resolved file per directory
|
||||
- adjacent ``.ifcfed.manifest`` files written and read alongside
|
||||
``.ifcfed`` files
|
||||
|
||||
Not implemented:
|
||||
|
||||
- JSON-RPC notifications for progress streaming; the connector shows its own
|
||||
progress dialog
|
||||
- cancellation of in-flight downloads
|
||||
- subdirectory upload layouts inside push destinations
|
||||
@@ -0,0 +1,130 @@
|
||||
Packaging the Autodesk Connector
|
||||
================================
|
||||
|
||||
The Autodesk connector is shipped as a self-contained folder that can be
|
||||
dropped into the Bonsai Viewer connectors directory. PyInstaller bundles the
|
||||
Python interpreter, Qt, and dependencies so end users do not need Python
|
||||
installed.
|
||||
|
||||
PyInstaller does not cross-compile. Each operating system must build its own
|
||||
package, typically through a CI matrix.
|
||||
|
||||
Output
|
||||
------
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
dist/
|
||||
autodesk/
|
||||
connector.json
|
||||
bonsaiviewer-autodesk[.exe]
|
||||
_internal/...
|
||||
autodesk-<os>-<arch>.zip
|
||||
|
||||
The ``autodesk/`` folder is what Bonsai Viewer expects under the
|
||||
``connectors`` directory bundled next to the viewer executable
|
||||
(``<application-dir>/connectors/``).
|
||||
|
||||
Build
|
||||
-----
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd src/bonsaiviewer-autodesk
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -e ".[build]"
|
||||
python packaging/build.py
|
||||
|
||||
On Windows, activate the virtual environment with
|
||||
``venv\Scripts\activate``.
|
||||
|
||||
The build script:
|
||||
|
||||
1. cleans ``dist/`` and ``build/``
|
||||
2. runs PyInstaller against ``packaging/bonsaiviewer-autodesk.spec``
|
||||
3. renames the produced folder to ``autodesk/``
|
||||
4. copies ``connector.json`` into it
|
||||
5. zips the folder as ``autodesk-<os>-<arch>.zip``
|
||||
|
||||
The UI uses Tcl/Tk through CustomTkinter, which keeps the bundle small. Expect
|
||||
roughly 50 MB unpacked or 21 MB zipped per OS. The Python used to build must
|
||||
include ``tkinter``.
|
||||
|
||||
Linux
|
||||
-----
|
||||
|
||||
Build on the oldest glibc you intend to support. Binaries built on a newer
|
||||
glibc will not run on older distributions. Ubuntu 22.04 LTS, with glibc 2.35,
|
||||
is a reasonable lowest common denominator in 2026.
|
||||
|
||||
The runtime keyring backend is Secret Service, such as gnome-keyring or
|
||||
KWallet. End users need a Secret Service provider running.
|
||||
|
||||
Expected output: ``autodesk-linux-x86_64.zip`` and/or an ARM64 archive.
|
||||
|
||||
macOS
|
||||
-----
|
||||
|
||||
Each architecture builds separately. To support Apple Silicon and Intel, build
|
||||
on each architecture and ship two zips, or post-process with ``lipo`` to
|
||||
produce universal binaries.
|
||||
|
||||
The runtime keyring backend is the system Keychain. For distribution outside
|
||||
the developer's machine, codesign the executable and Tcl/Tk dylibs and notarize
|
||||
the bundle. Unsigned binaries trigger Gatekeeper warnings. Codesigning is left
|
||||
to the caller; the spec's ``codesign_identity`` field can be wired up.
|
||||
|
||||
Expected output: ``autodesk-macos-arm64.zip`` and/or
|
||||
``autodesk-macos-x86_64.zip``.
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
Build with the Microsoft Visual C++ runtime available, which is usually true
|
||||
for modern Python distributions. The runtime keyring backend is Credential
|
||||
Manager.
|
||||
|
||||
The executable is built with ``console=True`` because the connector speaks
|
||||
JSON-RPC over stdio. Bonsai Viewer must launch it without showing a console
|
||||
window, for example with Qt's ``QProcess::setCreateProcessArgumentsModifier``
|
||||
and ``CREATE_NO_WINDOW``.
|
||||
|
||||
For distribution, sign the executable with an Authenticode certificate to avoid
|
||||
SmartScreen warnings. Signing is left to the caller.
|
||||
|
||||
Expected output: ``autodesk-windows-x86_64.zip``.
|
||||
|
||||
Install a Built Connector
|
||||
-------------------------
|
||||
|
||||
Extract the zip into the ``connectors`` directory next to the Bonsai Viewer
|
||||
executable.
|
||||
|
||||
Linux:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
unzip dist/autodesk-linux-x86_64.zip -d <application-dir>/connectors/
|
||||
|
||||
macOS:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
unzip dist/autodesk-macos-arm64.zip -d "<application-dir>/connectors/"
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
Expand-Archive dist\autodesk-windows-x86_64.zip -DestinationPath "<application-dir>\connectors\"
|
||||
|
||||
Bonsai Viewer discovers the connector on next launch.
|
||||
|
||||
Out of Scope
|
||||
------------
|
||||
|
||||
- signing and notarization
|
||||
- CI matrix setup
|
||||
- auto-update
|
||||
- universal macOS binaries via ``lipo``
|
||||
@@ -0,0 +1,384 @@
|
||||
Cloud Connector Protocol
|
||||
========================
|
||||
|
||||
Bonsai Viewer can load and save projects and models from cloud platforms
|
||||
through connectors. A connector is a separate application launched by Bonsai
|
||||
Viewer. It handles authentication, browsing, downloads, uploads, caching, and
|
||||
platform-specific behaviour.
|
||||
|
||||
The protocol currently covers:
|
||||
|
||||
- projects: ``.ifcfed``
|
||||
- models: ``.ifc``, ``.rdb``, ``.ifcview``, ``.rdbview``
|
||||
|
||||
Issues, clash results, specifications, and other resources are not yet defined.
|
||||
|
||||
Communication
|
||||
-------------
|
||||
|
||||
Bonsai Viewer launches one connector process per session, on first use, and
|
||||
keeps it alive for the duration of the session. Communication uses
|
||||
newline-delimited JSON-RPC 2.0 over standard input and standard output:
|
||||
|
||||
- requests and responses are single-line JSON objects
|
||||
- every message is terminated by a single newline
|
||||
- the connector must not emit literal newlines inside a JSON message
|
||||
- diagnostics may be written to standard error
|
||||
|
||||
Bonsai Viewer shuts down a connector by closing its standard input. The
|
||||
connector should exit cleanly. If it does not exit within a few seconds, Bonsai
|
||||
Viewer may terminate it.
|
||||
|
||||
Connector Scope
|
||||
---------------
|
||||
|
||||
Bonsai Viewer only works with local files. If a project or model is not local,
|
||||
the viewer asks a connector to resolve it. The connector returns a local path
|
||||
and optional cloud metadata. It must not modify the model file itself.
|
||||
|
||||
The connector handles anything specific to the cloud platform or data source:
|
||||
authentication, browsing, filtering, searches, revision pinning, progress UI,
|
||||
caches, and platform-specific rules. A connector may show its own UI or run
|
||||
without UI.
|
||||
|
||||
Returned files must be the sole child in their directory. This allows Bonsai
|
||||
Viewer to write adjacent sidecars, temporary files, database locks, or helper
|
||||
files without filename collisions. A connector may invalidate cached files by
|
||||
deleting the whole resolved directory. A new cloud revision should resolve to a
|
||||
fresh directory.
|
||||
|
||||
Projects
|
||||
--------
|
||||
|
||||
A project is an ``.ifcfed`` file. It stores project settings and model entries.
|
||||
|
||||
Example project:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"created": "2026-04-29T21:22:36Z",
|
||||
"modified": "2026-04-29T21:22:36Z",
|
||||
"home_view": null,
|
||||
"models": []
|
||||
}
|
||||
|
||||
A cloud-sourced project may have an adjacent ``.ifcfed.manifest`` file storing
|
||||
connector-specific source metadata.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"connector": "mycompany",
|
||||
"version": "2",
|
||||
"url": "https://example.com/project.ifcfed"
|
||||
}
|
||||
|
||||
Models
|
||||
------
|
||||
|
||||
Models are listed in the ``.ifcfed`` file. A model may point to a local path or
|
||||
to a cloud connector source.
|
||||
|
||||
Cloud connector source data is intentionally connector-specific. For example,
|
||||
a connector may store whether a model is pinned to one revision or should
|
||||
always resolve to the latest revision.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"display_name": "foo.ifc",
|
||||
"id": "0503642e-e2f6-4700-87fd-16479542e801",
|
||||
"source": {
|
||||
"connector": "local",
|
||||
"path": "path/to/foo.ifc"
|
||||
}
|
||||
},
|
||||
{
|
||||
"display_name": "bar.ifc",
|
||||
"id": "5fc69e6a-1ff0-4d8a-82c6-2215df53d2ed",
|
||||
"source": {
|
||||
"connector": "autodesk",
|
||||
"version": "1",
|
||||
"hub_id": "b.hub123",
|
||||
"project_id": "b.project456",
|
||||
"item_id": "urn:adsk.wipprod:dm.lineage:abc",
|
||||
"version_id": "urn:adsk.wipprod:fs.file:vf.xyz?version=3"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
Cloud metadata such as filename, cloud ID, revision, and date modified is not
|
||||
specified or stored in the ``.ifcfed``. It is returned by the connector when
|
||||
requested. Bonsai Viewer displays returned cloud metadata as text. The keys
|
||||
``author``, ``revision``, and ``date`` may be shown in more prominent UI
|
||||
locations.
|
||||
|
||||
Open from Cloud
|
||||
---------------
|
||||
|
||||
``pull_ifcfed_interactive`` opens an ``.ifcfed`` from a cloud platform and
|
||||
starts a fresh session.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{ "jsonrpc": "2.0", "id": "0", "method": "pull_ifcfed_interactive" }
|
||||
|
||||
The connector authenticates and lets the user browse or choose a project. It
|
||||
downloads or resolves the ``.ifcfed`` into a connector-managed directory,
|
||||
creates an adjacent ``.ifcfed.manifest``, and returns the local path:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{ "jsonrpc": "2.0", "id": "0", "result": { "path": "/path/to/project/file.ifcfed" } }
|
||||
|
||||
Bonsai Viewer loads the project, then calls ``pull_models`` for cloud-sourced
|
||||
models referenced by the ``.ifcfed``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "1",
|
||||
"method": "pull_models",
|
||||
"params": [
|
||||
{ "display_name": "bar.ifc", "id": "...", "source": { "connector": "autodesk" } }
|
||||
]
|
||||
}
|
||||
|
||||
The connector returns one result per requested model. A result may include
|
||||
optional metadata. ``null`` means that item was skipped or failed without
|
||||
aborting the whole batch.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "1",
|
||||
"result": [
|
||||
{
|
||||
"path": "/path/to/model.ifc",
|
||||
"metadata": { "revision": "B", "date": "2nd Oct 2025" }
|
||||
},
|
||||
null
|
||||
]
|
||||
}
|
||||
|
||||
Downloading the latest version of every model immediately is not required. A
|
||||
connector may download the latest file, use a pinned revision, offer the user a
|
||||
choice, skip a model, or return a cached file. The user can reopen or sync the
|
||||
project later.
|
||||
|
||||
Sync Cloud to Local
|
||||
-------------------
|
||||
|
||||
``pull_ifcfed`` refreshes the cloud-sourced project without prompting the user.
|
||||
It is available when the project has cloud resources: an adjacent
|
||||
``.ifcfed.manifest`` for the project itself, one or more cloud-sourced models,
|
||||
or both.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"method": "pull_ifcfed",
|
||||
"params": {
|
||||
"connector": "mycompany",
|
||||
"version": "2",
|
||||
"url": "https://example.com/project.ifcfed"
|
||||
}
|
||||
}
|
||||
|
||||
The connector returns a local ``.ifcfed`` path and writes a fresh adjacent
|
||||
manifest. Bonsai Viewer then continues by calling ``pull_models`` for
|
||||
cloud-sourced models. The project-refresh phase and model-refresh phase are
|
||||
independent. If no manifest exists, the project refresh phase is skipped and
|
||||
Bonsai Viewer refreshes only cloud-sourced models.
|
||||
|
||||
If the returned ``.ifcfed`` is unchanged from the currently loaded file, Bonsai
|
||||
Viewer may skip the fresh-session reload and continue to model refresh. How
|
||||
"unchanged" is determined, such as byte equality, hash, or modified time, is
|
||||
left to Bonsai Viewer.
|
||||
|
||||
Save Projects to Cloud
|
||||
----------------------
|
||||
|
||||
``push_ifcfed_interactive`` is the cloud equivalent of Save As. It pushes an
|
||||
``.ifcfed`` to a new user-selected cloud location.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"method": "push_ifcfed_interactive",
|
||||
"params": { "path": "/tmp/path/to/project.ifcfed" }
|
||||
}
|
||||
|
||||
The connector uploads the file, writes an adjacent manifest, and returns the
|
||||
resolved local path.
|
||||
|
||||
``push_ifcfed`` is the cloud equivalent of Save. It pushes back to the existing
|
||||
cloud location described by the manifest.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"method": "push_ifcfed",
|
||||
"params": {
|
||||
"path": "/tmp/path/to/project.ifcfed",
|
||||
"manifest": {
|
||||
"connector": "mycompany",
|
||||
"version": "2",
|
||||
"url": "https://example.com/project.ifcfed"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
The connector may update the manifest if the cloud platform returns a new
|
||||
revision or version identifier.
|
||||
|
||||
Add and Save Models
|
||||
-------------------
|
||||
|
||||
``pull_models_interactive`` lets the user choose one or more cloud models to
|
||||
add to the current project.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{ "jsonrpc": "2.0", "id": "0", "method": "pull_models_interactive" }
|
||||
|
||||
The connector returns model entries with ``display_name``, ``source``, a local
|
||||
``path``, and optional metadata:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"result": [
|
||||
{
|
||||
"display_name": "bar.ifc",
|
||||
"source": { "connector": "autodesk" },
|
||||
"path": "/path/to/model.ifc",
|
||||
"metadata": { "revision": "B", "date": "2nd Oct 2025" }
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Bonsai Viewer stores ``display_name`` and ``source`` in the ``.ifcfed`` and
|
||||
loads the model from ``path``. The path and metadata are not stored in the
|
||||
``.ifcfed``.
|
||||
|
||||
``push_model_interactive`` is Save Model As to Cloud:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"method": "push_model_interactive",
|
||||
"params": { "path": "/tmp/path/to/model.ifc" }
|
||||
}
|
||||
|
||||
``push_model`` saves a model back to the existing cloud location described by
|
||||
the model's ``source``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "0",
|
||||
"method": "push_model",
|
||||
"params": {
|
||||
"path": "/tmp/path/to/model.ifc",
|
||||
"source": { "connector": "autodesk", "hub_id": "b.hub123" }
|
||||
}
|
||||
}
|
||||
|
||||
The connector returns an updated ``source`` and optional metadata. Bonsai
|
||||
Viewer replaces the model's ``source`` in the ``.ifcfed``.
|
||||
|
||||
Conflict handling for non-interactive push methods is the connector's
|
||||
responsibility. The connector may overwrite, prompt, reject with a JSON-RPC
|
||||
error, or apply a platform-specific policy.
|
||||
|
||||
Settings and Errors
|
||||
-------------------
|
||||
|
||||
A connector may implement ``open_settings`` for credentials, sign-out, default
|
||||
folders, cache management, or other connector-specific settings.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{ "jsonrpc": "2.0", "id": "0", "method": "open_settings" }
|
||||
|
||||
If a connector returns JSON-RPC ``Method not found`` with code ``-32601``,
|
||||
Bonsai Viewer treats it as having no settings UI.
|
||||
|
||||
The settings result is currently always an empty object. Future revisions may
|
||||
add optional fields, such as a refreshed display label for the connector.
|
||||
|
||||
The connector owns user-facing error handling. Bonsai Viewer understands only:
|
||||
|
||||
- per-item soft failure: ``null`` in a result array
|
||||
- whole-call hard failure: a JSON-RPC error object
|
||||
|
||||
Diagnostic details should be written to standard error for logs.
|
||||
|
||||
Permissions
|
||||
-----------
|
||||
|
||||
Permissions are entirely connector-managed. A federation may contain models
|
||||
from multiple platforms, and some resources may fail while others succeed.
|
||||
Bonsai Viewer tolerates partial failure and does not require all remote models
|
||||
to resolve successfully.
|
||||
|
||||
Discovery
|
||||
---------
|
||||
|
||||
A connector is shipped as a folder containing a ``connector.json`` manifest and
|
||||
an executable entry point.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
<connectors-dir>/
|
||||
autodesk/
|
||||
connector.json
|
||||
bonsaiviewer-autodesk
|
||||
...
|
||||
|
||||
Example ``connector.json``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"id": "autodesk",
|
||||
"name": "Autodesk Forma",
|
||||
"version": "0.1.0",
|
||||
"exec": "./bonsaiviewer-autodesk"
|
||||
}
|
||||
|
||||
Fields:
|
||||
|
||||
- ``id`` is the stable identifier used in ``.ifcfed`` ``source.connector``
|
||||
fields and in ``.ifcfed.manifest`` files.
|
||||
- ``name`` is the human-readable UI label.
|
||||
- ``version`` is informational.
|
||||
- ``exec`` is the connector executable. Relative paths are resolved against the
|
||||
connector folder. On Windows, Bonsai Viewer also tries ``<exec>.exe`` if the
|
||||
path does not exist as written.
|
||||
|
||||
Bonsai Viewer scans the ``connectors`` directory bundled alongside the
|
||||
executable (``<application-dir>/connectors/``).
|
||||
|
||||
Every immediate subdirectory containing ``connector.json`` is treated as a
|
||||
connector. Connectors are launched on demand, not at startup.
|
||||
|
||||
If two folders declare the same ``id``, the first one wins and the other is
|
||||
skipped with a log warning. Malformed manifests or missing executables are
|
||||
reported when relevant without preventing other connectors from loading.
|
||||
@@ -0,0 +1,14 @@
|
||||
Connectors
|
||||
==========
|
||||
|
||||
Bonsai Viewer connectors are separate applications that let the viewer open
|
||||
and save projects or models from cloud platforms. The viewer itself works with
|
||||
local files; a connector resolves cloud resources into local cached files and
|
||||
returns the metadata needed to keep them connected to the cloud source.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
cloud_sync_protocol
|
||||
autodesk
|
||||
autodesk_packaging
|
||||
@@ -0,0 +1,45 @@
|
||||
Learn Bonsai Viewer
|
||||
===================
|
||||
|
||||
Hello world. Bonsai Viewer is a desktop application for opening, federating,
|
||||
and reviewing IFC models.
|
||||
|
||||
It is focused on fast model viewing rather than authoring. It works with IFC
|
||||
files and viewer-oriented formats such as ``.ifcview`` and ``.rdbview``.
|
||||
|
||||
.. only:: builder_html and (not singlehtml)
|
||||
|
||||
.. container:: toc-cards
|
||||
|
||||
.. container:: card
|
||||
|
||||
Getting started
|
||||
Open a model, navigate the scene, and inspect project data.
|
||||
|
||||
.. container:: card
|
||||
|
||||
Large models
|
||||
Use viewer caches and packaged formats for faster loading.
|
||||
|
||||
.. container:: card
|
||||
|
||||
Federation
|
||||
Combine multiple model files into one review session.
|
||||
|
||||
.. container:: card
|
||||
|
||||
:doc:`/connectors/index`
|
||||
Load models from external systems and cloud workflows.
|
||||
|
||||
.. container:: global-index-toc
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Contents
|
||||
:maxdepth: 2
|
||||
|
||||
connectors/index
|
||||
|
||||
Need more help? Join the `live chat <https://osarch.org/chat/>`__ or `community
|
||||
forums <https://community.osarch.org>`__. Something strange happening? Please
|
||||
`report a bug <https://github.com/IfcOpenShell/IfcOpenShell/issues>`__.
|
||||
@@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
@@ -0,0 +1,3 @@
|
||||
sphinx
|
||||
furo
|
||||
sphinx-copybutton
|
||||
@@ -83,7 +83,7 @@ QString userConnectorsDir() {
|
||||
// Linux -> ~/.local/share
|
||||
// macOS -> ~/Library/Application Support
|
||||
// Win -> %APPDATA% (Roaming)
|
||||
// matching CLOUD_SYNC_PROTOCOL.md's listed locations.
|
||||
// matching the Bonsai Viewer connector protocol docs.
|
||||
const QString base = QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation);
|
||||
return QDir(base).filePath("IfcOpenShell/BonsaiViewer/connectors");
|
||||
}
|
||||
|
||||
@@ -35,7 +35,7 @@ struct ConnectorManifest {
|
||||
// otherwise a bare name for PATH lookup at launch
|
||||
};
|
||||
|
||||
// Scans the per-user connectors directory per CLOUD_SYNC_PROTOCOL.md.
|
||||
// Scans the per-user connectors directory per the connector protocol docs.
|
||||
// First match wins for any given id; duplicates and malformed manifests
|
||||
// are skipped with a qWarning. Returned in discovery order so first-wins
|
||||
// is observable to callers.
|
||||
|
||||
Reference in New Issue
Block a user