1. LUUCY Help Center
  2. Importing your own data

How do I place a model using metadata.json?

The metadata file can be used to define the placement and axis interpretation of a model.

LUUCY maps the entire globe. In order for the imported models to be placed in the correct location, one of the following conditions must be met:

  • The model is correctly georeferenced, all geometries have valid coordinates.
  • The model is placed in an own local reference system, but the displacement to the real position is known.

Project reference point or metadata.json?

LUUCY offers to set a project reference point in the project settings. With this information, all models uploaded into a variant are automatically moved by the defined amount. If your model only needs to be moved, it is recommended to define the project reference point of the project.

In addition to a shift, the metadata file also offers the possibility to scale models or to define the axis interpretation (if the model is on the page after the import).

Tip: If your model does not need to be scaled or moved, but only lies horizontally, you can also write the axis interpretation directly in the file name of the ZIP archive and not pack metadata.json into the archive.

To do this, append the desired axis interpretation in front of the file extension (separated by dots).


my-model.zip → my-model.xz-y.zip

Inhalt der metadata.json

The metadata file typically contains the following fields:

"srs": "EPSG:2056",
"offset": [2686180.231, 1257650.078, 0.0],
"scale": 1,
"axes": "xyz"

Only the srs field is mandatory, the remaining fields are optional.

The structure of the file is JavaScript Object Notation (JSON). All lines contain one key field and one value field. All key fields, as well as those value fields that contain text, must be enclosed in inverted commas. Individual lines must be separated by a comma. In the last line, no comma may be used. The entire code block is enclosed in curly brackets.

An example file can be viewed here: metadata.json


The Spacial Reference System specifies the coordinate system of the model and how the displacement values must be interpreted. The SRS is specified using the EPSG code.

Possible values:

EPSG code Explanation and use
EPSG:2056 Swiss national coordinate system, LV95.
EPSG:4326 World Geodetic System, world coordinate system, WGS84


The offset field offers the possibility to specify values for the offset in the X, Y and Z axes. If the SRS is specified in EPSG:2056, the unit metres. Decimal places (up to millimetres in the case of LV95) are allowed.

The field always contains three values within square brackets. If an axis is not to be moved, this value is to be entered as 0.0.

A positive shift in the X-axis pushes the model towards the east. A positive shift in the Y-axis moves the model towards the north. The Z-axis points vertically from the ground towards the sky.


"offset": [2686180.231, 1257650.078, 0.0]

In this example, the model is moved by 2'686'180.231 metres on the X-axis, and 1'257'650.078 metres on the Y-axis. The height is not changed because the value is 0.0.


With the scale field, the size of the model can be changed by means of the specified factor. A value of 1 does not change the model. A value greater than 1 enlarges the model and a value less than 1 reduces it.

For example, if the model was exported with millimetres as the unit, a scale value of 0.001 can be used.

The scaling is carried out before the offset.


The axes field can be used to define how the three coordinate fields are to be interpreted within a 3D file. Depending on the file format, the forward or vertical axis is different.

In LUUCY the axes are interpreted as follows:

X North direction
Y East direction
Z Direction sky, perpendicular to the ground

XYZ axes

If your model uses a different axis interpretation, this can be controlled with the axes field during import.

This defines the order of the axes as text.


xyz → the first coordinate in the model is interpreted in LUUCY as the X-axis, the second as the Y-axis and the third as the Z-axis.

xz-y → the first coordinate in the model is interpreted in LUUCY as the X-axis, the second as the Z-axis and the third as the Y-axis. The values of the Y-axis are multiplied by -1.

If the model lies on its side after the import, try the value xz-y in the axes field.

The axis interpretation is carried out before the offset.


The metadata.json file is packed into a ZIP archive together with the model and all files belonging to the model and uploaded to LUUCY. The file name of the metadata file must not be changed. Several different models are allowed per ZIP archive, but only one metadata file. The properties within the metadata file are always applied to all models contained in the ZIP archive.


Is there anything we could change to make this article more helpful?