3d representation

docs/modules/usage/attachments/openapi.yml

@@ -1129,7 +1129,15 @@ paths:
           description: successful operation
   /v0.7.0/draw/<entity>/<name>.<format>:
     get:
-      description: Draw an entity
+      description: 'Draw an entity. For infrastructure, format gltf returns a glTF
+        2.0 JSON scene (model/gltf+json) with a single embedded buffer, one shared
+        unit cube, rack carcass panels, a textured room floor, per-equipment fill
+        and border materials, and node extras
+        for Slurm-web and similar consumers. Honored
+        drawing parameters for gltf: infrastructure.equipment_tags, ghost_unselected,
+        discard_empty_racks, other_racks, rack.u_height, rack.pane_width. Image-only
+        parameters (dimensions, margin, axonometric, colors, labels, pixel_perfect,
+        door_depth) are ignored.'
       parameters:
       - description: Type of entity to draw
         in: path
@@ -1146,7 +1154,7 @@ paths:
         required: true
         schema:
           type: string
-      - description: Format of the generated image
+      - description: Format of the generated image or glTF scene
         in: path
         name: format
         required: true
@@ -1156,6 +1164,7 @@ paths:
           - png
           - svg
           - pdf
+          - gltf
           type: string
       - description: Control if entities are represented perfectly aligned on pixels
           with concession on relative dimensions correctess. This parameter has no
@@ -1445,6 +1454,9 @@ paths:
             image/svg+xml:
               schema:
                 type: string
+            model/gltf+json:
+              schema:
+                type: object
             multipart/form-data:
               schema:
                 format: binary
@@ -1471,7 +1483,15 @@ paths:
                 $ref: '#/components/schemas/Error'
           description: Unable to load drawing parameters schema.
     post:
-      description: Draw an entity
+      description: 'Draw an entity. For infrastructure, format gltf returns a glTF
+        2.0 JSON scene (model/gltf+json) with a single embedded buffer, one shared
+        unit cube, rack carcass panels, a textured room floor, per-equipment fill
+        and border materials, and node extras
+        for Slurm-web and similar consumers. Honored
+        drawing parameters for gltf: infrastructure.equipment_tags, ghost_unselected,
+        discard_empty_racks, other_racks, rack.u_height, rack.pane_width. Image-only
+        parameters (dimensions, margin, axonometric, colors, labels, pixel_perfect,
+        door_depth) are ignored.'
       parameters:
       - description: Type of entity to draw
         in: path
@@ -1488,7 +1508,7 @@ paths:
         required: true
         schema:
           type: string
-      - description: Format of the generated image
+      - description: Format of the generated image or glTF scene
         in: path
         name: format
         required: true
@@ -1498,6 +1518,7 @@ paths:
           - png
           - svg
           - pdf
+          - gltf
           type: string
       - allowEmptyValue: true
         description: Dump equipments and racks coordinates in diagrams. When this
@@ -1539,6 +1560,9 @@ paths:
             image/svg+xml:
               schema:
                 type: string
+            model/gltf+json:
+              schema:
+                type: object
             multipart/form-data:
               schema:
                 format: binary

docs/modules/usage/pages/racksdb.adoc

@@ -289,8 +289,9 @@ This command accepts the following options:
   Name of the entity to represent. This option is required.
 
 [.cli-opt]#*--format*=#[.cli-optval]##_FORMAT_##::
-  File format of the generated image file. Possible values are _png_, _svg_ and
-  _pdf_. Default value is _png_.
+  File format of the generated output. Possible values are _png_, _svg_, _pdf_,
+  and _gltf_ (infrastructure only; see xref:rest.adoc#infrastructure-gltf-export[]).
+  Default value is _png_.
 
 [.cli-opt]#*--parameters*=#[.cli-optval]##_PARAMETERS_##::
   Path to YAML xref:drawparams.adoc[drawing parameters] file. With special value

docs/modules/usage/pages/rest.adoc

@@ -5,6 +5,85 @@ datacenter rooms and infrastructures racks. This REST API is served by
 xref:racksdb-web.adoc[`racksdb-web` command]. This page contains the reference
 documentation of this API.
 
+[[infrastructure-gltf-export]]
+== Infrastructure glTF export
+
+`GET` and `POST` `/v{api-version}/draw/infrastructure/<name>.gltf` return one glTF
+2.0 JSON document (`Content-Type: model/gltf+json`). The binary buffer is embedded as
+a base64 data URI on the single `buffers[0].uri` entry; the document does not reference
+an external `.bin` file. Request bodies and query drawing parameters work the same way
+as PNG draw, including blueprint default drawing parameters merged under the request.
+
+Drawing parameters that only affect 2D images are ignored for glTF:
+`dimensions`, `margin`, `axonometric`, `colors`, labels, label offsets, and
+`pixel_perfect`. Parameters that are honored include
+`infrastructure.equipment_tags`, `infrastructure.ghost_unselected`,
+`infrastructure.discard_empty_racks`, `infrastructure.other_racks`, `rack.u_height`
+(default 44.45 mm), and `rack.pane_width` (default 40 mm). `rack.door_depth` is not
+used as a geometry size.
+
+=== Coordinate system
+
+The scene uses glTF Y-up coordinates in meters (database millimeters are multiplied by
+0.001). +X is the room width axis, +Y is up, and +Z is the room depth axis (the 2D room
+diagram downward axis). Row translation is `(position.width, 0, position.depth)`. The
+database row rotation is clockwise on the floor plan; the row node Y rotation is the
+negation of `position.rotation`. Rack positions along a row follow the same slot-width
+summing as room diagrams (`RoomDrawer`), without elevation `rack.spacing`. After each
+rack node transform, local +Z is the door face (a 180° Y rotation on the rack node
+when `row.reversed` is true).
+
+When an infrastructure spans racks in more than one room, each room is a separate
+scene root with its own rectangular floor slab. Room nodes are placed side by side
+along +X in infrastructure layout order, separated by a fixed 2 m gap. Rows, racks, and
+floor tiles stay in each room's local frame and move with that room's translation.
+
+=== Shared unit cube
+
+The file defines one mesh geometry (unit cube from -0.5 to 0.5 on each axis, with
+normals and texture coordinates). Devices reference it through the `equipment` mesh.
+Scale equal to the object size in meters is set on a mesh child node; the named parent
+node carries translation, rotation, and `extras`, with scale `(1, 1, 1)`.
+
+Each rack carcass is the same cube instanced as panels: left and right side panels
+(`rack.pane_width` thick), plus top and bottom sheets. Local +Z, the door face, and
+the rear stay open. A rack that is not part of the infrastructure (`other_racks`)
+also has a front panel. Panel nodes are unnamed mesh children with `extras.category`
+`rack-part` and `extras.part` (`left`, `right`, `top`, `bottom`, or `front`). The
+rack material is a very dark gray.
+
+The room floor is a thin slab of that cube. Its material embeds
+`racksdb/drawers/assets/floor-tile-solid.png` (`images[0]`, repeat wrap) and
+`KHR_texture_transform` so the tile repeats every 0.6 m across the room. In front of
+each rack door, 0.6 m cells on that same grid use
+`racksdb/drawers/assets/floor-tile-perforated.png` (`images[1]`) on the even checker
+cells of the aisle strip outside the door face. Perforated floor nodes use
+`extras.category` `floor` and `extras.part` `perforated`.
+
+=== Node hierarchy and extras
+
+Hierarchy: `room` → floor and `row` → `rack` → panels and `equipment`. Folded equipment
+names are expanded. `GLTFLoader` copies node `extras` to `object.userData`.
+
+*Equipment* `extras`: `category` (`node`, `storage`, `network`, or `misc`), `type`,
+`tags`, `selected`, `size` `[width, height, depth]` in meters, `rack`, `slot`
+`{"u", "x"}`. Fill and border colors come from glTF materials on the equipment mesh
+children (same drawing `colors.equipments` rules as 2D elevation diagrams:
+`background` / `border` when selected, `ghost` when shown as a ghost). The solid fills
+that size, so neighboring devices touch. A line outline is drawn on the same edges so
+stacked units stay distinct without a gap.
+Depth is the rack depth minus 10 cm, removed at the rear; the front face stays on
+the door.
+
+*Rack* `extras`: `category` `rack`, `type`, `in_infrastructure`, `reversed`, `slots`,
+`size`.
+
+*Row* `extras`: `category` `row`, `reversed`, `rotation` (clockwise degrees as stored).
+
+*Room* `extras`: `category` `room`, `datacenter`, `size` `[width, 0, depth]`.
+
+Runtime state (CPU, RAM, GPU, Slurm status, and similar) is not included in the file.
+
 [subs=attributes]
 ++++
 <script async type="module" src="/_/js/vendor/rapidoc-min.js"></script>

frontend/package.json

@@ -17,6 +17,7 @@
     "@heroicons/vue": "^2.1.1",
     "axios": "^1.6.2",
     "leaflet": "^1.9.4",
+    "three": "^0.186.1",
     "vue": "^3.4",
     "vue-router": "^4.2.4"
   },
@@ -27,6 +28,7 @@
     "@types/jsdom": "^21.1.3",
     "@types/leaflet": "^1.9.8",
     "@types/node": "^18.17.17",
+    "@types/three": "^0.186.0",
     "@vitejs/plugin-vue": "^5.2.3",
     "@vue/eslint-config-prettier": "^8.0.0",
     "@vue/eslint-config-typescript": "^12.0.0",