> For the complete documentation index, see [llms.txt](https://virtualfactory.gitbook.io/vlft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://virtualfactory.gitbook.io/vlft/tools/vebjs/input-output.md).

# Input/Output files

Input files define the content of the [scene](#scene), the [animation](#animation), the [environment ](#environment)setup, and the app [configuration](#undefined). All input files can be specified using URL parameters. If not explicitly specified, VEB.js will try to load the animation, environment and configuration files of a scene according to the following convention. Given a scene file named `scene.json`, the convention is that the corresponding animation file is named `scene_anim.json`, the environment file `scene_env.json`, and the configuration file `scene_config.json`. 

[Examples of input files ](/vlft/use-cases/assets-and-animations.md)are provided in the Use Case section.

## Scene

Scenes can be imported/exported from/to a **.json** file according to a [specific schema](/vlft/kb/instantiation/assets/json.md). 

## Animation

The animation of the scene can be defined in a [**.json** file](/vlft/kb/instantiation/animations.md) together with additional data (e.g. reusable animation sequences) stored as [**.txt** files](/vlft/kb/instantiation/animations.md#animation-sequence).

## Environment

The environment setup is defined in a .json file according to a schema with the following root properties:

* "**cameras**": an array defining cameras to navigate the scene. Each camera can be characterized by "id", "type" (e.g. "FlyCamera", "FreeCamera", "ArcRotateCamera", etc.), "position", "rotation", "speed".
* "**lights**": an array defining sources of light in the scene. Each light can be characterized by "id", "type" (e.g. "HemisphericLight", "PointLight", etc.), "position" or "direction", "intensity".
* "**shadows**": an object specifying how shadows are generated with properties "darkness", "bias", "environmentIntensity".
* "**datagen**": definition of parameters for the generation of synthetic data, in particular screenshots.
  * "**cam**": definition of movements of the ArcRotateCamera during the automatic generation pointing the selected mesh in terms of alpha, beta and radius. Alpha and beta are degrees (angles) of rotation around the vertical axis and inclination w\.r.t. the horizontal plane. The radius is calculated multiplying the diagonal of the selected asset bounding box by a factor.
    * "**alphaMin**": starting value of alpha
    * "**alphaMax**": maximum value of alpha
    * "**alphaStep**": incremental step of alpha
    * "**betaMin**": starting value of beta
    * "**betaMax**": maximum value of beta
    * "**betaStep**": incremental step of beta
    * "**radiusFactorMin**": starting value of radiusFactor
    * "**radiusFactorMax**": maximum value of radiusFactor
    * "**radiusFactorStep**": incremental step of radiusFactor
  * "**background**": definition of parameters for the generation of an artificial background
    * "**fragmentMode**": strategy used to create each background element. Possible values: "box" (cube/box primitives with sampled materials), "clone" (clone real scene meshe), "csg" (cut fragments from scene meshes using BABYLON.CSG2)
    * **surfaceMode**: shape of the virtual surface on which background elements are placed. Possible values: "plane" (flat wall), "cylinder" (curved wall around the asset horizontally), "sphere" (curved shell around the asset horizontally and vertically)
    * **volumeForm**: shape proportions used when fragmentMode is "box". Possible values: "cube" (equal width, height, and depth), "box" (moderately rectangular block), "elongated" (long, thin block), "mixed" (random mixture of cube, box, and elongated blocks)
    * **fragmentCount**: Number of generated background elements. Higher values make the background denser but increase render cost.
    * **sourceCount**: maximum number of scene meshes used as source material/shape references. With fragmentMode "box", these provide colors/materials. With fragmentMode "clone", these provide actual cloned shapes. Higher values increase visual variety.
    * **distanceFactor**: distance of the background surface from the selected asset, expressed relative to the selected asset size. Higher values move the background farther away.
    * **widthFactor**: horizontal size of the background surface, relative to the selected asset. Higher values make the background wider.
    * **heightFactor**: vertical size of the background surface, relative to the selected asset. Higher values make the background taller.
    * **fragmentSizeFactor**: size of each background element, relative to the selected asset. This is the main parameter for larger or smaller fragments.
    * **minDepthRatio**: minimum depth of generated box fragments, relative to their largest side. Higher values prevent thin sheet-like pieces. Used only with fragmentMode "box".
    * **jitterRatio**: random displacement applied to each element from its regular grid point. Value 0.0 gives an ordered grid; higher values give a more
    * **seed**: deterministic random seed. Same seed + same scene + same parameters gives the same background. Change it to generate a different arrangement.
    * **minSourceSizeFactor**: minimum allowed source mesh size, relative to the selected asset radius. Smaller source meshes are ignored. Lower values include tiny details such as buttons/screws, while higher values focus on larger scene objects.
    * **maxSourceSizeFactor**: maximum allowed source mesh size, relative to the selected asset radius. Larger source meshes are ignored. Lower values avoid huge floor/wall/conveyor parts dominating the sample, while higher values allow large objects to contribute.
    * **materialVariation**: random brightness variation applied to sampled materials. Value 0.0 keeps original material colors; higher values add more variation.
    * **faceCameraFragments**: if true, each fragment is rotated to face the camera like a billboard. This can improve coverage but makes 3D blocks look like flat sheets. Keep false for real-looking volumetric blocks.
    * **materialSampling**: strategy used to choose source meshes for colors/materials. Possible values: "uniform" (every eligible mesh has equal probability), "surfaceArea" (larger meshes are sampled more often, usually producing colors closer to the global scene appearance).
    * **saturatedColorPenalty**: penalty applied to highly saturated colors during material sampling. Useful when small red/yellow/green/blue parts are over-represented. Value 0.0 disables the penalty; 1.0 strongly suppresses saturated colors.
    * **colorSaturationFactor**: desaturation factor applied to cloned/sampled material colors. Value 1.0 keeps original colors, while 0.0 converts colors fully toward gray.
* "**env**": 
  *  "**skyboxTexture**": texture to be used for a skybox environment (default "textures/studio.env")
  * "**backgroundColor**": color of the background defined as an array of floats representing the RGB values (default \[0.2,0.2,0.3]
  * "ground": parameters defining the ground
    * "**texture**": texture to be used for the ground (absent by default)
    * "**size**": array of integer values defining the width, height, and subdivision of the ground
    * "**mass**": mass of the ground.

## Configuration

The app configuration is defined in a .json file according to a schema with the following root properties:

* "**endpoint**": definition of the SPARQL endpoint to query/update an ontology. Its properties are:
  * "**server**": address of the server 
  * "**database**": name of the database
  * "**user**": user
  * "**psw**": password
* "**repo**": definition of the repositories that are relevant to load a VR scene
  * "**model3d**": repository of the 3D models 
  * "**animation**": repository of the animation sequences
  * "**sparqlDir**": repository of the SPARQL query/update templates
* "**MQTT**": definition of MQTT communication settings
  * "**broker**": URL of the broker
  * "**sub\_base\_topics**": array of base topics (that are customized with the addition of the scene name) for MQTT subscriptions
  * "**pub\_base\_topics**": array of base topics (that are customized with the addition of the scene name) for MQTT publishing
  * "**QoS**": quality of service (0, 1, 2)