---
name: treble-geometry-components
description: Furnish rooms with the Treble SDK's geometry component library (tsdk.geometry_component_library, GeometryDefinition, add_geometry_component, populate_with_geometry_components, GeometryComponentPlacement) instead of hand-building objects. Use whenever a request adds furniture or other objects (tables, chairs, desks, sofas, shelves, loudspeakers, boxes) to a room, furnishes a library or generated room, or randomizes object placement across many rooms.
---

# Treble SDK: geometry components

Follow AGENTS.md (https://sdk-docs.treble.tech/agent-instructions/AGENTS.md) as well; this skill adds to it and does not replace it.

**API reference**:
- Geometry component library and placement: https://sdk-docs.treble.tech/api/core/treble_tsdk.core.geometry_component_library.html
- `GeometryDefinition`: https://sdk-docs.treble.tech/api/geometry/treble_tsdk.geometry.geometry_definition.html
- `GeometryComponentGenerator` / `GeometryDefinitionGenerator`: https://sdk-docs.treble.tech/api/geometry/treble_tsdk.geometry.generator.html

**How-to documentation**:
- https://docs.treble.tech/treble-sdk/how-to/room-simulations/room-geometry/create-components — exploring the library, adding, moving and removing components, transforms, generators
- https://docs.treble.tech/treble-sdk/tutorial/room-simulations/creating-furnished — a furnished room end to end
- https://docs.treble.tech/treble-sdk/how-to/working-at-scale/generate-random-rooms — random furniture across many generated rooms

With the Treble MCP server connected, open these links with `docs_fetch` and confirm names and
signatures with `api_lookup`.

## Use the library first

- For furniture and objects inside a room, use the geometry component library instead of building boxes or meshes yourself.
- List the groups with `tsdk.geometry_component_library.get_groups_with_count()` (or `get_group_names()`), then pick components with `query(group=..., name=...)` or `get_by_id(id)`.
- Only build objects with `treble.GeometryComponentGenerator` (boxes, planes, loudspeakers) when no library component fits, and tell the user when you substitute. To reuse an object from a geometry library room, extract it with `GeometryComponentGenerator.create_component_from_model(model, component_name, layer_names=[...])`.

## Steps

1. Get a `treble.GeometryDefinition` to hold the components. Start from a generator result (e.g. `treble.GeometryDefinitionGenerator.create_shoebox_room(...)`), or wrap an existing room with `treble.GeometryDefinition(model)` (a geometry library room, a `ModelObj`, or a `.3dm` path).
2. Place components:
   - One at a time: `geo_def.add_geometry_component(name, component, treble.Transform3d(treble.Point3d(x, y, z), treble.Rotation(azimuth)))`. Pass `snap_layer_name=` to sit it flush against a surface such as the floor.
   - Scattered: `geo_def.populate_with_geometry_components([treble.GeometryComponentPlacement(components=[...], preferred_count=n, snap_layer_name=...)])`. Use `rotation_settings=treble.ComponentAnglePool([...])`, `min_dist_from_objects=` and `min_dist_from_walls=` to control orientation and clearance.
3. Upload with `project.add_model(name, geo_def)` (or `project.add_models_bulk(...)` for many rooms), then `model.wait_for_model_processing()`.
4. Components bring their own layers, so assign a material to every entry in the processed `model.layer_names`, as AGENTS.md *Materials* describes.

## Pitfalls

- Component names must be unique within a `GeometryDefinition`; use `move_geometry_component`, `set_geometry_component_transform` or `remove_geometry_component` to change an existing one rather than adding it again.
- `preferred_count` is the preferred number of instances, not a guarantee: the SDK makes up to 100 random placement attempts per requested instance and can skip one if none passes its placement checks. Check the result (`geo_def.plot()`) before uploading many rooms.
- Keep sources and receivers out of furniture: after the model is processed, run `sim_def.remove_invalid_sources()` / `remove_invalid_receivers()` as usual.