Talk:K3D JavaScript Canvas Library/Tutorial

K3D objects features a number of user definable properties. They can describe the object relative position from the origin and allow set-up of simple animations that increment one or more of the angles or position vector properties for the object over time. There are also a number of properties that describe how the object should be rendered by the engine:

The following properties describe the point around which the object should be rotated during animation - default is the origin at 0,0,0:
 * aboutx (number) - x coordinate for the object rotation origin
 * abouty (number) - y coordinate for the object rotation origin
 * aboutz (number) - z coordinate for the object rotation origin

The following properties describe the initial rotatation angles for the object with respect to its rotation origin, default is zero degrees:
 * otheta (number) - the initial angle in degrees to rotate the object around the X axis
 * ophi (number) - the initial angle in degrees to rotate the object around the Y axis
 * ogamma (number) - the initial angle in degrees to rotate the object around the Z axis

The following properties describe how the engine should modify the rotation per animation frame, default is no animation:
 * addtheta (number) - degrees to add to the rotation around the X axis per animation frame
 * addphi (number) - degrees to add to the rotation around the Y axis per animation frame
 * addgamma (number) - degrees to add to the rotation around the Z axis per animation frame

The following properties describe the initial offset of the object in 3D space, this allows the object to be moved into a position, note that the rotation origin is then relative to this location, default is the origin at 0,0,0:
 * offx (number) - object offset x coordinate
 * offy (number) - object offset y coordinate
 * offz (number) - object offset z coordinate

The following properties describe the velocity to be applied to the object offset position in the x,y,z axis per animation frame, used to automatically move the object to create simple animations when combined with the bmin/max properties below, default is no velocity:
 * velx (number) - object velocity in the x axis
 * vely (number) - object velocity in the y axis
 * velz (number) - object velocity in the z axis

The following properties describe a virtual bounding box in which the object will be automatically "bounced" if it's offset location touches the edges of the box, this can be used to create simple 3D bouncing animations when combined with the velocity properties above, default is no bounding box defined:
 * bminx, bminy, bminz, bmaxx, bmaxy, bmaxz (number) - bounding box x, y, z minimum and maximum coordinates


 * scale (number) - describes a scaling factor to be applied to the points for the object before initial display. This is a one-time operation. It is generally used to scale up/down an object to fit the current canvas size. So you define an object once with a known size, and scale it before display for different animations etc. It does not actually move the observer closer to the object, just changes the size of the object. Default is 1.0.

The following properties modify how the object is rendered by the engine:
 * drawmode (string) -"point" - only render the points of an object. "wireframe" - render the edges of an object as lines, "solid" - render the polygons of an objects as solid filled polygons.
 * shademode (string) - "plain" - plain color rendering, no attempt to light source or shade the lines or polygons, this is the simplest rendering mode. "depthcue" - z-ordered depthcued color rendering - the engine will shade the object from light to dark (using the object color as the lightest color) based on the z-order of the points and also adjust the relative line thickness to make lines in the background look further away than lines closest to the observer. "lightsource" - lightsourced color rendering (only available for "solid" drawmode), by default the engine will shade the polygons based on the angle of the polygon surface from the observer, so as polygons turn further away from the observer, they will be shaded darker. As well as the default lighting, additional coloured lights can be added to generate cool lighting effects (which themselves can be moved and modified during animation). See K3D.LightSource object.
 * color (Array) - default color of the object - used when "plain" shading mode is used for points, lines or polygons. Specified as RGB 0-255 values in an Array e.g. [255,255,255] is the white default color.


 * perslevel (number) - perspective level multiplier - powers of 2 recommended, default is 512. This value controls how strong the perspective effect is for the 3D->2D projection. Lower values give a intense 3D look, higher values give a flatter looking 3D projection.
 * linescale (number) - floating point scaling factor for "wireframe" drawing mode - use this to make wireframe edges of an object look thick or thin. Default value is 2.0 pixels.
 * doublesided (boolean) - by default this value is false as for performance reasons the engine will not render polygons that are not facing the observer. Set this flag to true to always render all polygons, visible or otherwise. This is useful if you want to see the back faces of an object i.e. inside of a cube or similar.

Advanced rendering properties:
 * recalulatenormals (boolean) - by default this value is false. K3D performs a one-time calculation of the polygon normal vectors so that the polygons are correctly lit and correctly removed if not visible. Set this flag to true only if you manipulate the points during an animation (via the callback method) as then the engine will then need to recalculate the normal vectors for each frame.
 * fillstroke (boolean) - due to the way in which HTML5 canvas fills shapes, if you place two polygons exactly next to each other and render them, there will be a small 0.5 pixel thick gap between the polygons. This leads to a "cracking" effect that makes some objects look like they have thin holes in. To fix this, the engine can render each polygon twice, which causes canvas to "overdraw" the anti-aliased edges of the polygons, this is the fastest way to fix the problem. Set this property to true and the engine will double fill the polygons to fix the cracking effect. However this is a relatively expensive operation and will slow down the rendering.
 * depthscale (number) - when using depthcued rendering mode, this value controls the "middle point" for the depthcue/perspective scaling calculation. By default it is set to the width of the canvas/2. Generally you will not need to modify this value.
 * sortmode (boolean) - one of "sorted" or "unsorted", default is "sorted". Can be used to disable z-ordered sorting of objects before they are displayed. Generally you will not need to modify this value.

Thanks! Here were my guesses: o{phi,theta} are angles for the camera position. add{gamma,theta,phi} are angular animation increments when a callback isn't being used; about{x,y,z} could be axis coordinates or maybe something having to do with the camera position; scale could be the zoom; linescale and fillstroke have something to do with the width of wireframe and points (respectively?); doublesided perhaps means to render light on both sides of a face?; recalculatenormals hints that the callback might change the orientation of the face polygons. I see now that the boolean second argument to K3D.Controller disables click-to-pause. Jsalsman (discuss • contribs) 18:13, 19 August 2011 (UTC)