@shapediver/sdk.sdtf-primitives
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    ShapeDiver

    Structured Data Transfer Format - Integration for primitive types

    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®. This open, efficient, and easily extensible data format enables the exchange of complex data structures, independent of software vendors. See the sdTF documentation for more details.

    The aim of this package is to extend the sdTF-v1 module to provide processing and typing functionality for primitive data.

    It can be used in Node.js and modern Browsers, and exposes the respective TypeScript declarations.

    Installation

    npm i @shapediver/sdk.sdtf-v1 @shapediver/sdk.sdtf-primitives

    This package is a plugin for the sdTF-v1 module and cannot be used by itself.

    Usage

    This code initializes the SDK and registers the integration for primitive types. After this step, the integration is fully included in all reading and writing processes of the SDK instance.

    // index.ts
    import { create, SdtfSdk } from "@shapediver/sdk.sdtf-v1"
    import { SdtfPrimitiveTypeIntegration } from "@shapediver/sdk.sdtf-primitives"
    
    (async () => {
        const sdk: SdtfSdk = await create({
            integrations: [ new SdtfPrimitiveTypeIntegration() ]
        })
    
        // Use the sdk here
    })()

    Supported types

    The following table lists all type hints that are supported by this integration, their specific TypeScript types, and the provided type guard functions that can be used to infer a data content type.

    Type hint name TypeScript type Type guard
    "boolean" or SdtfPrimitiveTypeHintName.BOOLEAN boolean SdtfPrimitiveTypeGuard.assertBoolean
    SdtfPrimitiveTypeGuard.isBoolean
    "char" or SdtfPrimitiveTypeHintName.CHAR string SdtfPrimitiveTypeGuard.assertString
    SdtfPrimitiveTypeGuard.isString
    "color" or SdtfPrimitiveTypeHintName.COLOR [number, number, number, number] SdtfPrimitiveTypeGuard.assertColor
    SdtfPrimitiveTypeGuard.isColor
    "data" or SdtfPrimitiveTypeHintName.DATA DataView SdtfPrimitiveTypeGuard.assertDataView
    SdtfPrimitiveTypeGuard.isDataView
    "decimal" or SdtfPrimitiveTypeHintName.DECIMAL number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "double" or SdtfPrimitiveTypeHintName.DOUBLE number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "guid" or SdtfPrimitiveTypeHintName.GUID string SdtfPrimitiveTypeGuard.assertString
    SdtfPrimitiveTypeGuard.isString
    "image" or SdtfPrimitiveTypeHintName.IMAGE DataView SdtfPrimitiveTypeGuard.assertDataView
    SdtfPrimitiveTypeGuard.isDataView
    "int8" or SdtfPrimitiveTypeHintName.INT8 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "int16" or SdtfPrimitiveTypeHintName.INT16 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "int32" or SdtfPrimitiveTypeHintName.INT32 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "int64" or SdtfPrimitiveTypeHintName.INT64 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "single" or SdtfPrimitiveTypeHintName.SINGLE number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "string" or SdtfPrimitiveTypeHintName.STRING string SdtfPrimitiveTypeGuard.assertString
    SdtfPrimitiveTypeGuard.isString
    "uint8" or SdtfPrimitiveTypeHintName.UINT8 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "uint16" or SdtfPrimitiveTypeHintName.UINT16 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "uint32" or SdtfPrimitiveTypeHintName.UINT32 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber
    "uint64" or SdtfPrimitiveTypeHintName.UINT64 number SdtfPrimitiveTypeGuard.assertNumber
    SdtfPrimitiveTypeGuard.isNumber

    Additionally, the type guard SdtfPrimitiveTypeGuard provides functions to infer type hints by their respective TypeScript type:

    typeGuard.isBooleanType:
    Returns true when the given type hint name is SdtfPrimitiveTypeHintName.BOOLEAN.

    typeGuard.isStringType:
    Returns true when the given type hint name is of

    • SdtfPrimitiveTypeHintName.CHAR
    • SdtfPrimitiveTypeHintName.GUID
    • SdtfPrimitiveTypeHintName.STRING

    typeGuard.isNumberType:
    Returns true when the given type hint name is of

    • SdtfPrimitiveTypeHintName.DECIMAL
    • SdtfPrimitiveTypeHintName.DOUBLE
    • SdtfPrimitiveTypeHintName.SINGLE
    • SdtfPrimitiveTypeHintName.INT8
    • SdtfPrimitiveTypeHintName.INT16
    • SdtfPrimitiveTypeHintName.INT32
    • SdtfPrimitiveTypeHintName.INT64
    • SdtfPrimitiveTypeHintName.UINT8
    • SdtfPrimitiveTypeHintName.UINT16
    • SdtfPrimitiveTypeHintName.UINT32
    • SdtfPrimitiveTypeHintName.UINT64

    typeGuard.isColorType:
    Returns true when the given type hint name is SdtfPrimitiveTypeHintName.COLOR.

    typeGuard.isDataViewType:
    Returns true when the given type hint name is of

    • SdtfPrimitiveTypeHintName.DATA
    • SdtfPrimitiveTypeHintName.IMAGE

    Example

    This simple example reads a sdTF file and extracts the content of all data items which contain a numeric type hint. Since the extracted content data is of type unknown, a type guard function is used to check and infer the content type to number. The numbers are then summed up and shown on the console.
    If any data item has a numeric type hint but does not contain numeric data, a corresponding error is thrown.

    // index.ts
    import { create, SdtfSdk } from "@shapediver/sdk.sdtf-v1"
    import { SdtfPrimitiveTypeIntegration, SdtfPrimitiveTypeGuard } from "@shapediver/sdk.sdtf-primitives"
    
    (async () => {
        const sdk: SdtfSdk = await create({
            integrations: [ new SdtfPrimitiveTypeIntegration() ]
        })
    
        // Reads the example file given in the sdTF specification v1:
        // https://github.com/shapediver/sdTF/tree/development/specification/1.0#a-complete-example
        const asset = await sdk.createParser().readFromFile("./test_data/sdTF_spec_example.sdtf")
    
        // Filter all data items with a numeric type hint (does not check the content!)
        const numericData = asset.items.filter(dataItem => SdtfPrimitiveTypeGuard.isNumberType(dataItem.typeHint?.name))
    
        let sum: number = 0
        for (const dataItem of numericData) {
            const content = await dataItem.getContent()             // load data content of type `unknown`
            SdtfPrimitiveTypeGuard.assertNumber(content)            // infers content to type `number`; throws if not possible
            sum += content                                          // add to sum
        }
    
        console.log("The sum of all numeric data content is", sum)  // Prints out: "The sum of all numeric data content is 479"
    })()

    Support

    If you have questions, please use the ShapeDiver Help Center.

    You can find out more about ShapeDiver right here.

    Licensing

    This project is released under the MIT License.

    Install

    npm i @shapediver/sdk.sdtf-primitives

    DownloadsWeekly Downloads

    141

    Version

    1.0.0

    License

    ISC

    Unpacked Size

    63.4 kB

    Total Files

    30

    Last publish

    Collaborators

    • dmitry_at_shapediver
    • snabela
    • michael_at_shapediver
    • matt_at_shapediver
    • luka_at_shapediver