DaVinci Viewer is a plug and play solution for displaying product proofs in a more realistic way using WebGL. This site gives a summary of browsers that support WebGL.

Setting up DaVinci Viewer only takes a couple of minutes to have it up and running with the default settings. You can further customize once you complete the following steps.

Start by adding the following script within your document head:

<script type="text/javascript" src="//davinci.opensoftdev.com/dvv/dist/davinciViewer.js"></script>

Determine where in your page you want it and then add the following tag there:

<div id="davinciViewer"></div>

To initialize and control DVV, we now need to add some JavaScript. Add the following code to your page to create an instance of DVV:

<script>
    var DVV = new opensoft.DavinciViewer('davinciViewer', {
        name: 'DVV',
        pages: [{your product data goes here...}],
        onLoadFailed: function () {
            console.error('Failed to load design into DVV.');
        }
    });
</script>

When passing information in about the product you want to display, it needs to match a certain format. The following are guidelines for making the JSON object that represents the product.

The following is an example of a simple business card:

[{
	"thickness": 20,
	"width": 666,
	"height": 390,
	"faces": [{
		"processes": [{
			"type": "regular",
			"src": "images/front.jpg"
		}]
	}, {
		"processes": [{
			"type": "regular",
			"src": "images/back.jpg"
		}]
	}]
}]

The outer array will contain as many objects as there are pages. Typically this will only be 1.

Each page object has several parameters that are required. These have an asterisk next to their name. A double asterisk means that that parameter OR a different parameter must be present. All of the rest are either optional or have default values.

Name Type Default Description
bleedX number 0 Use this option to trim bleed zone in the X direction. It defaults to 0. Make sure you're diecut matches the final shape you want. Trim bleed will not contract vertices.
bleedY number 0 Use this option to trim bleed zone in the Y direction. It defaults to 0. Make sure you're diecut matches the final shape you want. Trim bleed will not contract vertices.
camera object Use this option to edit the camera's position at set animations if desired. The default position is (0, 0, -500). See more details for the camera object later in this documentation.
diecut object Use this option to create a custom shape. See more instructions for diecut below.
faces array An array of faces. This tells DVV how each face should look and what processes should be applied. See below for more info.
fold string This option specifies if there are folds on this page. Options currently include: F4-1 | F4-2 | F6-1 | F6-2 | F6-3 | F6-4 | F6-5 | F6-8. See link for details. Do not use F2-1 ... leave fold blank instead.
foldConfig object Use this option to configure how the folds work. Right now we only have playTo param which allows you to have the fold animation play to a certain point and stop. For example, "playTo": {"o": 1,"p": 0.5} would play to half way through order 1 and then pause the fold animation.
foldOrigin number 1 Use this to adjust where the fold axis origin sits. Options are a range: 0.0 | 1.0.
foldRotation number 0 Rotates folds (as a whole) by this amount. Options currently include: 0 | 90.
folds object This option specifies if there are folds on this page. See below for more info. NOTE: If this param is used, it will override the 'fold' param.
height number Height of page (should match the height of the page's primary image in pixels).
rotation number 0 Rotation position you want product to start in. Some products need to be rotated to be in correct orientation like some tri-folds.
thickness number 5 Thickness of page in pixels.
thicknessImage string This is a base64 bytearray of the bitmap to use for this side texture. This property takes precedence over thicknessSrc property.
thicknessSrc string Location of bitmap to use for side texture. Example texture:
width * number Width of page (should match the width of the page's primary image in pixels).

The diecut explains the type of product we are displaying. There are several different types available including two custom types that allow you to build your own.

Name Type Default Description
object object Use this building a custom object. The format is: {"verts":[...], "polys":[...], "uvs":[...]}
radius number 0 Size in pixels to round the corners of a square.
type string rect Sets the design to a preset shape. Options currently include: 'rect' | 'ellipse' | 'customObject'.
vertices array Use vertices to define your own 2D shape vertices array like this: [[0, 100], [100, 100], [100, 0], [0, 0]]

Each face object is made up of a list of processes.

Name Type Default Description
gloss number 0 | 0.6 Amount of gloss to apply to this face. Closer to 0 the more rubber like. Closer to 1 the more glass like. Value range is: 0.0 - 1.0. Defaults to 0. If spotUV image is passed in, it will default to 0.5. If spotUV image is present, the gloss value here will affect how strong the spotUV is.
shine number 30 Amount of shine to apply to this face. Brightness of light reflection. Value range is: 0 - 100. Defaults to 30.
processes * array An array of processes. This tells DVV how each face should be rendered.

You can have as many processes as you want. Each process will be stacked on top of the last. If a pixel has a process on it, none of the processes below it will be seen. In other words, processes don't blend together, they replace. Only in places where a process is not applied do other processes show through. Each process object has several parameters available.

Name Type Default Description
bgSrc string Location of bitmap to use for this print process's background. It defaults to using the image supplied for the process.
bumpStrength number 1 Use this to adjust the strength of the bump map. Range is 0 - 10 but can be higher.
gloss number Use this to overwrite default value given by process. The lower the number the less light will be reflected. This number is a range from 0.0 - 1.0.
glossColor string Use this to overwrite default value given by process. This will change the color of the light that is reflected. This value is a hex number. Exclude the # prefix.
height number Height of image in pixels.
image string This is a base64 bytearray of the bitmap to use for this print process. If you supply a non grayscale image to a non regular process, DVV will handle it. This property takes precedence over src property.
invert boolean false This will invert the image. Usually used for inverting black and white images for effects like spotUV or emboss.
opacity number 1 A number between 0.0 and 1.0 which assigns an opacity value to this process.
shine number Use this to overwrite default value given by process. The higher the value, the shiny or the sharper the light reflection will be (think metal vs rubber). A lower number will disperse the light reflection over the surface more. This number is a range from 0 - 100.
src string Location of bitmap to use for this print process. If you supply a non grayscale image to a non regular process, DVV will handle it.
type * string Type of print process. Options currently include: 'regular' | 'spotUV' | 'KRE8-3D' | 'emboss' | 'metallic'. If using emboss, make sure that's the first process.
useAlphaMap boolean true If true, it will take the process image (of second effect or greater) to also mask the image which allows stacking of effects. If false, no masking will take place on.
width number Width of image in pixels.

The camera object represents the starting place for the camera and any animations that might be included. It defaults to 0 for all values except for z which is -500. If you add a camera object, you will always want to include a path and animation object.

Name Type Default Description
path object The path object contains a list of camera translations (x, y, and z for positioning and rx, ry, and rz for rotating).
animation object The animation object contains a list of paths and loops (m=index of path, t=time in ms, l=loop index, c=count).

Here is an example:

{
    "path": [   // List of camera states giving possible coordinate and rotation values.
        {"z": 200, "rx": 10},   // Move camera to z=200 and rotate camera to 10 degrees.
        {"z": 500},   // Move camera to z=500.
        {"z": 300, "rx": 20}   // Move caera to z=300 and rotate camera to 20 degrees.
    ],
    "animation": [   // List of transitions that are used to animate the camera.
        {"m": 0},   // Start camera with state 0 whichis z=200.
        {"m": 1, "t": 2000},   // Next, move camera to state 1 over 2 seconds (z=500).
        {"m": 0, "t": 3000},   // Next, move camera to state 0 over 3 seconds (z=200 and xRotation=10).
        {"m": 1, "t": 1000},   // Next, move camera to state 1 over 1 second (z=500).
        {"m": 2, "t": 5000},   // Next, move camera to state 2 over 5 seconds (z=300 and xRotation=20).
        {"l": 1, "c": 1}   // Next, loop back to transition state 1 which tells the camera to move to state 1 over 2 seconds (z=500). Only does this loop once since count=1.
    ]
}
            

The folds object represents all of the folds on this page. If you were to fold the page up and then unfold it, the creases on the page will help you enter this info. This is tricky at the start. Look at some of the examples and play around with it.

Name Type Default Description
d number 0 Direction fold. Options include: 0 | 1. Use 0 to fold away and 1 to fold toward.
f0 object Left side of fold. This is a new folds object which new folds can be applied to. The initial point of this object starts at the new fold.
f1 object Right side of fold. This is a new folds object which new folds can be applied to. The initial point of this object starts at the new fold.
h0 boolean false Hides polygons before folded.
h1 boolean false Hides polygons after folded.
i0 * number Side to use for first point of fold.
i1 * number Side to use for second point of fold.
label string Use this for complicated folds to help you to keep track of which folds are which.
mx number 180 Max degrees for the fold.
o number 0 Order that the folds should occur. Starts at 0 and progresses through. Folds using the same order number will fold at the same time.
r number 1 Default side to rotate. Other side will not move.Options include: 0 | 1.
w0 * number Distance in percentage from first point of first side for fold.
w1 * number Distance in percentage from first point of second side for fold.
ws number 0 Wrap size is used when folding on folds. Sometimes you need to have a fold wrap around other folds to have correct overlay. Each increment of 1 offsets fold by one thickness amount.

Here is a more complicated product:

[{
    "thickness": 20,
    "thicknessSrc": "images/sandwich.jpg",
    "width": 666,
    "height": 514,
    "faces": [{
        "processes": [{
            "type": "regular",
            "src": "images/front.jpg"
        },
        {
            "type": "spotUV",
            "src": "images/front_uv.jpg"
        }]
    }, {
        "processes": [{
            "type": "regular",
            "src": "images/back.jpg"
        }, {
            "type": "KRE8-3D",
            "src": "images/back_uv.jpg"
        }]
    }],
    "folds": {
        "i0": 0,
        "i1": 3,
        "w0": 0.386,
        "w1": 0.5,
        "d" : 0,
        "o" : 0,
        "f1": {
            "i0": 3,
            "i1": 4,
            "w0": 0.614,
            "w1": 1.0,
            "d" : 0,
            "o" : 0,
            "f0": {
                "i0": 2,
                "i1": 4,
                "w0": 0.5,
                "w1": 0.5,
                "d" : 0,
                "o" : 1
            }
        }
    }
}]
            

Initial Parameters

When creating a new instance of DVV, there are several parameters that are required. These have an asterisk next to their name. A double asterisk means that that parameter OR a different parameter must be present. All of the rest are either optional or have default values. The following table shows the list of available parameters:

Name Type Default Description
keyboardEnabled boolean false If set to true, keyboard can be used to move product around.
logLevel string "error" Logging level to use. (log | debug | info | warn | error | off)
name * string "davinciViewer" This parameter tells DVV what the name of the div is where DVV should be placed. This will normally be davinciViewer.
pageNum int 0 Page index you want to view. (0-N)
pages * string This is a JSON object that contains information on the product you want to view. (more info)
mouseWheelEnabled boolean true If set to true, mouse wheel will toggle DVV zoom but will block normal mouse wheel function like page scrool. Set to false if you don't need the zoom feature and would like to have the mouse wheel propagate up to browser for normal mouse wheel use.
onInit function Use this to attach a callback method which is called once DVV is initiated and app is ready. No parameters are returned in the method.
onLoadFailed function Use this to attach a callback method which is called if DVV fails to initialize. No parameters are returned in the method. This will be called if WebGL isn't supported.

When you call new opensoft.Davinci( ... ) in the embed tag, it ques a new instance to load. Several things need to be loaded before it actually builds that instance of DVV. Once the initial work is done, future creation of instances on same page are synchronous. The onInit param allows you to detect when the instance is done building. If you want to check if the initial work is already complete, you can call opensoft.Davinci.isReady . If you create an instance of DVS and wait for the onInit to come back, from then on opensoft.Davinci.isReady will be true on that page. If an instance fails to initiate, the onLoadFailed initial param (if given) will be called.

Commands

All commands take an object of property-value pairs as a parameter.

Function Description
animateFold

Params:

An object of attribute/value pairs to set. Attributes as follows:

  • action - (string) The state of the folding. Options include: 'paused' | 'open' | 'close'

Returns:

  • none

Info:
Toggles the animation of the product folding.

Example:

DVV.app.animateFold({action: 'close'});
                                

changePage

Params:

An object of attribute/value pairs to set. Attributes as follows:

  • pageNum - (number) The page you want to display. Page index starts at 0.

Returns:

  • none

Info:
Displays given page number of product.

Example:

DVV.app.changePage({pageNum: 0});
                                

pause

Params:

  • none

Returns:

  • none

Info:
Toggles the spinning of the product.

Example:

DVV.app.pause();
                                

rebuild

Params:

  • Same params as init. Although, if root, logLevel, or pageNum is left off, it will default to what is already used.

Returns:

  • none

Info:
Clears and rebuilds current product. Similar to creating a new instance.

Example:

DVV.app.rebuild();
                                

destroy

Params:

  • none

Returns:

  • none

Info:
Cleans up and removes instace.

Example:

DVV.app.destroy();
                                

These are synchronous events that you can listen for.

Events Description

None at this time...