From 427a0e6d7446ae9556faa80d37b00ce4630519f7 Mon Sep 17 00:00:00 2001
From: Bruno Postle <bruno@postle.net>
Date: Wed, 29 Apr 2026 19:07:53 +0100
Subject: [PATCH] docs: document bcf_viewpoint_to_ifc_url() and
 IfcUrl.to_string()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update SPECIFICATION.md §6 to clarify the isolate-visibility mapping
(DefaultVisibility=false + Exceptions). Add library usage examples to
README for to_string() and bcf_viewpoint_to_ifc_url().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md        | 21 +++++++++++++++++++++
 SPECIFICATION.md |  6 ++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d1656a4..079bf50 100644
--- a/README.md
+++ b/README.md
@@ -234,6 +234,27 @@ png = render(model, selector=url.selector, clips=url.clips or None,
              camera=url.camera, fov=url.fov, visibility=url.visibility)
 ```
 
+Serialise a parsed URL back to a string with `.to_string()`:
+
+```python
+url = IfcUrl.parse("ifc://example.com/org/repo@heads/main?path=model.ifc")
+modified = dataclasses.replace(url, selector="IfcWall", visibility="ghost")
+print(modified.to_string())
+# ifc://example.com/org/repo@heads/main?path=model.ifc&selector=IfcWall&visibility=ghost
+```
+
+Convert a BCF 3.0 REST viewpoint dict to an `ifc://` URL (§6 reverse direction):
+
+```python
+from ifcurl.bcf import bcf_viewpoint_to_ifc_url
+
+base = IfcUrl.parse("ifc://example.com/org/repo@heads/main?path=model.ifc")
+ifc_url = bcf_viewpoint_to_ifc_url(base, viewpoint_dict)
+```
+
+`viewpoint_dict` is a BCF 3.0 REST API viewpoint object (camera, clipping planes,
+component selection/visibility). The repo/ref/path context comes from `base`.
+
 Remote repositories are cloned as bare repos to the OS cache directory (`~/.cache/ifcurl/` on Linux) on first use. Mutable refs (`@heads/`, `@HEAD`) trigger a `git fetch`; immutable refs (commit hashes, tags) use the cache as-is.
 
 For private repositories, configure tokens per host in `~/.config/ifcurl/tokens.json`:
diff --git a/SPECIFICATION.md b/SPECIFICATION.md
index 463bd9e..6f034b1 100644
--- a/SPECIFICATION.md
+++ b/SPECIFICATION.md
@@ -251,8 +251,10 @@ The camera and selection in an IFC URL map directly to BCF viewpoint concepts.
 4. Populate `Components/Selection` with the resolved GUIDs
 
 **BCF viewpoint to IFC URL:**
-1. Extract the GUID list from `Components/Selection`
-2. Construct an IfcOpenShell GUID selector
+1. Extract the GUID list from `Components/Selection`; if `DefaultVisibility`
+   is false, use the GUIDs from `Visibility/Exceptions` instead and set
+   `visibility=isolate`
+2. Construct an IfcOpenShell GUID selector (bare GUIDs joined with `+`)
 3. Convert the BCF camera to `camera`, `fov` or `scale` parameters
 4. Convert clipping planes to `clip` parameters