Annotation to Animation Binding & A List of API Gripes


(Wraybowling) #1

Hey gang. I was hired with the task to use the sketchfab api to figure out a way to have annotations be clickable to trigger a specific animation. The result is pretty basic and it works, but the process was messy. Based on my experience and what i can see others have tried to do, here are my gripes.

First step, a list of both the annotations and the animations.
Annotations come back as an array of objects. The index of the object in the array is how you identify which number the annotation is (object at index 2 plus 1 equals annotation 3).

Array [ Object, Object ]

[
  { name: 'open the box', uid:'abc12' }
  { name: 'eat the candy' uid:'def34' }
]

Animations come back as an array in whatever order the api feels like at the time. Sometimes this changes based on what browser you’re using… Fun! But instead of an object, this time it’s another array.

Array [ Array[3], Array[3] ]

[
  ['jkl456', 'eat the candy', 12]
  ['ghi123', 'open the box', 8]
]

Gripe #1: Animations should come back as objects

There’s really nothing y’all are gaining by using an array other than making the code harder to read. animationsList[i][0] is inferior to animationsList[i].id

Gripe #2: How about all the animations as one object?

If the order isn’t going to come back the same way it was set up in 3D settings, then why bother using an ordered structure like an array? If you’re going to assign unique IDs to the animations, how about just use those?

allAnimations : {
  'ghi123': { ... },
  'jkl456': { ... }
}

Gripe #3: variables on annotations would have nice

instead of just body text, often I want to store a list of basic key-value paired attributes. If you want to really make your API shine, this is going to be a big one. In my case, I would’ve made a field called “animation” and set it to the name of the animation to play.

Gripe #4: There’s no event that fires at the end of an animation

Basic stuff.
…Instead I had to use the duration and make a setTimeout to try to catch the animation just before the end to pause it and it doesn’t always work because there’s no guarantee that my timer and the player are on the same wavelength.

Gripe #5: Callback Hell

It’s almost 2019. Promises, please.

Sorry Not Sorry

So, before I share my codebase I need to clear that it’s okay to do so. But also… i kind of hate looking at it. It’s gross. No one should do code like this and while I did get it to work, I think we should upgrade the API some so I can clean it up, or even negate the need for it. I would be sorry about being grouchy on my first post, but I think I gave some OK constructive alternatives, and if the team wants help upgrading the API, PM me, I’ll be happy to.


(Paul Sketch) #2

Thanks for the remarks, definitely helpful.

1, 2: noted.
3: is there a typo ? is it annotation or animation ? can you provide a sample of variable on “annotations/animations”?
4: noted. you can get current animation time rather than using a timeout ?
5: Note that Promises is in our plans, and we have to carefully plan it to not induce more lag too. (callback between iframe and main frame is two ticks, promise would add another one.)


(Wraybowling) #3

2: annotation variables
Nope, no typo. Annotations are the best way to capture user interactivity. The attributes available now all will display on screen. There’s already a lot of hidden metadata in annotations to make use of but none of it can be set manually.

For example let’s pretend a model has some annotations on it and when clicked you’d like a mapping api to fly/zoom over to a set of geo coordinates. I think the idea y’all have right now is that annotations should then be generated by js so perhaps a CMS could keep track of both the sketchfab annotation uid and the mapping coordinates. But annotations on 3D models are really best placed by hand in the 3D setting interface. So, if the most natural interface isn’t in any CMS, it would be nice to be able to add my own variables to the annotation so when its events dispatch i can retrieve values for use in a script.
To really make my point, doing the reverse would be quite easy because tools like QGIS can edit geoJSON in an interactive and visual way, and geoJSON allows any key value pair data. So all i would need to do is add the corresponding sketchfab uid to the geoJSON.
A solution that doesn’t require duplicate efforts might not exist, i’m grasping for options though.


(Paul Sketch) #4

ok, now I get it, thanks.
so
2- Ability to have metadata on annotations placed in the 3D editor.