Objectloader / "JS SDK"

Help
,
1

Hey! :slight_smile:

I am currently developing a web app and struggling to find any proper resources for any “Javascript/Typescript SDK” or even for the existing JS ObjectLoader.
As far as I know, there is no complete SDK for JavaScript - just the ObjectLoader. I found that one in the speckle-server repository, but I am unable to get the given example to work. Some imports seem to point to missing files?

I am aware of the GraphQL API and I am currently using that one. But is there any “ready-made” code for handling speckle objects in Typescript? Anything to process the API response? Anything for going through the model without processing JSON directly?

I would be so happy, if you could point me into the right direction (if there is one). <3

2 Likes
2

Or maybe some kind of typescript interface/type definitions for the GraphQL API responses.

1 Like
3

Hello @samberger,

Welcome to our community! I see you’ve been a member here for a while, and we appreciate your :speckle: engagement. :blush:

I understand your struggle to find comprehensive resources for a “Javascript/Typescript SDK” and the existing JS ObjectLoader. You’re completely correct; currently, we don’t have a robust SDK for JS/TS.

Each package relies upon and expects some of the others to be ‘active’ at the same time. The ObjectLoader and the Viewer are both available as npm packages. You can find them here:

Unfortunately, the documentation for both is limited at the moment. We’re working hard to stabilise the API, especially for the Viewer, which is a rapidly evolving project.

The ObjectLoader and the GQL interfaces are more stable. Still, providing a Typed response is challenging due to the nature of the data. Depending on the source application or analysis, the data stored in Speckle will be arbitrary JSON, which you’ve already encountered.

We do plan to map Speckle Types to JS/TS eventually. However, as most of the Connectors are built using other SDKs, this hasn’t been a priority yet. One possibility we’ve considered is having our CI process automatically document a common schema, allowing our Core Objects library to continue evolving while maintaining consistency.

Even with the Objects library, a lot of dynamic data might not fit neatly into a schema. This is intentional - Speckle does not enforce a strict schema but employs opinionated structures.

I also encourage you to explore the current server and frontend code, following the instructions in the viewer-sandbox. This might provide some interim solutions and further insights into the areas that need improvement. There are also some equivalences to the helpful SDK wrapper functions in the speckle-excel connector. However, you seem to have the GQL querying sorted already.

We understand the challenge you’re facing, and we want to ensure that our development efforts meet the needs of our users. To this end, we’d greatly appreciate it if you could share the specific requirements or features you feel are essential for a JavaScript/TypeScript SDK. Your insights will be instrumental in helping us develop a minimum viable product (MVP) that addresses real-world needs.

Your interest sounds like it is the data object side of any SDK rather than the interfaces with the server, so your feedback in this process is invaluable. We’re here to support you and make the development process as smooth and effective as possible - in lieu of more tooling, please continue to ask questions.

Thank you again for your engagement and support. :blush: :blush:

5 Likes
4

There’s also this SDK developed by @haitheredavid and team at Sasaki: GitHub - sasakiassociates/speckle: JavaScript client for the Speckle API

3 Likes
5

:wave: Ah I feel you @samberger, we had the same experience when sketching out our first prototypes for the web with speckle. If you want/can share any info on the project I can do my best to help.

A while back we did mock up a proof of concept for a speckle js sdk, but it’s a bit limiting at the moment. We are planning to do a heavy push over the next couple of months to get a basic core sdk setup.

I’ve had a few chats with other community members about this, so here is a lil copy pasta that might help

The Object Loader

The main thing you’ll need to get speckle objects into your three project is the ObjectLoader. This is a package that handles getting data from a stream and formatting the data into standard Base type objects. We started working with this in a console project and it was pretty straightforward when hacking together a solution. However, this won’t get geometry into three natively, you still need to worry about converting it.

The View Object Loader

Speckle adapted their object loader for their viewer to work like their c# connectors. The main difference is that the loader has a Converter object nested in it that pulls the deserialized object data into the three scene. If you jump into that converter you’ll see some logic for handling how the Base objects get turned into three objects. Depending what you’re trying to do you might need to copy this loader and converter into your project. We’ve been developing a package that lets you just add these feature to your project, but that isn’t ready yet for publishing.

5 Likes
6

@jonathon Thank you so much for your quick and extensive response! And sorry I haven’t replied earlier.
Also Thanks to @teocomi and @haitheredavid!

The SDK of Sasaki indeed is new to me. Cool! :slight_smile: As far as I understand from a quick look, this seems to be more or less the part I already wrote myself by now (I think). :sweat_smile:
As I understand, based on the concept of “opinionated/flexible data structures” the Sasaki SDK serves whatever JSON is returned from the GQL API. Navigating through streams/branches/commits more easily of course. :slight_smile:

Thinking one step further for the application in our company (structural engineers), I aimed to create more specific objects/classes with built-in “functionality” - not just JSON. Maybe like a “wrapper” for the underlying JSON data. For example a “Beam” with built-in properties “endpoints” or “length” … or a method “reverse()”. And a “RevitBeam” might extend “Beam” and so on… So using the speckle model and its building elements wouldn’t require to handle the underlaying actual JSON structure. I assume there must be something like that for all the C# connectors. Base Object etc.
Of course, this makes it less flexible regarding data content (allthough you might always be able to access the raw data of the object), but would make it more efficient and easy to use for different application of our daily work. I don’t think we need that creativity here, haha. :crazy_face:

And yes, since those objects kind of reflect the data structure underneath, I am very much interested in how it is structured and which properties are common for which types of objects and which are not.

So far, it’s less about the 3D viewer.

I agree, it might be very helpful to dive into your server and frontend code to see how you are handling such things yourself. So far, I had too much respect to do so. :innocent:
On the other hand the frontend is probably not really “processing” the properties of the objects/building, and “just” unknowingly rendering the geometry and moving the JSON packages? :thinking: So the connectors might indeed be more interesting (but not TS).

I will follow your advices and see!
It’s already super helpful to be sure about the current state out there.

Thanks again!

2 Likes
7

Take a look through the Speckle Objects library if you haven’t already. Its all C#, but is almost self-documenting :face_with_peeking_eye:

It’s clear, at least, how class inheritance is working.

For the extended objects you are referring to, are you planning on authoring objects in JS to send to Speckle, or are you referring to the augmentation of objects as received and then displayed to your users … similar to the recently published B+G study?

1 Like
8

For now, it’s mainly about altering the (non-geometrical) properties/parameters of existing objects (like columns, walls, …) … Or about analyzing/reading any properties for various purposes.