Sharing and embedding

When you publish an animation and/or video, you are given a unique handle, for example NTc0OTAx

You may share a publication in different ways:

You may embed a publication into your own website or blog using the following code:

<iframe width="640" height="480" src="https://3dthis.com/play.htm?h=handle&autostart&nocontrols&loop" frameborder="0" allowfullscreen></iframe>

You may change width and height at your convenience.
handle is mandatory, replace it by your animation/video handle, NTc0OTAx in this example.
&autostart is optional, if present animation/video will start after load.
&nocontrols is optional, if present the upper and lower control bars will not be displayed (for video, the lower controls are always displayed).
&loop is optional, if present then it affects only videos, which will restart from the beginning.
frameborder is optional, it defines the border width around the publication (defaults to standard browser border).
allowfullscreen is optional, keep it if you want to allow full screen display. Currently works only with Firefox and Chrome.

 

The PhotoAnim JavaScript API V2.1


The PhotoAnim API allows integrating an animation to your website without accessing 3Dthis.com.
It is a very high level API, which requires very little 3D graphic, HTML and JavaScript knowledge.
The API has been tested for compatibility with all major browsers and devices, including mobiles.

Key features:
  • Not only display models, but also animate them at your wish, or decide how your viewers can animate them.
  • Short load time thanks to compact coding and compression.
  • Unique controls like brightness, contrast, hue, saturation are handled directly by the graphic card.
  • Does not depend on a 3rd party website or external resources: It's all self-contained.
  • Several 3D objects can be animated simultaneously.
  • No plugins, relies on the WebGL API, which is supported as standard by all major browsers.
  • Totally free, including for commercial use.
Typical applications:
  • Online advertisement and 3D product display
  • 3D online apps
  • Online games
  • Web design

With the PhotoAnim JavaScript API, you may display and customize animations previously published on 3Dthis or you may create animations from scratch.

Downloadable resources:

Starting from animations previously published on 3Dthis.com

This is the simplest way of using the PhotoAnim API: You first publish an animation created with PhotoAnim for Windows or one of our various online 3Dthis apps(*), you download it and play it as follows:

  • Using our standard player (paplayer.htm) in an <iframe>
  • Implementing your own player: This allows customizing controls and features.
(*)Available apps: Morphing, 3D photo effects, 3D volume, 3D viewer, Google Cam to 3D, 3D mapper, Live selfie, i-Video, Photo cube

The easy way: standard player in an <iframe>

Download following 2 files and save them to the same folder as your html page:
            photoanim.js     paplayer.htm   click to download

Download one of your animations or use this test animation and save it to the same folder (default name is paJSON.js).

On the body from your html page, insert the following code where you want the animation to be played:

width and height may be adjusted to match your page layout.

Following options can be added to the paplayer.htm query string:
&autostart - start animation immediately
&nocontrols - do not display the control bar

Example:
paplayer.htm?url=paJSON.js&autostart&nocontrols

 



Implementing your own player

Implementing your own player allows customizing your animation: You may define your own start/stop buttons, add additional controls like brightness, contrast, implement collision detection, give user control to different objects... Possibilities are endless...
However, you will need some knowledge about the PhotoAnim JavaScript API.
 

Example 1: Implementing Start/Stop buttons and Brightness/Contrast sliders

 



 
Example 2: Collision detection

Two spheres are produced with PhotoAnim for Windows and randomly animated using the 3Dthis animation editor. A collision detection is added, when a sphere hits the other one...  It happens that spheres capture each other, which produces funny effects...



 
Example 3: Individual objects detection and move

A static sphere and cylinder are produced with PhotoAnim for Windows. Mouse capture is implemented to detect when mouse is over an object. The object can then be dragged.
Some maths are included to make it still work when the camera is rotated or zoomed.

 



 

Creating animations from scratch

This is best explained using a few examples. You will find the full PhotoAnim API reference here and the JavaScript API file here.
 

Example 1: The minimum animation

In this example, we will simply rotate a square picture around the Y axis (horizontal rotation).
The picture is called a texture, and dimensions should be a power of 2 (i.e. 512x256 or 512x512). For compatibility with most browsers a texture should not exceed 4096px on one dimension.



header
The bgrdcolor property is mandatory, format is [r, g, b, a] (red, green, blue, alpha), with values from 0 to 1. alpha defines the full animation opacity.
vertices
Each entry into vertices is 7 values, namely x, y, z, trajx, nx, ny, nz. x, y, z, define a point in space coordinates, nx, ny, nz, corresponding normals, trajx is used for trajectories (see reference). Coordinates are relative to scenery center, with x pointing right, y pointing up, z pointing towards viewer, in the range 0 to 1.
Normals can be set to 0 and computed using method calcNormals(vertices), see Example 2.
In the above example, 4 vertices are defined, one at each corner of a square.
texcoord - texture coordinates
Each entry into texcoord is 2 values, namely u,v and total number of entries should be same as in vertices. u, v define a point from the texture image, u, v coordinates are relative to texture top left, u towards right and v towards bottom, in the range 0, 1.
In the above example, 4 texture points are defined, one at each corner of the square texture image.
triangles
Triangles join vertices together to define surfaces. Each entry into triangles is 3 values, indexes into vertices/7, namely vx1, vx2, vx3. Triangles should be oriented external face CCW for lighting purposes.
In the above example, 2 triangles are defined to form a square.

mesh
mesh is a 5 objects array, namely [vertices, texcoord, triangles, trajectories, texture]
trajectories are not used in this case, so we set them as a single value [0] array.
canvas can be an image url or another canvas or a video object. In the above example, we use a 512*512 image from a cat named "myimage.jpg".

global
The global object should have at least 3 properties defined: camera, light and user
camera defines the camera movement and zoom. In this case we request the camera to rotate around the Y axis at a speed of 40° / second and we set the zoom to a fixed value of .5
light defines scenery lighting. We use default light so we set it to a dummy object {}
user defines allowed user actions with mouse or fingers, namely rotate, move, zoom. We use default values (allow all) so we set it to a dummy object {}

object
Several objects can be defined, and each object can be animated independently. A given object has at least two properties: A center [x, y, z] and a start index vxstart into vertices. In the above example we have a single object.
objects
objects lists the various objects, with property objs.

Example 2: Displaying and animating an STL model

STL is a very simple 3D file format, mainly used by 3D printers. This script converts a binary STL file and displays the model.

 



STL files define volume only, not textures. The PhotoAnim API always need textures, even to display solid colors. So in this case we use a small 16x16 texture image "yellow.png" and set all texcoord to .5, .5 (middle of texture).
Untextured objects need light to be displayed properly, so we define light properties "shading" and "specular".

startWebGL is called when the stl file is loaded and parsed.
LoadStlFile does an Ajax request to load the "duck.stl" file as a byte array
parseBinStl gets vertices x, y, z values and adds triangles. As we need vertices normals, the triangle normals from the stl file are ignored and the method calcNormals is called once, followed by refreshVertices to update the graphic card.
For a good computation of vertices normals, duplicated vertices are removed in addVertex. Also, the model is centered and scaled with normVertices
 
Example 3: Adding a background image and updating texture

 



 
 

More examples from the API documentation

  •   Rotate camera 360° around subject when user clicks canvas
     
  •   Rotate light around model, control shading and specular with sliders
     
  •   Animate many objects
     
  •   Use mouse capture to control background position
     
  •   Move object(s) using trajectories
     
  •   A basic Pong game
     
  •   VR photos
 

Licensing

The PhotoAnim API is licensed under Creative Commons CC BY

You are free to:

  • Share - copy and redistribute the material in any medium or format
  • Adapt - remix, transform, and build upon the material for any purpose, even commercially.
Under the following terms:
  • Attribution - You must give appropriate credit and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
  • No additional restrictions - You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

If you use the PhotoAnim API, then we kindly request you to give credit to 3Dthis.com, by copy/pasting the following piece of code to your site:
 This will link to 3Dthis with the following logo: