Pictofit / Web SDK / 7.3.1 / Configuration

Configuration

The Pictofit Web SDK allows you to load an entire scene based on a configuration file. This makes it very easy to define a 3D scene with arbitrary content. For every asset generated through our Pictofit Content Service, a configuration file is provided as well. This allows for easy loading of the assets with just a few lines of code. But you can also write your own config files or extend the ones provided by us to customise your 3D scene without having to write code. This section explains how this can be done. For further details on the used babylon.js classes, please see the respective reference (links are provided).

File Structure

This snippet shows an example configuration to give you the basic idea of the structure. The configuration files are in the .json format and very easy to understand and to write.

Each file starts with a version entry which should be set to 2. We also support legacy configuration file formats meaning your old config files will still work with newer versions of the SDK. The next root entry in the configuration is the scene node which defines the content of the scene. The following sections describe the possible elements in more detail.

{
  "version" : 2,
  "scene" : {
    "materials": [
    ],
    "nodes" : [
      {
        "name" : "MyMesh",
        "type" : "Mesh",
        "uri" : "mesh.obj",
        "material" : {
          "name" : "MyMesh-material",
          "type" : "StandardMaterial",
          "emissiveColor" : [1, 1, 1],
          "diffuseTexture" : {
            "uri" : "texture.jpg"
          },
          "disableLighting" : true
        }
      },
      {
        "name" : "Orbit",
        "type" : "ArcRotateCamera",
        "target" : "MyMesh",
        "useAutoRotationBehavior" : true
      }
    ]
  }
}

Scene

This property contains all elements which are actually part of the scene. The main entry is the nodes section. It describes the actual scene graph. Or in other words: All elements that actually part (and visible in one way or another) of your scene. The defaultEnvironment section allows you to define basic properties like the color or a skybox in a handy way. Finally, the materials section can be used to define the respective entities in a global way so that they can be referenced by elements in the scene. The environmentTexture properties allows you to define a texture that is then used by all PBR materials by default. This is handy since you usually want to use the same texture for all of them.

{
  "clearColor" : [number, number ,number],
  "environmentTexture" : CubeTexture,
  "defaultEnvironment" : DefaultEnvironment,
  "materials" : [ Material ],
  "nodes" : [ Node ]
}

Default Environment

This property is a a helper to define commonly used elements like a ground plane, a skybox or a general color scheme. This simply speeds up the process of setting up a scene.

{
    "createGround" : boolean,
    "createSkybox" : boolean,
    "mainColor" : [ number, number, number ],
    "groundSize" : number,
    "skyboxSize" : number,
    "skyboxColor" : [ number, number, number ],
    "groundColor" : [ number, number, number ],
    "groundShadowLevel" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.environmenthelper

Materials

A material defines the apperance of a model. Currently, we support the “StandardMaterial” from babylon.js but more will follow in the future. Materials can be defined in the material section of the scene object or inline as property of a mesh. Defining them in the material sections ensurse that they are parsed before any scene element and therefore you can reference and use them from any mesh in your scene.

To see the different materials in action, please check out our material editor sample.

Material Editor Sample
  • Material (abstract)
    • StandardMaterial
    • PBRMaterial
    • PBRMetallicRoughnessMaterial

Material (absract)

{
    "type" : "Material",
    "name" : string,
    "backFaceCulling" : boolean,
    "wireframe" : boolean,
    "pointsCloud" : boolean,
    "pointSize" : number,
    "alpha" : number
}

Standard Material

{
    "type" : "StandardMaterial",
    "diffuseTexture" : Texture,
    "specularTexture" : Texture,
    "opacityTexture" : Texture,
    "bumpTexture" : Texture,
    "reflectionTexture" : CubeTexture,
    "invertNormalMapX" : boolean,
    "invertNormalMapY" : boolean,
    "diffuseColor" : [ number, number, number ],
    "specularColor" : [ number, number, number ],
    "emissiveColor" : [ number, number, number ],
    "specularPower" : number,
    "disableLighting" : boolean,
    "reflectionFresnelParameters" : FresnelParameters,
    "emissiveFresnelParameters" : FresnelParameters,
    "opacityFresnelParameters" : FresnelParameters,
    "diffuseFresnelParameters" : FresnelParameters
}

To see how materials can be usued to adjust the apperance of mannequins, have a look at this example babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.standardmaterial

Fresnel Parameters

Encapsulates parameters to configure the fresnel effect.

{
    "type" : "FresnelParameters",
    "bias" : number,
    "power" : number,
    "leftColor" : [ number, number, number],
    "rightColor" : [ number, number, number]
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.fresnelparameters

PBR Material

{
    "type" : "PBRMaterial",
    "albedoColor" : [ number, number, number],
    "albedoTexture" : Texture,
    "metallic" : number,
    "roughness" : number,
    "metallicTexture" : Texture,
    "reflectionTexture" : Texture | CubeTexture,
    "reflectivityColor" : [ number, number, number],
    "refractionTexture" : Texture | CubeTexture,
    "microSurface" : number,
    "indexOfRefraction" : number,
    "directIntensity" : number,
    "environmentIntensity" : number,
    "subsurface" : SubSurface
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.pbrmaterial

Sub Surface

{
    "type" : "SubSurface",
    "isRefractionEnabled" : boolean,
    "indexOfRefraction" : number,
    "refractionIntensity" : number,
    "isTranslucencyEnabled" : boolean,
    "translucencyIntensity" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.pbrsubsurfaceconfiguration

PBR Metallic Roughness Material

This is a simpler version of the PBRMaterial with limited options. Usually this is more then enough and performance-wise it makes sense to use this limited version if you don’t need any of the features of the more sofisticated version.

{
    "type" : "PBRMetallicRoughnessMaterial",
    "baseColor" : [ number, number, number],
    "baseTexture" : Texture,
    "metallic" : number,
    "roughness" : number,
    "metallicRoughnessTexture" : Texture,
    "environmentTexture" : Texture | CubeTexture
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.pbrmetallicroughnessmaterial

Textures

Textures are used to define properties like color, reflectivitly, transparency and bumpyness of your objects. At the moment, we support the standard texture and cube textures (for e.g. reflections and sky boxes).

  • BaseTexture (abstract)
    • Texture
    • CubeTexture

BaseTexture (abstract)

{
    "type" : "BaseTexture",
    "name" : string,
    "uri" : string,
    "getAlphaFromRGB" : boolean,
    "wrapU" : number,
    "wrapV" : number,
    "coordinatesMode" : number,
    "level" : number,
}

Texture

{
    "type" : "Texture",
    "invertY" : boolean,
    "samplingMode" : number,
    "noMipmap" : boolean
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.texture

CubeTexture

{
    "type" : "CubeTexture",
    "noMipmap" : boolean
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.cubetexture

Nodes

The nodes properties contains all elements of the scene graph. The elements described in the following sections inherit form the base node, meaning they support the properties described here as well. The most basic type that can be instantied is the TransformNode. It allows you to group elements through the children property and position them in the 3D space. Any element that dervies directly or indirectly from Node can be added as a child.

  • Node (abstract)
    • TransformNode

Node (abstract)

{
    "type" : "Node",
    "name" : string,
    "children" : [ Node, ... ]
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.node

TransformNode

{
    "type" : "TransformNode",
    "position" : [ number, number, number ],
    "rotation" : [ number, number, number ],
    "scaling" : [ number, number, number ],
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.transformnode

Meshes

Meshes define the 3D objects in your scene. They can be loaded from various file formats or you can also generate primitive shapes (cubes, planes, cylinders, …) directly using the respective prefab types. Since meshes drive from the TransformNode class, they can be positioned and support a parent-child hierarchy as well. To configure how a mesh should be rendered, you will want to assign a material to it. This can by done by referencing a globally defined one by its name or by defining one inline.

  • Node (abstract)
    • TransformNode
      • Mesh
      • InstancedMesh

Mesh

{
    "type" : "Mesh",
    "uri" : string,
    "sourceMesh" : string,
    "material" : StandardMaterial | string,
    "isVisible" : boolean,
    "showBoundingBox" : boolean,
    "mustDepthSortFacets" : boolean,
    "renderOutline" : boolean,
    "outlineColor" : [ number, number, number ],
    "renderOverlay" : boolean,
    "overlayColor" : [ number, number, number ]
}

Either specify a uri to load meshes from files or sourceMesh to clone an existing mesh. Cloned meshes share some data like the geomtry with the source but can have differnt transformations, materials, etc.

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.mesh

InstancedMesh

{
    "type" : "InstancedMesh",
    "sourceMesh" : string,
    "position" : [ number, number, number ],
    "rotation" : [ number, number, number ],
    "scaling" : [ number, number, number ],
}

Instanced meshes share all data and properties with the source mesh except for position, rotation and scaling. This is a very efficient way of adding multipe instanced of a mesh to your scene which only differ in transformation.

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.instancedmesh

Box

{
    "type" : "BoxPrefab",
    "size" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.meshbuilder#createbox

Cylinder

{
    "type" : "CylinderPrefab",
    "height" : number,
    "diameterTop" : number,
    "diameterBottom" : number,
    "tessellation" : number,
    "subdivisions" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.meshbuilder#createcylinder

Plane

{
    "type" : "PlanePrefab",
    "size" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.meshbuilder#createplane

Sphere

{
    "type" : "SpherePrefab",
    "segments" : number,
    "diameter" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.meshbuilder#createsphere

Cameras

A camera defines your view into the virtual world. We support two types of cameras: The FreeCamera which allows users to navigate through the scene unconstrained and the ArcRotateCamera which orbits around a set of defined objects and ensures that these are always in focus. Both derive from TargetCamera which can’t be instanciated directly. All instances of TargetCamera can define a target property which either can be a position or an arry of meshes to focus on. A good introduction an cameras can be found under https://doc.babylonjs.com/divingDeeper/cameras.

  • Node
    • TargetCamera (abstract)
      • ArcRotateCamera
      • FreeCamera

TargetCamera (abstract)

{
    "type" : "TargetCamera",
    "fov" : number,
    "minZ" : number,
    "maxZ" : number,
    "position" : [ number, number, number ],
    "target" : [ number, number, number ] | [ string, ... ],
    "upVector" : [ number, number, number ]
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.targetcamera

FreeCamera

{
    "type" : "FreeCamera"
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.freecamera

ArcRotateCamera

{
    "type" : "ArcRotateCamera",
    "useAutoRotationBehavior" : boolean,
    "autoRotationBehavior" : {
        "idleRotationSpeed" : number,
        "idleRotationSpinupTime" : number,
        "idleRotationWaitTime" : number,
        "zoomStopsAnimation" : boolean
    },
    "horizontalAngle" : number,
    "verticalAngle" : number,
    "upperVerticalAngleLimit" : number,
    "lowerVerticalAngleLimit" : number,
    "radius" : number,
    "upperRadiusLimit" : number,
    "lowerRadiusLimit" : number,
    "minimumZoomLevel" : number,
    "maximumZoomLevel" : number,
    "panningSensibility" : number,
    "wheelPrecision" : number,
    "target" : string | [string]
}

Remark: horizontalAngle is called alpha and verticalAngle is called beta in the babylon.js docs. We renamed them in our configuration file format for the sake of clarity. Furthermore, we’ve introduced an upperVerticalAngleLimit and a lowerVerticalAngleLimit which define the possible rotation range in vertical direction from 0 to 90 degree. The former limits the camera when going up, the latter when going down.

The minimumZoomLevel and the maximumZoomLevel define how close or how far the user can get to the object in a relative way. They only make sense if a target has been set. Setting the minimumZoomLevel to 0.5 means that the user can zoom out until the target fills half of the screen. Analog to this, setting the maximumZoomLevel to 2 means that the user can zoom in until the target is twice as big as it was initially.

The target parameter is used to frame certain scene elements. Here you can provide a mesh name or and array of names if you want the camera to focus on multiple elements. In that case, the joint bounding box of the meshes is used to position and orient the camera. You can also use the wildcard operator * here. This allows you to group elements using a naming schema and then focus onto all with certain prefix like e.g. foreground-*. This is especially handy with cascading as it allows you to reuse a camera configuration for different scenes.

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.arcrotatecamera

Lights

Light sources are important to give your scene an realistic apperance and make them look nice. Adding lights also allows to create shadows. Currently, we support PointLight, DirectionalLight and SpotLight. All of them derive from the ShadowLight which defines the following properties (but can’t be instanciated). To get a better understanding of lights and shadows, have a look at https://doc.babylonjs.com/divingDeeper/lights.

Checkout our lights sample to see this in action.

Lights Sample
  • Node
    • ShadowLight (abstract)
      • PointLight
      • DirectionalLight
      • SpotLight

ShadowLight (abstract)

{
    "type" : "ShadowLight",
    "diffuse" : [ number, number, number ],
    "specular" : [ number, number, number ],
    "intensity" : number,
    "radius" : number,
    "range" : number,
    "shadowMinZ" : number,
    "shadowMaxZ" : number,
    "shadowGenerator" : {
        "mapSize" : number,
        "shadowCasters" : [ string, ... ],
        "usePoissonSampling" : boolean,
        "useExponentialShadowMap" : boolean,
        "useBlurExponentialShadowMap" : boolean,
        "blurScale" : number,
        "blurBoxOffset" : number,
        "useKernelBlur" : number,
        "blurKernel" : number
    }
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.shadowlight https://doc.babylonjs.com/typedoc/classes/babylon.shadowgenerator

PointLight

{
    "type" : "PointLight",
    "position" : [ number, number, number ]
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.pointlight

DirectionalLight

{
    "type" : "DirectionalLight",
    "position" : [ number, number, number ],
    "direction" : [ number, number, number ]
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.directionallight

SpotLight

{
    "type" : "SpotLight",
    "position" : [ number, number, number ],
    "direction" : [ number, number, number ],
    "angle" : number,
    "exponent" : number
}

babylon.js reference: https://doc.babylonjs.com/typedoc/classes/babylon.spotlight

© 2014-2020 Reactive Reality AG