disguise developers

2.5D Assets

2.5D assets consist of a series of 2.5D plates, with optional meshes or depth maps, used to construct a seemingly 3D scene out of 2D image or video content. These assets can be exported from Designer, or created with 3rd party integrations such as cuebric. For more information on the 2.5D workflow in Disguise, see 2.5D workflow.

Assets are saved as a .2p5d file, which can be shared between projects and applications. This page describes the format for these files, which can be used to build additional custom integrations for 2.5D assets.

Format Overview

A .2p5d file is a renamed .zip file. By changing the extension back to .zip it is possible to extract the contents and see what is contained inside.

A .2p5d file contains the following files within it:

Data JSON

The data.json file contains a nested structure of properties. The top level objects are as follows:

meta

The meta object contains the following properties:

asset

The asset object contains the following properties:

See below for further information on how these values are defined.

plates

The plates property is an array of objects, each containing the following properties for each plate:

Example

Here is an example data.json file for a simple 2.5D asset with two plates.

{
    "meta": {
        "version": "1.0.0",
        "generator": "Disguise Designer"
    },
    "asset": {
        "max_depth": 100,
        "min_depth": 10,
        "field_of_view": 90
    },
    "plates": [
        {
            "name": "Background",
            "filename": "background_image.png",
            "depth_map_filename": "background_depth.png",
            "width": 1920,
            "height": 1080,
            "x": 0,
            "y": 0,
            "z": 0.75,
            "scale_x": 1,
            "scale_y": 1,
            "scale_z": 1,
            "rotation_x": 0,
            "rotation_y": 0,
            "rotation_z": 0,
            "mean_depth": 0.4
        },
        {
            "name": "Foreground",
            "filename": "foreground_image.png",
            "depth_map_filename": "foreground_depth.png",
            "width": 512,
            "height": 200,
            "x": 0.4,
            "y": -0.2,
            "z": 0.2,
            "scale_x": 0.25,
            "scale_y": 0.2,
            "scale_z": 1,
            "rotation_x": 0,
            "rotation_y": 0,
            "rotation_z": 0,
            "mean_depth": 0.05
        }
    ]
}

Image and video files

Image and video files for each plate should be placed in the .2p5d file with the name and extension defined by filename in data.json.

Format restrictions for these files are the same as for Disguise Designer in general. See Supported file formats for information on supported video and image formats.

Depth maps

Depth maps can optionally be provided for each plate, placed in the .2p5d file with the name and extension defined by depth_map_filename in data.json. Both still image and video depth maps are supported in Designer and these should be saved as a greyscale image/video sequence with the same resolution as the plate image/video.

The depth information should be defined as inverse normalised depth, where white (1.0) corresponds to min_depth and black (0.0) corresponds to max_depth defined in the asset object in data.json. The equation to convert a colour value in this format to absolute depth in metres is:

 depth = (max_depth * min_depth) / (colour * (max_depth - min_depth) + min_depth)

An example depth map is shown below.

Example Depth Map

Format restrictions for these files are the same as for Disguise Designer in general. See Supported file formats for information on supported video and image formats.

Meshes

Plate shapes can be defined using OBJ meshes rather than depth maps. These meshes should be placed in the .2p5d file with the name and extension defined by mesh_filename in data.json.

In general, it is expected that meshes will have a width (x) and height (y) of 1 to fit within the view frustrum, with the scale values being used to represent any scaling outside of the frustum area.

Plate positioning units

2.5D Units

The image above highlights how the variables defining the positioning of the plates within the asset are defined. Since a 2.5D asset generally represents a layered view of a scene from a single eye point, the variables are referenced relative to this viewing frustum.

The asset parameters are defined as follows:

The plate parameters are defined as follows:

 depth = z * (max_depth - min_depth) + min_depth

 z = min_depth * (1 - mean_depth) / (mean_depth * (max_depth - min_depth) + min_depth)