Accessing the 3D Folding Viewer

Launching the 3D Folding Viewer from the editor

If a folding setting is linked to a document, you can launch the 3D folding viewer by pressing the “show folding view” button in the toolbar:

More information on how to configure folding settings and linking them to a document can be found /wiki/spaces/CPDOC/pages/1412440.
However, to be able to launch the 3D viewer, you must enable this feature. 3D folding in CHILI is hardware accelerated. The Flashplayer needs to know hardware acceleration is required. By default this is not the case. To do this, all you need to do is add the following parameter to the editor URL: "enableFolding=true" for CHILI Publisher versions older then version v4.0.3.0. As of v4.0.3.0 a new query string parameter “enable3D=true” for folding and 3D models, replaces the "enableFolding parameter” (existing implementations using the old parameter will continue to work, in the background the enable3D parameter will be set, but it is advised to use the new parameter for new implementations).

The standalone 3D Folding Viewer

At some point in your workflow you may want to display a 3D folded document, without loading the editor. This is possible using the 3D folding viewer. The CHILI webservice has a function to retrieve the URL of a folding viewer for a specific document.
This webservice function is called “DocumentGetFoldingViewerURL”. This function takes 4 parameters:

apiKey: A valid API key
itemID : The document ID for which to return the Folding Viewer URL
foldingSettingsID : This is an optional parameter. This parameter makes it possible to use a folding scheme of your choice and apply it to the document. If not provided, the folding settings in the document are used.
modXML : This is also an optional parameter. This XML describes the modifications applied to the folding setting. This enables you to update the width and height of each individual panel. For example, if you want to change the width of a cover spine, you can do it this way, without affecting the original folding scheme.

To access the standalone viewer in HTML use this call: DocumentGetHTMLFoldingViewerURL (the parameters stay the same).
It works exactly the same as DocumentGetFoldingViewerURL, but instead of returning the Flash based 3D viewer, you will get the URL of javascript/WebGL based 3D viewer.

Only on WebGL enabled devices/browsers !

Modifying a folding scheme

A valid mod XML has the following structure:

<items>

<item panelName=”panel name”>

<prop name=”panelWidth” value=”100” />

<prop name=”panelHeight” value=”100” />

</item>

</items>

All values are pixel values. If you change the width, height or position, you should always convert your values to pixel values.

To be able to use this, it is important to understand how a folding scheme is structured. A folding scheme is actually a tree of panels. Each panel can have child panels. And each scheme is made out of at least 1 panel, called the root panel.

The root panel is the only panel that has an absolute coordinate. Moving this panel will also move all of its child panels (and their child panels).
Each panel has its own coordinate space, and is attached to the side of another panel (except for the root panel). On the below scheme the green dots represent the origin points (zero points) of the panels. The green arrows represent their Y axis.

You can move the scheme around by setting the rootX and rootY values on the root panel:

<item panelName=”root panel”>

<prop name=”rootX” value=”100” />

<prop name=”rootY” value=”100” />

</item>

Other panels are attached to another panel. By default they are placed at the center of the side they are attached to. But it is possible to move these panels by setting the “hingeOffset” value

</item>

There are however some pitfalls to consider. If a panel is resized, the position of its child panels is likely to change. Their coordinates are relative because they are attached to another panel.
For example, see the below image:

In this situation we have a typical cover spine scheme. The root panel being the spine. By changing its width, we push both the right panel and the left panel to the side. For this scheme this even problematic because the left panel is pushed beyond the borders of the document. In this case we need to compensate this by moving the root panel to the right (by the change in width devided by 2). We do this by modifying the "rootX" property of the root panel. How to compensate for this behavior depends on how your document is set up. In this example the document was configured to expand to the right depending on the width of the spine.

Additional modXML changes

The mod XML allows you to change any property on a panel in the 3D Folding XML.

Let's consider the following 3D Folding XML:

3D Folding XML

<folding debugMode="false" showStats="false" calculatePanelCollisions="false" allowMouseInteraction="true"
         adjustCameraTargetPosition="false" freeCamera="false" startPosition="unfolded" initialCameraX="0"
         initialCameraY="0" diecutMirroredOverYAxis="true" show3DStats="false"
         documentId="e1b6d49c-d459-4129-bf1e-cbcf9e93a037" maskAssetId="" backgroundColor="14540253"
         renderPanelOutLines="false" useComposedMaterial="false" rootX="420" rootY="595" originalDocumentHeight="595"
         originalDocumentWidth="842" initialCameraRadius="650" iconSetID="" autoPlaySequence="false"
         loopSequence="false" initialCameraTargetX="0" initialCameraTargetY="0" initialCameraTargetZ="0"
         invertMask="false">
    <panels>
        <item panelId="0F89FF94-782C-D771-1989-8DC8C9525005" panelName="root panel" minRot="0" maxRot="0" initialRot="0"
              startRot="0" endRot="0" hingeOffset="0" panelWidth="280.6254" panelHeight="595.266" attachedToSide="0"
              creaseBottom="0" creaseTop="0" creaseLeft="0" creaseRight="0" ignoreCollisions="false"
              mouseEnabled="true">
            <attachedPanels>
                <item panelId="4CBDF01E-318D-1719-6AA5-A374775DE09E" panelName="panel2" minRot="-180" maxRot="180"
                      initialRot="0" startRot="0" endRot="90" hingeOffset="0" panelWidth="595.266"
                      panelHeight="280.6254" attachedToSide="3" creaseBottom="0" creaseTop="0" creaseLeft="0"
                      creaseRight="0" ignoreCollisions="false" mouseEnabled="true">
                    <attachedPanels/>
                </item>
                <item panelId="878DDC01-29F2-2551-D136-A3747B92942E" panelName="panel3" minRot="-180" maxRot="180"
                      initialRot="0" startRot="0" endRot="90" hingeOffset="0" panelWidth="595.266"
                      panelHeight="280.6254" attachedToSide="1" creaseBottom="0" creaseTop="0" creaseLeft="0"
                      creaseRight="0" ignoreCollisions="false" mouseEnabled="true">
                    <attachedPanels/>
                </item>
            </attachedPanels>
        </item>
    </panels>
    <sequences>
        <sequence/>
    </sequences>
</folding>

The following properties can be changed on a panel:

minRot
maxRot
initialRot
startRot
endRot
hingeOffset
panelWidth
panelHeight
attachedToSide
creaseBottom
creaseTop
creaseLeft
creaseRight
ignoreCollisions
mouseEnabled

On top of this, it is possible to change general properties on the 3D folding model. The attributes that can be found on the folding element in the XML above.

debugMode
showStats
calculatePanelCollisions
allowMouseInteraction
adjustCameraTargetPosition
freeCamera
startPosition
initialCameraX
initialCameraY
diecutMirroredOverYAxis
show3DStats
documentId
maskAssetId
backgroundColor
renderPanelOutLines
useComposedMaterial
rootX
rootY
originalDocumentHeight
originalDocumentWidth
initialCameraRadius
iconSetID
autoPlaySequence
loopSequence
initialCameraTargetX
initialCameraTargetY
initialCameraTargetZ
invertMask

Many of these properties shouldn't be changed or there is no use in changing them. But some of these might prove to be useful when trying to apply documents that have different sizes to the 3D Folding model.

For example when the folding model expects a square document, but you are applying it to a portrait-shaped document, the document will be distorted when placed onto the model. To change this, you will have to update the rootX, rootY, originalDocumentHeight and originalDocumentWidth properties alongside the different panels in the mod XML.

To change these properties that are on the folding element of the folding XML, you must update them via the rootPanel. In a previous example we have described that you can use the rootX and rootY properties to move the root panel around. In the same way you can now also update the original document width and height. Keep in mind though that changing the rootX and rootY values will influence all other panels too, since all other panels are attached to the root panel.

   <item panelName="root panel">
          <prop name="rootX" value="50" />
          <prop name="rootY" value="200" />
          <prop name="originalDocumentHeight" value="100" />
          <prop name="originalDocumentHeight" value="200" />
          <prop name="panelWidth" value="33" />
          <prop name="panelHeight" value="200" />
   </item>