Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@
the Blender panel makes the preview faces translucent in Revit, to see
the model through them. The edges stay opaque. Applied immediately, no
Sync needed; with an older Blender add-in the preview stays opaque.
- New: **family dimension parameters.** A family baked from Blender carries
`BL_Length`, `BL_Width`, `BL_Height`, `BL_Area` and `BL_Volume` (closed
meshes only) as type parameters, plus `BL_Thickness` when set. Values come
from the object's extent and can be set by hand from an edge or face
selection in the panel, except the volume. Informative only: they do not
drive the geometry and are rewritten at every bake.

## 0.2.0 - 2026-10-10

Expand Down
19 changes: 18 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ failure would have to be treated as terminal.
| `preview_style` | `{type, face, edge, face_alpha?}` | - |
| `proxy_edges` | `{type, obj_id, name, edge_count, arc_count?}` | `edge_count * 6` float32: two endpoints per edge, x y z each; then `arc_count * 9` float32: start, end, mid-angle point per arc |
| `bake_begin` | `{type, obj_ids, target, host?}` | - |
| `bake_mesh` | `{type, obj_id, name, category, matrix, vert_count, face_count, loop_count, tri_count, accept_open, smooth_mesh?}` | positions (vert_count*3 f32) + face_sizes (face_count u32) + face_vertices (loop_count u32) + tri_vertices (tri_count*3 u32) + tri_faces (tri_count u32) |
| `bake_mesh` | `{type, obj_id, name, category, matrix, vert_count, face_count, loop_count, tri_count, accept_open, smooth_mesh?, params?}` | positions (vert_count*3 f32) + face_sizes (face_count u32) + face_vertices (loop_count u32) + tri_vertices (tri_count*3 u32) + tri_faces (tri_count u32) |
| `bake_end` | `{type}` | - |
| `bake_remove` | `{type, obj_ids}` | - |

Expand Down Expand Up @@ -443,6 +443,23 @@ a Sheet (an open mesh already stitched), the polygons that are not exactly
planar fall back to their triangles and the builder runs again; the retry
is kept if it gives a Solid or a Sheet. Same path for the family bake.

**Family dimension parameters.** `params` on `bake_mesh` (absent = none)
is an array of `{name, kind, value}`: `name` is `BL_` followed by letters,
`kind` one of `length`, `area`, `volume`, `value` a finite number >= 0 in
SI units (m, m2, m3). Blender sends `BL_Length` and `BL_Width` (the larger
and smaller of `obj.dimensions` X and Y), `BL_Height` (Z), `BL_Area` (total
surface of the evaluated mesh), `BL_Volume` (only for a closed mesh, never
overridden) and `BL_Thickness` (only when set by hand); every value but the
volume can be set by hand from an edge or face selection, stored frozen on
the object. Only the family bake uses them, and with Bake together only the
host's. Revit writes them as type parameters, group Dimensions, converted
to internal units; it deletes the `BL_` parameters that did not arrive and
never touches parameters without the prefix. The re-bake reloads with
`overwriteParameterValues = false`, so the `BL_` values are also written
on the family's types in the project after the load. The values are
informative: they do not drive the geometry. A malformed `params` is an
`error` for that object.

**Smooth mesh, per object.** `smooth_mesh` on `bake_mesh` (absent =
false) asks the DirectShape bake for a mesh from the start: target
`Mesh`, fallback `Salvage`, no retry. Revit draws a mesh DirectShape
Expand Down
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,11 @@ endorsed by Autodesk or the Blender Foundation.
replaces the previous version; **Remove Bake** deletes what Bilocus
created. A DirectShape can also arrive as a smooth mesh instead of a
solid: see [Smooth meshes or true solids](#smooth-meshes-or-true-solids).
A family also carries `BL_` type parameters (length, width, height, area,
volume, and thickness when set): rough values from the object's extent,
each one but the volume can be set from an edge or face selection in the
panel. They are informative, not linked to the geometry, and rewritten at
every bake.

![A geometry nodes pavilion synced, then baked together into one family](docs/media/geomnodes-sync-blender.gif)

Expand Down
648 changes: 648 additions & 0 deletions docs/superpowers/plans/2026-10-12-family-dimension-parameters.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Family dimension parameters - Design

Date: 2026-10-12
Status: approved in brainstorming, not yet implemented.

## 1. Goal

A shape modeled in Blender and baked as a family reaches Revit as a mute
solid. After this change the family carries a few rough dimensions as
family parameters with the `BL_` prefix, readable on the type in Revit:
length, width, height, thickness, area, volume.

The values are **informative**: they do not drive the geometry (a
`FreeFormElement` cannot flex), and they are rewritten at every bake from
Blender, which stays the source of truth. Whoever reshapes the object must
reassign the overridden values. Scheduling them is up to the user, who can
map them to shared parameters: Bilocus creates plain family parameters.

Out of scope: DirectShape (it has no family parameters), shared
parameters, instance parameters, parameters that drive geometry.

## 2. The parameters

All type parameters, group *Dimensions*, sent in SI units (m, m2, m3) and
converted by Revit to internal units; the project shows them in its own
units.

| Parameter | Automatic value | Override |
|---|---|---|
| `BL_Length` | larger of `obj.dimensions` X, Y | sum of the selected edges |
| `BL_Width` | smaller of `obj.dimensions` X, Y | sum of the selected edges |
| `BL_Height` | `obj.dimensions` Z | sum of the selected edges |
| `BL_Thickness` | none: exists only when overridden | sum of the selected edges |
| `BL_Area` | total surface of the evaluated mesh | sum of the selected faces |
| `BL_Volume` | volume of the evaluated mesh, only if closed (every edge manifold); otherwise not sent | not overridable |

`obj.dimensions` is Blender's own bounding box of the evaluated geometry
(modifiers included) in local axes times the object scale: the same X, Y, Z
the user reads in the N panel. Length and width are ordered by size so that
"length" stays the long side whichever local axis it lies on. Area and
volume are measured on the evaluated mesh with the object's rotation and
scale applied (no translation). Overridden edge and face measures are taken
in world scale too.

With **Bake together** the parameters are the active object's: it already
names, places and identifies the family, and the typical members are LODs
of the same shape, whose volumes must not be summed.

## 3. Blender side

- Overrides are frozen values in meters, m2: object custom properties
`bilocus_param_<name>` (e.g. `bilocus_param_length`). Not recomputed when
the mesh changes.
- Panel, Bake section, box *Family parameters* for the active object: one
row per parameter with the value that will be sent, "auto" or "set",
a button that sets it from the Edit Mode selection (edges for lengths,
faces for area) and an X that clears the override. Volume shows its value
or "open mesh".
- Pure logic (no bpy) in `bridge_bake.py`: the parameter list from
dimensions, area, volume and overrides; the `params` header field.

## 4. Protocol

`bake_mesh` gets an optional `params` field: an array of
`{name, kind, value}`, `kind` one of `length`, `area`, `volume`, `value` a
finite number >= 0 in SI units, `name` starting with `BL_`. Absent means
no parameters. The DirectShape bake ignores it; an older Revit add-in
ignores it too. A malformed `params` is a content error for that object.

## 5. Revit side

- `BakeMeshRequest` parses and validates `params` (pure, tested).
- In the family document, inside the family transaction of both creation
and re-bake: ensure a current family type, add the missing `BL_`
parameters (`FamilyManager.AddParameter`, type parameter, group
Dimensions, spec Length/Area/Volume), set their values in internal units
(`UnitUtils.ConvertToInternalUnits`), and **delete the `BL_` parameters
that did not arrive** (an override cleared, a mesh that opened): stale
data is worse than missing data. Parameters without the `BL_` prefix are
never touched.
- Re-bake reloads with `overwriteParameterValues = false` on purpose (the
user's own values on project types stay): so after the load the `BL_`
values are also written on the family's type in the project, and only
those.

## 6. Testing

- pytest: ordering of length and width, sums, volume only when closed,
override vs automatic, Thickness only when set, `params` in the header
and its validation.
- xUnit: `params` parsing and validation in `BakeMeshRequest`.
- Live via MCP: bake a family, read the `BL_` values on the type; override
thickness from an edge, re-bake, read it; clear it, re-bake, check it is
gone; open mesh -> no `BL_Volume`.
- Docs: DESIGN.md (`bake_mesh` row and paragraph), README (informative
values, family only), CHANGELOG.
14 changes: 11 additions & 3 deletions src/Bilocus.Revit/Bake/BakeMeshRequest.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
// Copyright (c) 2026 Roberto Dolfini

using System;
using System.Collections.Generic;
using Bilocus.Geometry;
using Bilocus.Revit.Proxy;

Expand Down Expand Up @@ -56,8 +57,13 @@ public sealed class BakeMeshRequest
// solid. False if the message does not carry it.
public bool SmoothMesh { get; private set; }

// The BL_ family parameters. Only the family bake writes them, and
// with Bake together only the host's: the members are often LODs of
// the same shape. Never null, empty if the message has none.
public IList<BakeParameter> Parameters { get; private set; }

private BakeMeshRequest(string objectId, string name, string category, float[] matrix,
BakeMeshPayload mesh, bool acceptOpen, bool smoothMesh)
BakeMeshPayload mesh, bool acceptOpen, bool smoothMesh, IList<BakeParameter> parameters)
{
ObjectId = objectId;
Name = name;
Expand All @@ -66,6 +72,7 @@ private BakeMeshRequest(string objectId, string name, string category, float[] m
Mesh = mesh;
AcceptOpen = acceptOpen;
SmoothMesh = smoothMesh;
Parameters = parameters;
}

// The Phase B Parse: AcceptOpen false.
Expand All @@ -88,7 +95,7 @@ public static BakeMeshRequest Parse(string objectId, string name, string categor
// be reported.
public static BakeMeshRequest Parse(string objectId, string name, string category, float[] matrix,
int vertCount, int faceCount, int loopCount, int triCount, byte[] payload, bool acceptOpen,
bool smoothMesh = false)
bool smoothMesh = false, IList<BakeParameter> parameters = null)
{
// Without identity there is neither replacement nor removal:
// better to reject the message than to leave a DirectShape in the
Expand Down Expand Up @@ -133,7 +140,8 @@ public static BakeMeshRequest Parse(string objectId, string name, string categor
// The request stays pending until it is drained: a copy, so a
// caller that reuses its array does not move the object.
return new BakeMeshRequest(
normalizedId, label, category, (float[])matrix.Clone(), mesh, acceptOpen, smoothMesh);
normalizedId, label, category, (float[])matrix.Clone(), mesh, acceptOpen, smoothMesh,
new List<BakeParameter>(parameters ?? new BakeParameter[0]));
}
}
}
62 changes: 62 additions & 0 deletions src/Bilocus.Revit/Bake/BakeParameter.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Roberto Dolfini

using System;

namespace Bilocus.Revit.Bake
{
// One BL_ family parameter of a bake_mesh: a rough dimension of the
// Blender object, informative, written as a type parameter of the
// family. No Revit API in here, so it is checked by the tests;
// FamilyParameters does the writing.
public sealed class BakeParameter
{
public const string Prefix = "BL_";

public string Name { get; private set; }

// "length", "area" or "volume": it picks the Revit spec and unit.
public string Kind { get; private set; }

// SI units, m, m2 or m3 by Kind.
public double Value { get; private set; }

private BakeParameter(string name, string kind, double value)
{
Name = name;
Kind = kind;
Value = value;
}

// Throws ArgumentException on anything a Blender add-on would never
// send: the router turns it into a "bake_mesh: ..." error for that
// object. Letters only after the prefix, because the name becomes a
// family parameter name and the prefix is how stale ones are found.
public static BakeParameter Create(string name, string kind, double value)
{
if (name == null || name.Length <= Prefix.Length
|| !name.StartsWith(Prefix, StringComparison.Ordinal))
{
throw new ArgumentException("parameter name '" + name + "' must start with " + Prefix);
}
for (int i = Prefix.Length; i < name.Length; i++)
{
if (!char.IsLetter(name[i]))
{
throw new ArgumentException(
"parameter name '" + name + "' may only contain letters after " + Prefix);
}
}
if (kind != "length" && kind != "area" && kind != "volume")
{
throw new ArgumentException(
"parameter " + name + ": kind '" + kind + "' is not length, area or volume");
}
if (double.IsNaN(value) || double.IsInfinity(value) || value < 0.0)
{
throw new ArgumentException("parameter " + name + ": value must be a finite number >= 0");
}
return new BakeParameter(name, kind, value);
}
}
}
11 changes: 11 additions & 0 deletions src/Bilocus.Revit/Bake/FamilyBaker.cs
Original file line number Diff line number Diff line change
Expand Up @@ -712,6 +712,10 @@ private ObjectWrite CreateFamily(
{
ProxySchema.Mark(created[i], built[i].ObjectId);
}

// The host's BL_ parameters: with Bake together the
// members are often LODs, their values do not add up.
FamilyParameters.Apply(familyDoc, host.Parameters, familyName);
return null;
});
if (refusal != null) { return ObjectWrite.Refused(refusal); }
Expand Down Expand Up @@ -850,6 +854,9 @@ private ObjectWrite UpdateFamily(BakeMeshRequest host, List<MemberSolid> built,
// what the user added in the editor has no mark.
removedMembers = RemoveOtherMembers(familyDoc, requested);

// Added, updated, and the stale BL_ ones removed.
FamilyParameters.Apply(familyDoc, host.Parameters, familyName);

// For a family the category is changed in place: it
// is always replaced, never recreated (contract).
if (familyDoc.OwnerFamily.FamilyCategoryId != category.Id)
Expand Down Expand Up @@ -881,6 +888,10 @@ private ObjectWrite UpdateFamily(BakeMeshRequest host, List<MemberSolid> built,
string renameNote = null;
string instanceRefusal = TryInTransaction(_project, ObjectTransactionPrefix + host.Name, () =>
{
// The reload above keeps the project's type values on
// purpose: the BL_ ones are written here, and only them.
FamilyParameters.WriteToTypes(_project, target, host.Parameters);

List<ElementId> instances = MarkedInstancesOf(target.Id, host.ObjectId);

if (instances.Count == 1)
Expand Down
Loading
Loading