---
title: "2.5D Assets"
description: "Documentation and guidance for building tools and integrations with the Disguise platform."
url: https://developer.disguise.one/formats/2p5d/
---

# 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](https://cuebric.com/disguise). For more information on the 2.5D workflow in Disguise, see [2.5D workflow](https://help.disguise.one/workflows/vp/2p5d-workflow.html).

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:

-   A data.json file containing data describing the asset and plates
-   Image or video files for the content to be mapped onto each plate
-   _(optional)_ Depth map image/video files for each plate
-   _(optional)_ OBJ mesh files for each plate

## Data JSON

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

-   _**meta**_: An object containing general metadata for the file
-   _**asset**_: An object containing information for the 2.5D asset as a whole
-   _**plates**_: An array of objects containing information for each 2.5D plate in the asset

### meta

The _**meta**_ object contains the following properties:

-   _**version**_: The version string for the .2p5d format being used. Currently this is “1.0.0”.
-   _**generator**_: The name of the application which generated the asset, e.g. “Disguise Designer”.

### asset

The _**asset**_ object contains the following properties:

-   _**max\_depth**_: _(optional)_ The maximum depth of the asset in metres. This is used to scale the normalised depth maps to absolute depth values.
-   _**min\_depth**_: _(optional)_ The minimum depth of the asset in metres. This is used to scale the normalised depth maps to absolute depth values.
-   _**field\_of\_view**_: _(optional)_ The field of view of the asset in degrees.

See [below](#plate-positioning-units) 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:

-   **name**: The name of the plate
-   _**filename**_: The filename of the image or video which is mapped onto the plate, including file extension.
-   _**depth\_map\_filename**_: _(optional)_ The filename of the image or video containing the depth map for the plate, including file extension.
-   _**mesh\_filename**_: _(optional)_ The filename of the OBJ mesh for the plate, including file extension.
-   _**width**_: The width of the resolution of the plate, in pixels.
-   _**height**_: The height of the resolution of the plate, in pixels.
-   _**x**_: _(optional)_ The horizontal offset of the plate centroid, see [below](#plate-positioning-units) for definition of units.
-   _**y**_: _(optional)_ The vertical offset of the plate centroid, see [below](#plate-positioning-units) for definition of units.
-   _**z**_: _(optional)_ The depth of the plate centroid, see [below](#plate-positioning-units) for definition of units.
-   _**scale\_x**_: _(optional)_ The horizontal scale of the plate, see [below](#plate-positioning-units) for definition of units.
-   _**scale\_y**_: _(optional)_ The vertical scale of the plate, see [below](#plate-positioning-units) for definition of units.
-   _**scale\_z**_: _(optional)_ The depth scale of the plate, see [below](#plate-positioning-units) for definition of units.
-   _**rotation\_x**_: _(optional)_ The x rotation of the plate in degrees, see [below](#plate-positioning-units) for definition of units.
-   _**rotation\_y**_: _(optional)_ The y rotation of the plate in degrees, see [below](#plate-positioning-units) for definition of units.
-   _**rotation\_z**_: _(optional)_ The z rotation of the plate in degrees, see [below](#plate-positioning-units) for definition of units.
-   _**mean\_depth**_: _(optional)_ The mean depth of the plate, defined in inverse normalised units similarly to the depth maps. This defines the depth of the centroid of the plate.

### Example

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

```json
{
    "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](https://help.disguise.one/designer/getting-started/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:

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

An example depth map is shown below.

![Example Depth Map](/assets/aurora_depth.png)

Format restrictions for these files are the same as for Disguise Designer in general. See [Supported file formats](https://help.disguise.one/designer/getting-started/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](/assets/2p5d_units.png)

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:

-   _**max\_depth**_ and _**min\_depth**_ are the maximum and minimum allowed depth (z) values of all plates in metres, measured from the eye point.
-   _**field\_of\_view**_ is the horizontal field of view encompassed by the frustrum, in degrees.

The plate parameters are defined as follows:

-   _**x**_ and _**y**_ are the horizontal and vertical offsets of the centroid of the plate, relative to the centre of the view. They are normalised relative to the width of the frustum, such that a value of _x = 0.5_ corresponds to the centroid being on the right edge of the view. Note that _**y**_ is also defined relative to the width, so a value of _y = 0.5_ doesn’t correspond to the top edge of the view, unless the image is square.
-   _**z**_ is a _non-inverse_ relative depth, normalised relative to _**max\_depth**_ and _**min\_depth**_, such that _z = 0_ corresponds to _**min\_depth**_ and _z = 1_ corresponds to _**max\_depth**_. Values outside of the range 0-1 are allowed. The equation to convert _**z**_ to the absolute plate depth in metres is:

```python
 depth = z * (max_depth - min_depth) + min_depth
```

-   _**mean\_depth**_ is an _inverse_ normalised depth, in the same units as the depth map itself (see above). The value should be between 0 and 1. Both _**z**_ and _**mean\_depth**_ determine the position of the centroid of the plate. One or the other can be used; if both are present then **mean\_depth** defines the local centroid position relative to the depth map, while _**z**_ defines the global centroid position, which can be offset from the local position. Setting values which are not equivalent may result in the plate not precisely filling the frustum. Since the values are defined in different units, they are equivalent if the following equation is true:

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

-   _**scale\_x**_ and _**scale\_y**_ are normalised relative to the frustum width and height, so that a flat plane with both values equal to 1 fills the frustum.
-   _**scale\_z**_ is not normalised, it is an absolute scaling relative to the original scale of the mesh or depth map.
-   _**rotation\_x**_, _**rotation\_y**_ and _**rotation\_z**_ are rotations in degrees around the X/Y/Z axes aligned to the frustum.