API.js

API.js is a library that is used for communication between widget showing WebGL representation of the model and the surrounding web shop content management system.

It has two important modules:

RPC

RPC, abbreviation for Remote Procedure Call, is a module that has two main functionalities:

Sending messages to iframe is key to tell iframe that user has chosen some new color/background/material... and that the iframe should adjust it's content and show someting different.

The developer that integrates WebGL configurator into his content management system or web shop does not need to use or initialize or use the module himself. The module is initialized and used only by API module.

API

API, abbreviation for Application Programing Interface, is a module that uses RPC as communication channel and exposes the core functionalities of WebGL configurator widget to the surrounding content management system. It gives a developer that is integrating WebGL configurator into his system an easy, intuitive way to interact with the iframe and it's content.

API.init()

A function that needs to be called after page finishes loading (usually by the body's onload event).

MODEL

API.setColor(colors)

Selects colors for specified parts of the model

Syntax:

    API.setColors({
        "fabric": "#ffffff",
        "patent": "#ff00aa",
    });

TEXT

API.addText(text, x, y, size, angle, strokeWidth, strokeColor, fillColor, fontFamily, fontStyle, textDecoration)

Adds text to the model.

Only text field is required, others are optional.

Positions are:

front: X: 30 .. 560 Y: 50 .. 715

back: X: 515 .. 985 Y: 50 .. 715

API.removeText()

Removes text from model.

API.setText(text)

Changes text content in the front of the model.

API.setFontSize(size)

Changes font size.

API.setTextPosition(X, Y)

Places text on model on specific position. Position is dependent on the model and how textures are mapped on it. How it applies to real world takes some experimentation.

API.setTextAngle(angle)

Rotates to the left by angle in degrees from 0 to 360.

API.setFontFamily(fontfamily)

Sets the font family of the text. Available fonts are subject to fonts available on client's system and browser of choice. It is reccomended to stick with most commom fonts for highest interoperability.

API.setFontStyle(fontstyle) - WORK IN PROGRESS

Sets the additional styles to the font (currently only italic).

API.setTextDecoration(decoration) - WORK IN PROGRESS

Sets the additional decoration to the text (currently underline and strikethrough).

API.setTextStrokeWidth(color)

Sets the outline stroke of text. Default is 0.

API.setTextStrokeColor(color)

Sets the color of the outline of the text.

API.setTextFillColor(color)

Sets the fill color of the text.

CAMERA

API.setCamera(view) - WORK IN PROGRESS

Changes the camera view. Currently available:

IMAGE

API.addImage(name, imageUrl, x, y, scaleX, scaleY, angle)

Adds an image to the currently shown model. Name must be unique in order to be able to modify it's position and scale or to be able to remove it. Names can be named arbitrarily, most commonly image1, image2, ...

Currently only one image can be imported and name is ignored. The method prototype is in place for future use where multiple images will be possible

name and imageUrl are required parameters, others are optional.

API.removeImage(name)

Remove previously added image.

API.setImagePosition(name, X, Y)

Move image

API.setImageScale(name, scale)

Scale image.

API.setImageAngle(name, angle)

Rotate image.

SCREENSHOT

API.screenshot()

Fires an action to take screenshot. The actual data will be given via API.screenshotResult callback event.

EVENTS (OVERRIDABLE METHODS)

Methods in this section are a way to signal the develper that something in the iframe has changed. Most common events are when end user moves text or image. These methods are by themselves abstract and empty, they do nothing on their own. They are intended to be overriden by developer.

API.textPosition(x, y, width, height, angle, scale)

Callback method that gets called when text position on the model changes.

Example how to override this method is:

// excerpt from index.js

API.textPosition = function(x, y, width, height, angle, scaleX, scaleY) {
    document.getElementById("textX").value = x;
    document.getElementById("textY").value = y;
}

Reminder: measurements are not expressed with real-life measurement units. It is near impossible (at the moment) to get accurate measurements in milimeters (or any other measurement units). They are pixels on the texture that contains rendered text and is projected on model. To get real life measurements, the developer must move text to all extremes and calculate position in percentages, which can then be used (depending on real model) there to position the text.

API.imagePosition(x, y, width, height, angle, scaleX, scaleY)

Similar to textPosition, this method is a callback that signals the change in position, scale or angle of image placed on the model.

API.screenshotResult(width, height, pngData)

Resulting callback event that developer must override to get screenshot from iframe. It returns width, height and pngData of an image. pngData is represented in data:image/png;base64

Developer (if using Chrome) can console.log(rawData) and copy the resulting PNG data from Developer Tools Console into URL and the actual image will show in browser. This data can then be further used in the process, like sending to server for order processing.