├── LICENSE ├── README.md └── specification └── 1.0 ├── README.md └── assets ├── README.md ├── binary-sdtf-content.png ├── sdTF_spec_example.ghx ├── sdTF_spec_example.png └── sdTF_spec_example.sdtf /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 ShapeDiver GmbH 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # sdTF 2 | Specification of the Structured Data Transfer Format 3 | 4 | sdTF (Structured Data Transfer Format) is a specification for the efficient transfer and loading of trees of data items as used by parametric 3D modeling software like [Grasshopper®](https://www.grasshopper3d.com/). 5 | sdTF borrows concepts from [glTF](https://github.com/KhronosGroup/glTF) and encodes data items, the tree structure used to organize these items, and optional attributes attached at different levels of the tree. 6 | Storage of the tree structure and attributes is kept separate from the serialized data items, allowing for efficient exploration and partial fetching of data stored in sdTF assets. 7 | Data items may be stored as primitives (numbers, booleans, strings), JSON encoded, or binary in arbitrary file formats. Binary file buffers may be kept separate or bundled together with the tree structure into a single binary asset. 8 | sdTF is extensible at various levels, e.g. by adding support for further file formats or primitive data types. 9 | 10 | # Specification 11 | 12 | Please provide spec feedback by submitting [issues](https://github.com/shapediver/sdTF/issues). Ask general questions about sdTF in the [ShapeDiver forum](https://forum.shapediver.com/). 13 | 14 | * [sdTF specification 1.0](specification/1.0/README.md) 15 | 16 | # Reference implementations 17 | 18 | * [SDK for JavaScript / TypeScript / node.js](https://www.npmjs.com/package/@shapediver/sdk.sdtf-v1) 19 | * SDK for .NET (available on request, will be published in Q4 2022) 20 | -------------------------------------------------------------------------------- /specification/1.0/README.md: -------------------------------------------------------------------------------- 1 | ![version](https://img.shields.io/badge/version-1.0-blueviolet.svg) 2 | 3 | The Structured Data Transfer Format (sdTF) is an API-neutral exchange and storage format for trees of data items as used by parametric 3D modeling software like [Grasshopper®](https://www.grasshopper3d.com/). 4 | 5 | Last Updated: March 17, 2021 6 | 7 | Editors 8 | 9 | * Alexander Schiftner, [ShapeDiver](https://www.shapediver.com) 10 | * Emil Poulsen, [CORE studio](http://core.thorntontomasetti.com/) 11 | * Matthias Reisacher, [ShapeDiver](https://www.shapediver.com) 12 | 13 | Copyright (C) 2020-2021 ShapeDiver GmbH. All Rights Reserved. 14 | 15 | # Contents 16 | 17 | * [Introduction](#introduction) 18 | * [Motivation](#motivation) 19 | * [Basics](#basics) 20 | * [Design goals](#design-goals) 21 | * [Versioning](#versioning) 22 | * [File extensions and MIME types](#file-extensions-and-mime-types) 23 | * [Concepts](#concepts) 24 | * [Asset](#asset) 25 | * [Nodes](#nodes) 26 | * [Chunks](#chunks) 27 | * [Data items](#data-items) 28 | * [Buffers](#buffers) 29 | * [Bufferviews](#bufferviews) 30 | * [Accessors](#accessors) 31 | * [Attributes](#attributes) 32 | * [Type hints](#type-hints) 33 | * [A complete example](#a-complete-example) 34 | * [Binary sdTF file format specification](#binary-sdtf-file-format-specification) 35 | * [Magic](#binary-sdtf-magic) 36 | * [Version](#binary-sdtf-version) 37 | * [Total length](#binary-sdtf-total-length) 38 | * [Content length](#binary-sdtf-content-length) 39 | * [Content format](#binary-sdtf-content-format) 40 | * [Content string](#binary-sdtf-content-string) 41 | * [Binary](#binary-sdtf-binary) 42 | * [Properties reference](#properties-reference) 43 | * [accessor](#reference-accessor) 44 | * [attributes](#reference-attributes) 45 | * [attributevalue](reference-attributevalue) 46 | * [buffer](#reference-buffer) 47 | * [bufferview](#reference-bufferview) 48 | * [chunk](#reference-chunk) 49 | * [fileinfo](#reference-fileinfo) 50 | * [item](#reference-item) 51 | * [node](#reference-node) 52 | * [sdTF (root object)](#reference-sdTF) 53 | * [typehint](#reference-typehint) 54 | 55 | 56 | 57 | # Introduction 58 | 59 | sdTF makes it possible to store and exchange trees of data items as used by parametric 3D modelling software in an efficient and extensible way, independent of software vendors. 60 | 61 | ## Motivation 62 | 63 | Chaining applications based on parametric 3D modelling requires an open, efficient, and easily extensible data format for exchange of complex data structures. sdTF aims to close this gap. 64 | 65 | ## Basics 66 | 67 | sdTF stores data items like primitives, 3D objects, images, PDF documents, as well as metadata about them: 68 | 69 | * the tree structure used to organize data items 70 | * optional attributes attached to data items 71 | 72 | The metadata is stored in JSON format, while data items may either be embedded into the metadata (typically used for primitive data items), or stored in binary buffers which are referenced from the metadata (3D objects, images, documents, arrays of numbers, other blobs). Metadata and binary buffers may either be kept in separate files, or merged into a single [_binary sdTF_](#binary-sdtf-file-format-specification). 73 | 74 | ## Design goals 75 | 76 | sdTF has been designed with the following goals in mind: 77 | 78 | * _Lazy loading, separate fetching of metadata and data items_: sdTF allows for the metadata to be fetched and inspected without loading binary data. Fetching of individual data items is possible using HTTP range requests, without downloading a complete asset. 79 | * _Independence from specific runtimes_: sdTF does not depend on closed source libraries. 80 | * _Extensibility_: The sdTF asset format specification is openly available and allows for extensions in many ways. As an example support for further formats for serialisation of data items can easily be added. The specification itself allows for extensions while keeping backwards compatibility. 81 | 82 | ## Versioning 83 | 84 | Any updates made to sdTF in a minor version will be backwards and forwards compatible. Backwards compatibility will ensure that any client implementation that supports loading a sdTF 1.x asset will also be able to load a sdTF 1.0 asset. Forwards compatibility will allow a client implementation that only supports sdTF 1.0 to load sdTF 1.x assets while gracefully ignoring any new features it does not understand. 85 | 86 | A minor version update can introduce new features but will not change any previously existing behavior. Existing functionality can be deprecated in a minor version update, but it will not be removed. 87 | 88 | Major version updates are not expected to be compatible with previous versions. 89 | 90 | ## File extensions and MIME types 91 | 92 | * `*.sdtf` for _binary sdTF_, MIME type `model/vnd.sdtf` 93 | * `*.jsdtf` for JSON sdTF (metadata only), MIME type `model/vnd.sdtf+json` 94 | * `*.bin` for binary buffers referenced from metadata, MIME type `application/octet-stream` 95 | 96 | # Concepts 97 | 98 | sdTF metadata is stored in JSON format. This section describes the concepts used for the properties representing the metadata in JSON. A flat hierarchy is used, using numeric indices for refering between child items of top level attributes. 99 | 100 | ## Asset 101 | 102 | This property must exist in any sdTF. It contains information about versioning, and optional information about the author and copyright. 103 | 104 | ### Example: minimal sdTF 105 | 106 | ``` 107 | { 108 | "asset": { 109 | "generator": "ShapeDiverSdtfWriter", 110 | "copyright": "Author of sdTF asset", 111 | "version": "1.0" 112 | } 113 | } 114 | ``` 115 | 116 | ## Nodes 117 | 118 | Trees in sdTF are made of nodes. Nodes can reference other `nodes` and/or data `items`. They can have an optional `name`, optional `attributes`, and an optional `typeHint`. 119 | Due to the flat hierarchy it's theoretically possible to create circular structures of nodes, but that's discouraged. 120 | 121 | ### Example: Node referencing data items 122 | 123 | A node element of the [type](#reference-typehint) specified at typeHint[2], consisting of 13 elements. 124 | 125 | ``` 126 | { 127 | "name": "[0,0]", 128 | "items": [3, 4, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14], 129 | "typeHint": 2 130 | } 131 | ``` 132 | 133 | ### Example: Node referencing other nodes 134 | 135 | A node element of the [type](#reference-typehint) specified at typeHint[0], referencing [nodes](#reference-node) that are defined at nodes[0] and nodes[1]. 136 | 137 | ``` 138 | { 139 | "name": "57e60008-ee18-4864-8711-1cbc8adfc821", 140 | "nodes": [0, 1], 141 | "typeHint": 0, 142 | "attributes": 1 143 | } 144 | ``` 145 | 146 | ## Chunks 147 | 148 | Chunks use the same schema as nodes, the only difference being that they provide the entry points to the sdTF. 149 | Typically every chunk corresponds to a separate tree structure. 150 | 151 | Example: In case we are storing several Grasshopper data trees in a sdTF, each data tree becomes a chunk. 152 | The first level of nodes below a chunk corresponds to the branches of the tree. Each such node references a list of data items. 153 | 154 | ## Data items 155 | 156 | Data items serve as the leaves of trees defined by nodes. The actual data may be embedded directly, or a reference to an accessor. Data items can have optional attributes. 157 | 158 | ### Example: Item embedding a value 159 | 160 | ``` 161 | { 162 | "value": 42.0, 163 | "typeHint": 2 164 | } 165 | ``` 166 | 167 | ### Example: Item referencing an accessor 168 | 169 | An item representing some binary data, that is stored inside of a [buffer](#reference-buffer), by referencing an [accessor](#reference-accessor) element. 170 | 171 | ``` 172 | { 173 | "accessor": 0, 174 | "typeHint": 0 175 | } 176 | ``` 177 | 178 | ## Buffers 179 | 180 | Buffers are used to story binary data, imagine them as a concatenation of individual files (in fact: bufferviews). A single sdTF can reference multiple buffers. The actual data of a buffer can reside 181 | 182 | * in a external binary file referenced by an uri, 183 | * embedded into the JSON metadata by means of a data uri, or 184 | * appended directly to the JSON metadata in case of a [_binary sdTF_](#binary-sdtf-file-format-specification). 185 | 186 | ### Example: External buffer 187 | 188 | Uris to external buffers are resolved relative, absolute uris can be used but are discouraged. 189 | 190 | ``` 191 | { 192 | "byteLength": 1234, 193 | "uri": "buffer.bin" 194 | } 195 | ``` 196 | 197 | 198 | ### Example: Attached buffer (binary sdTF) 199 | 200 | In case of binary sdTF the first buffer in the list refers to the directly attached one, hence it only uses the `byteLength` property. 201 | 202 | ``` 203 | { 204 | "byteLength": 2358119 205 | } 206 | ``` 207 | 208 | ## Bufferviews 209 | 210 | A bufferview is a pointer to a portion of a buffer, it references a file or simply some binary data (e.g. a large list of numbers, or a large string). 211 | The `byteOffset` and `byteLength` define the location of the bufferview inside the buffer. 212 | 213 | ### Example: Bufferview for a 3dm file 214 | 215 | ``` 216 | { 217 | "buffer": 0, 218 | "byteOffset": 0, 219 | "byteLength": 5164, 220 | "contentType": "model/vnd.3dm", 221 | "contentEncoding": "gzip" 222 | } 223 | ``` 224 | 225 | ### Example: Image 226 | 227 | The accessor references a complete bufferview (in this case an image file). 228 | 229 | ``` 230 | { 231 | "bufferView": 0 232 | } 233 | ``` 234 | 235 | ### Example: Bufferview for an image file 236 | 237 | ``` 238 | { 239 | "buffer": 0, 240 | "byteOffset": 0, 241 | "byteLength": 2073, 242 | "contentType": "image/png" 243 | } 244 | ``` 245 | 246 | ## Accessors 247 | 248 | Accessors reference individual objects inside bufferviews. What they are referencing depends on the type of bufferview. In some cases they reference a complete bufferview. 249 | 250 | ### Example: Geometric object in a 3dm file 251 | 252 | Referencing an individual object located in [bufferViews[0]](#reference-buffer) via its id. 253 | 254 | ``` 255 | { 256 | "bufferView": 0, 257 | "id": "64b723b9-2712-4f4e-a7ef-9c34cbf68289" 258 | } 259 | ``` 260 | 261 | ## Attributes 262 | 263 | Attributes are stored as dictionaries. They can be referenced by nodes, chunks, and data items. Attribute values can be directly embedded, or reference accessors. 264 | 265 | ### Example 266 | 267 | ``` 268 | { 269 | "Name": { 270 | "value": "Mesh sphere", 271 | "typeHint": 3 272 | }, 273 | "Color": { 274 | "value": "126, 156, 255", 275 | "typeHint": 4 276 | }, 277 | "Layer": { 278 | "value": "Some layer", 279 | "typeHint": 3 280 | }, 281 | "Preview": { 282 | "accessor": 3, 283 | "typeHint": 1 284 | } 285 | } 286 | ``` 287 | 288 | ## Type hints 289 | 290 | Type hints are used to add information about the type of data items found below a specific node in the tree. They are also used for data items, allowing to know 291 | about the type without reading binary data. 292 | 293 | ### Example 294 | 295 | ``` 296 | { 297 | "typeHints": [{ 298 | "name": "rhino.mesh" 299 | }, { 300 | "name": "image" 301 | }, { 302 | "name": "double" 303 | }, { 304 | "name": "string" 305 | }, { 306 | "name": "color" 307 | }, { 308 | "name": "guid" 309 | }] 310 | } 311 | ``` 312 | # A complete example 313 | 314 | The following example shows the metadata of an sdTF asset containing 3 trees: 315 | 316 | * a tree called _Mesh_ containing two branches with one mesh each (one of the meshes has attributes attached) 317 | * a tree called _Images_ containing a single branch with a single image 318 | * a tree called _Numbers_ containing two branches which are lists of numbers 319 | 320 |

321 | 322 |

323 | 324 | You can download [the complete binary sdTF asset](assets/sdTF_spec_example.sdtf) and the [Grasshopper model that was used to create it (requires ShapeDiver plugin >= 2.0)](assets/sdTF_spec_example.ghx). 325 | 326 | ``` 327 | { 328 | "asset": { 329 | "generator": "ShapeDiverSdtfWriter", 330 | "version": "1.0" 331 | }, 332 | "chunks": [ 333 | { 334 | "attributes": 1, 335 | "name": "57e60008-ee18-4864-8711-1cbc8adfc821", 336 | "nodes": [ 0, 1 ], 337 | "typeHint": 0 338 | }, 339 | { 340 | "attributes": 2, 341 | "name": "c641e0f8-ecfd-4607-936f-01ed06ac7dbd", 342 | "nodes": [ 2 ], 343 | "typeHint": 1 344 | }, 345 | { 346 | "attributes": 3, 347 | "name": "fc5cedb5-42c0-4238-ae01-9cf94d194130", 348 | "nodes": [ 3, 4 ], 349 | "typeHint": 2 350 | } 351 | ], 352 | "nodes": [ 353 | { 354 | "items": [ 0 ], 355 | "name": "[0,0]", 356 | "typeHint": 0 357 | }, 358 | { 359 | "items": [ 1 ], 360 | "name": "[0,1]", 361 | "typeHint": 0 362 | }, 363 | { 364 | "items": [ 2 ], 365 | "name": "[0]", 366 | "typeHint": 1 367 | }, 368 | { 369 | "items": [ 3, 4, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 ], 370 | "name": "[0,0]", 371 | "typeHint": 2 372 | }, 373 | { 374 | "items": [ 4, 5, 6, 7, 15, 16, 9, 17, 18, 19, 20 ], 375 | "name": "[0,1]", 376 | "typeHint": 2 377 | } 378 | ], 379 | "items": [ 380 | { 381 | "accessor": 0, 382 | "attributes": 0, 383 | "typeHint": 0 384 | }, 385 | { 386 | "accessor": 1, 387 | "typeHint": 0 388 | }, 389 | { 390 | "accessor": 2, 391 | "typeHint": 1 392 | }, 393 | { 394 | "typeHint": 2, 395 | "value": 0 396 | }, 397 | { 398 | "typeHint": 2, 399 | "value": 1 400 | }, 401 | { 402 | "typeHint": 2, 403 | "value": 2 404 | }, 405 | { 406 | "typeHint": 2, 407 | "value": 3 408 | }, 409 | { 410 | "typeHint": 2, 411 | "value": 5 412 | }, 413 | { 414 | "typeHint": 2, 415 | "value": 8 416 | }, 417 | { 418 | "typeHint": 2, 419 | "value": 13 420 | }, 421 | { 422 | "typeHint": 2, 423 | "value": 21 424 | }, 425 | { 426 | "typeHint": 2, 427 | "value": 34 428 | }, 429 | { 430 | "typeHint": 2, 431 | "value": 55 432 | }, 433 | { 434 | "typeHint": 2, 435 | "value": 89 436 | }, 437 | { 438 | "typeHint": 2, 439 | "value": 144 440 | }, 441 | { 442 | "typeHint": 2, 443 | "value": 7 444 | }, 445 | { 446 | "typeHint": 2, 447 | "value": 11 448 | }, 449 | { 450 | "typeHint": 2, 451 | "value": 17 452 | }, 453 | { 454 | "typeHint": 2, 455 | "value": 19 456 | }, 457 | { 458 | "typeHint": 2, 459 | "value": 23 460 | }, 461 | { 462 | "typeHint": 2, 463 | "value": 27 464 | } 465 | ], 466 | "attributes": [ 467 | { 468 | "Name": { 469 | "typeHint": 3, 470 | "value": "Mesh sphere" 471 | }, 472 | "Color": { 473 | "typeHint": 4, 474 | "value": "126, 156, 255" 475 | }, 476 | "Layer": { 477 | "typeHint": 3, 478 | "value": "Some layer" 479 | }, 480 | "Preview": { 481 | "accessor": 3, 482 | "typeHint": 1 483 | } 484 | }, 485 | { 486 | "Id": { 487 | "typeHint": 5, 488 | "value": "57e60008-ee18-4864-8711-1cbc8adfc821" 489 | }, 490 | "Name": { 491 | "typeHint": 3, 492 | "value": "Mesh" 493 | }, 494 | "Type": { 495 | "typeHint": 3, 496 | "value": "Mesh" 497 | } 498 | }, 499 | { 500 | "Id": { 501 | "typeHint": 5, 502 | "value": "c641e0f8-ecfd-4607-936f-01ed06ac7dbd" 503 | }, 504 | "Name": { 505 | "typeHint": 3, 506 | "value": "Images" 507 | }, 508 | "Type": { 509 | "typeHint": 3, 510 | "value": "GrasshopperBitmap" 511 | } 512 | }, 513 | { 514 | "Id": { 515 | "typeHint": 5, 516 | "value": "fc5cedb5-42c0-4238-ae01-9cf94d194130" 517 | }, 518 | "Name": { 519 | "typeHint": 3, 520 | "value": "Numbers" 521 | }, 522 | "Type": { 523 | "typeHint": 3, 524 | "value": "Number" 525 | } 526 | } 527 | ], 528 | "typeHints": [ 529 | { 530 | "name": "rhino.mesh" 531 | }, 532 | { 533 | "name": "image" 534 | }, 535 | { 536 | "name": "double" 537 | }, 538 | { 539 | "name": "string" 540 | }, 541 | { 542 | "name": "color" 543 | }, 544 | { 545 | "name": "guid" 546 | } 547 | ], 548 | "accessors": [ 549 | { 550 | "bufferView": 0, 551 | "id": "d16103f1-f64f-4dd6-9d87-924520d554cd" 552 | }, 553 | { 554 | "bufferView": 0, 555 | "id": "e2bb8f80-5df3-41a4-b6ad-ce5e71f2bd06" 556 | }, 557 | { 558 | "bufferView": 1 559 | }, 560 | { 561 | "bufferView": 2 562 | } 563 | ], 564 | "bufferViews": [ 565 | { 566 | "buffer": 0, 567 | "byteLength": 11590, 568 | "byteOffset": 0, 569 | "contentEncoding": "gzip", 570 | "contentType": "model/vnd.3dm" 571 | }, 572 | { 573 | "buffer": 0, 574 | "byteLength": 2172131, 575 | "byteOffset": 11592, 576 | "contentType": "image/png" 577 | }, 578 | { 579 | "buffer": 0, 580 | "byteLength": 173507, 581 | "byteOffset": 2183724, 582 | "contentType": "image/png" 583 | } 584 | ], 585 | "buffers": [ 586 | { 587 | "byteLength": 2357231 588 | } 589 | ] 590 | } 591 | 592 | ``` 593 | 594 | 595 | # Binary sdTF file format specification 596 | 597 | The binary sdTF file consists of three parts: 598 | 599 | - a 20 byte long binary header describing the contents of the binary sdTF file (little endian). 600 | - a content string: the metadata as described in section [Concepts](#concepts). 601 | - a binary blob attached at the end of the file, containing the data of the first buffer referenced from the metadata (see [Example: Attached buffer (binary sdTF)](#example-attached-buffer-binary-sdtf)). 602 | 603 | See section [A complete example](#a-complete-example) to download a sample binary sdTF file, and see below for a diagram and descriptions of the individual parts. 604 | 605 | ![Binary sdTF Content](assets/binary-sdtf-content.png) 606 | _Visual representation of the different parts of the sdTF file_ 607 | 608 | The following sections describe each part in more detail. 609 | 610 | 611 | ### Magic 612 | A 4 byte ASCII encoded string “sdTF“ representing an identifier of the binary sdTF file type. It can be used to identify a file as binary sdTF. 613 | 614 | 615 | ### Version 616 | A 4 byte uint indicating the version of the binary sdTF format (currently 1). This version is relevant for the binary format and how to deconstruct the other parts. 617 | 618 | 619 | ### Total length 620 | A 4 byte uint representing the total length of the binary sdTF file. 621 | 622 | 623 | ### Content length 624 | A 4 byte int representing the total length of the content string. 625 | 626 | 627 | ### Content format 628 | A 4 byte uint indicating an identifier for the content string format. 0 for JSON. 629 | 630 | 631 | ### Content string 632 | A string of arbitrary length describing the metadata of the sdTF asset. In the case of JSON (i.e. if the [content format](#binary-sdtf-content-format) indicates 0), this will be UTF8 encoded. See section [Concepts](#concepts) for detailed information and section [A complete example](#a-complete-example) to see an example json. 633 | 634 | 635 | ### Binary 636 | Contains the data of the first buffer referenced from the metadata (see [Example: Attached buffer (binary sdTF)](#example-attached-buffer-binary-sdtf)). 637 | 638 | # Properties reference 639 | 640 | * [accessor](#reference-accessor) 641 | * [attributes](#reference-attributes) 642 | * [attributevalue](#reference-attributevalue) 643 | * [buffer](#reference-buffer) 644 | * [bufferview](#reference-bufferview) 645 | * [chunk](#reference-chunk) 646 | * [fileinfo](#reference-fileinfo) 647 | * [item](#reference-item) 648 | * [node](#reference-node) 649 | * [sdTF (root object)](#reference-sdTF) 650 | * [typehint](#reference-typehint) 651 | 652 | 653 | --------------------------------------- 654 | 655 | ### accessor 656 | 657 | Accessors reference individual objects inside bufferviews. What they are referencing depends on the type of bufferview. In some cases they reference a complete bufferview. 658 | 659 | **Properties** 660 | 661 | | |Type|Description|Required| 662 | |---|----|-----------|--------| 663 | |**bufferView**|`integer`|Id of the referenced bufferview.|:white_check_mark: Yes| 664 | |**id**|`string`|Id of the referenced object inside the bufferview.|No| 665 | 666 | Additional properties are allowed. 667 | 668 | #### accessor.bufferView :white_check_mark: 669 | 670 | Id of the referenced bufferview. 671 | 672 | * **Type**: `integer` 673 | * **Required**: Yes 674 | * **Minimum**: ` >= 0` 675 | 676 | #### accessor.id 677 | 678 | Id of the referenced object inside the bufferview. Used to reference individual objects in files that contain multiple objects. 679 | The meaning of this id is specific to the content type of the bufferview (the file type). 680 | May be omitted in case the complete bufferview shall be referenced, e.g. in case of image files. 681 | 682 | * **Type**: `string` 683 | * **Required**: No 684 | 685 | 686 | 687 | --------------------------------------- 688 | 689 | ### attributes 690 | 691 | Attributes are stored as dictionaries, mapping an arbitrary number of attribute names to their values, where the values are represented as [attributevalue](#reference-attributevalue). 692 | 693 | **Properties** 694 | 695 | | |Type|Description|Required| 696 | |---|----|-----------|--------| 697 | |name of attribute as `string`|[`attributevalue`](#reference-attributevalue)|An [`attributevalue`](#reference-attributevalue) object, representing the attribute's value.|No| 698 | 699 | Each property of an `attributes` object corresponds to a key-value pair, further properties are not allowed. 700 | 701 | 702 | --------------------------------------- 703 | 704 | ### attributevalue 705 | 706 | Attribute values are very similar to [items](#reference-item), except that they can not reference attributes. 707 | 708 | **Properties** 709 | 710 | | |Type|Description|Required| 711 | |---|----|-----------|--------| 712 | |**accessor**|`integer`|Index to referenced accessor.|No| 713 | |**typeHint**|`integer`|Index to referenced typehint.|:white_check_mark: Yes| 714 | |**value**|`any`|Embedded value.|No| 715 | 716 | Additional properties are allowed. 717 | 718 | #### attributevalue.accessor 719 | 720 | Index to referenced accessor. Both an embedded value and an accessor may be specified, in which case the embedded value serves as preview. 721 | 722 | * **Type**: `integer` 723 | * **Required**: No 724 | * **Minimum**: ` >= 0` 725 | 726 | #### attributevalue.typeHint 727 | 728 | Index to referenced typehint. 729 | 730 | * **Type**: `integer` 731 | * **Required**: Yes 732 | 733 | #### attributevalue.value 734 | 735 | Embedded value. 736 | 737 | * **Type**: `any` 738 | * **Required**: No 739 | 740 | 741 | 742 | --------------------------------------- 743 | 744 | ### buffer 745 | 746 | A buffer is used to reference binary data. 747 | 748 | **Properties** 749 | 750 | | |Type|Description|Required| 751 | |---|----|-----------|--------| 752 | |**byteLength**|`integer`|Length of the buffer in bytes.|:white_check_mark: Yes| 753 | |**uri**|`string`|Uri to fetch buffer from.|No| 754 | 755 | Additional properties are allowed. 756 | 757 | #### buffer.byteLength :white_check_mark: 758 | 759 | Length of the buffer in bytes. 760 | 761 | * **Type**: `integer` 762 | * **Required**: Yes 763 | * **Minimum**: ` >= 0` 764 | 765 | #### buffer.uri 766 | 767 | Uri to fetch data from. Can be a data uri. Not set in case of the directly attached buffer used for _binary sdTF_. 768 | 769 | * **Type**: `string` 770 | * **Required**: No 771 | 772 | 773 | 774 | --------------------------------------- 775 | 776 | ### bufferview 777 | 778 | A bufferview references a chunk of data in a buffer. 779 | 780 | **Properties** 781 | 782 | | |Type|Description|Required| 783 | |---|----|-----------|--------| 784 | |**buffer**|`integer`|Index of the referenced buffer.|:white_check_mark: Yes| 785 | |**byteLength**|`integer`|Length of the bufferView in bytes.|:white_check_mark: Yes| 786 | |**byteOffset**|`integer`|Offset into the buffer in bytes.|:white_check_mark: Yes| 787 | |**contentEncoding**|`string`|Content-Encoding which was used to compress the data referenced by the buffer view.|No| 788 | |**contentType**|`string`|MIME type of data referenced by the buffer view.|:white_check_mark: Yes| 789 | |**name**|`string`|Optional name of the buffer view.|No| 790 | 791 | Additional properties are allowed. 792 | 793 | #### bufferview.buffer :white_check_mark: 794 | 795 | Index of the referenced buffer (0-based). 796 | 797 | * **Type**: `integer` 798 | * **Required**: Yes 799 | * **Minimum**: ` >= 0` 800 | 801 | #### bufferview.byteLength :white_check_mark: 802 | 803 | Length of the bufferView in bytes. 804 | 805 | * **Type**: `integer` 806 | * **Required**: Yes 807 | * **Minimum**: ` >= 0` 808 | 809 | #### bufferview.byteOffset :white_check_mark: 810 | 811 | Offset into the buffer in bytes. 812 | 813 | * **Type**: `integer` 814 | * **Required**: Yes 815 | * **Minimum**: ` >= 0` 816 | 817 | #### bufferview.contentEncoding 818 | 819 | Content-Encoding which was used to compress the data referenced by the buffer view. 820 | See [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding). 821 | 822 | * **Type**: `string` 823 | * **Required**: No 824 | 825 | #### bufferview.contentType :white_check_mark: 826 | 827 | MIME type of data referenced by the buffer view. 828 | See [https://www.iana.org/assignments/media-types/media-types.xhtml](https://www.iana.org/assignments/media-types/media-types.xhtml) 829 | and [https://tools.ietf.org/html/rfc6838](https://tools.ietf.org/html/rfc6838) 830 | 831 | * **Type**: `string` 832 | * **Required**: Yes 833 | 834 | #### bufferview.name 835 | 836 | Optional name of the buffer view 837 | 838 | * **Type**: `string` 839 | * **Required**: No 840 | 841 | 842 | 843 | --------------------------------------- 844 | 845 | ### chunk 846 | 847 | Same as [node](#reference-node). 848 | 849 | 850 | 851 | --------------------------------------- 852 | 853 | ### fileinfo 854 | 855 | Metadata about the sdTF asset. 856 | 857 | **Properties** 858 | 859 | | |Type|Description|Required| 860 | |---|----|-----------|--------| 861 | |**copyright**|`string`|Copyright mark.|No| 862 | |**generator**|`string`|Hint to software package that generated the sdTF asset.|No| 863 | |**version**|`string`|The sdTF version used by this asset.|:white_check_mark: Yes| 864 | 865 | Additional properties are allowed. 866 | 867 | 868 | 869 | --------------------------------------- 870 | 871 | ### item 872 | 873 | Data items serve as the leaves of trees defined by nodes. The actual data may be embedded directly, or a reference to an accessor. Data items can have optional attributes. 874 | 875 | **Properties** 876 | 877 | | |Type|Description|Required| 878 | |---|----|-----------|--------| 879 | |**accessor**|`integer`|Index to referenced accessor.|No| 880 | |**attributes**|`integer`|Index to referenced attributes.|No| 881 | |**typeHint**|`integer`|Index to referenced typehint.|:white_check_mark: Yes| 882 | |**value**|`any`|Embedded value.|No| 883 | 884 | Additional properties are allowed. 885 | 886 | #### item.accessor 887 | 888 | Index to referenced accessor. Both an embedded value and an accessor may be specified, in which case the embedded value serves as preview. 889 | 890 | * **Type**: `integer` 891 | * **Required**: No 892 | * **Minimum**: ` >= 0` 893 | 894 | #### item.attributes 895 | 896 | Index to referenced attributes. 897 | 898 | * **Type**: `integer` 899 | * **Required**: No 900 | 901 | #### item.typeHint 902 | 903 | Index to referenced typehint. 904 | 905 | * **Type**: `integer` 906 | * **Required**: Yes 907 | 908 | #### item.value 909 | 910 | Embedded value. 911 | 912 | * **Type**: `any` 913 | * **Required**: No 914 | 915 | 916 | 917 | --------------------------------------- 918 | 919 | ### node 920 | 921 | Trees in sdTF are made of nodes. Nodes can reference other nodes and/or data items. 922 | 923 | **Properties** 924 | 925 | | |Type|Description|Required| 926 | |---|----|-----------|--------| 927 | |**attributes**|`integer`|Index to referenced attributes.|No| 928 | |**items**|`integer[]`|Array of indices of child items.|No| 929 | |**name**|`string`|Optional name of node.|No| 930 | |**nodes**|`integer[]`|Array of indices of child nodes.|No| 931 | |**typeHint**|`integer`|Index to referenced typehint.|No| 932 | 933 | Additional properties are allowed. 934 | 935 | #### node.attributes 936 | 937 | Index to referenced attributes. 938 | 939 | * **Type**: `integer` 940 | * **Required**: No 941 | 942 | #### node.items 943 | 944 | Array of indices of child items. 945 | 946 | * **Type**: `integer[]` 947 | * **Required**: No 948 | 949 | #### node.name 950 | 951 | Optional name of node. 952 | 953 | * **Type**: `string` 954 | * **Required**: No 955 | 956 | #### node.nodes 957 | 958 | Array of indices of child nodes. **Must not** reference itself. 959 | 960 | * **Type**: `integer[]` 961 | * **Required**: No 962 | 963 | #### node.typeHint 964 | 965 | Index to referenced typehint. **Should** be specified in case the type hint for all child nodes and items is the same. **Must not** be specified otherwise. 966 | 967 | * **Type**: `integer` 968 | * **Required**: No 969 | 970 | 971 | 972 | --------------------------------------- 973 | 974 | ### sdTF (root object) 975 | 976 | The root object of an sdTF asset. 977 | 978 | **Properties** 979 | 980 | | |Type|Description|Required| 981 | |---|----|-----------|--------| 982 | |**accessors**|[`accessor[]`](#reference-accessor)|Array of accessors.|No| 983 | |**asset**|[`fileinfo`](#reference-fileinfo)|Metadata about the asset.|:white_check_mark: Yes| 984 | |**attributes**|[`attributes[]`](#reference-attributes)|Array of attributes.|No| 985 | |**buffers**|[`buffer[]`](#reference-buffer)|Array of buffers.|No| 986 | |**bufferViews**|[`bufferView[]`](#reference-bufferView)|Array of bufferviews.|No| 987 | |**chunks**|[`chunk[]`](#reference-chunk)|Array of chunks.|No| 988 | |**items**|[`item[]`](#reference-item)|Array of items.|No| 989 | |**nodes**|[`node[]`](#reference-node)|Array of nodes.|No| 990 | |**typeHints**|[`typeHint[]`](#reference-typeHint)|Array of type hints.|No| 991 | 992 | Additional properties are allowed. 993 | 994 | 995 | 996 | --------------------------------------- 997 | 998 | ### typehint 999 | 1000 | Type hints are used to add information about the type of data items found below a specific node in the tree. 1001 | 1002 | **Properties** 1003 | 1004 | | |Type|Description|Required| 1005 | |---|----|-----------|--------| 1006 | |**name**|`string`|Name of the typehint.|:white_check_mark: Yes| 1007 | 1008 | Additional properties are allowed. 1009 | 1010 | #### typehint.name :white_check_mark: 1011 | 1012 | Name of the typehint 1013 | 1014 | * **Type**: `string` 1015 | * **Required**: Yes 1016 | * **Supported values** (extensible): 1017 | * boolean 1018 | * char 1019 | * color 1020 | * data 1021 | * decimal 1022 | * double 1023 | * guid 1024 | * image 1025 | * int8 1026 | * int16 1027 | * int32 1028 | * int64 1029 | * json 1030 | * single 1031 | * string 1032 | * uint8 1033 | * uint16 1034 | * uint32 1035 | * uint64 1036 | * geometry.arc 1037 | * geometry.boundingbox 1038 | * geometry.box 1039 | * geometry.circle 1040 | * geometry.complex 1041 | * geometry.cone 1042 | * geometry.cylinder 1043 | * geometry.ellipse 1044 | * geometry.interval 1045 | * geometry.interval2 1046 | * geometry.line 1047 | * geometry.matrix 1048 | * geometry.plane 1049 | * geometry.point 1050 | * geometry.point2d 1051 | * geometry.point3d 1052 | * geometry.point4d 1053 | * geometry.polyline 1054 | * geometry.ray 1055 | * geometry.rectangle 1056 | * geometry.sphere 1057 | * geometry.torus 1058 | * geometry.transform 1059 | * geometry.transformlist 1060 | * geometry.vector 1061 | * geometry.vector2d 1062 | * geometry.vector3d 1063 | * geometry.vector4d 1064 | * grasshopper.path 1065 | * rhino.arccurve 1066 | * rhino.brep 1067 | * rhino.curve 1068 | * rhino.extrusion 1069 | * rhino.linecurve 1070 | * rhino.mesh 1071 | * rhino.nurbscurve 1072 | * rhino.nurbssurface 1073 | * rhino.planesurface 1074 | * rhino.point 1075 | * rhino.polycurve 1076 | * rhino.polylinecurve 1077 | * rhino.revsurface 1078 | * rhino.subd 1079 | * rhino.surface 1080 | -------------------------------------------------------------------------------- /specification/1.0/assets/README.md: -------------------------------------------------------------------------------- 1 | Assets for sdTF 1.0 specification 2 | -------------------------------------------------------------------------------- /specification/1.0/assets/binary-sdtf-content.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/shapediver/sdTF/da9d59af7551633b36ac2b9161cc490ee7bda1fe/specification/1.0/assets/binary-sdtf-content.png -------------------------------------------------------------------------------- /specification/1.0/assets/sdTF_spec_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/shapediver/sdTF/da9d59af7551633b36ac2b9161cc490ee7bda1fe/specification/1.0/assets/sdTF_spec_example.png -------------------------------------------------------------------------------- /specification/1.0/assets/sdTF_spec_example.sdtf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/shapediver/sdTF/da9d59af7551633b36ac2b9161cc490ee7bda1fe/specification/1.0/assets/sdTF_spec_example.sdtf --------------------------------------------------------------------------------