Simulation Data

Manage simulation data used to test localization.

Simulation data lets you test the localization pipeline without being physically present at the mapped site. Each simulation data record is a zip file containing pre-recorded camera frames and metadata that can be replayed against the localization APIs.

A typical workflow is:

Record simulation data at the site.
Upload the resulting zip via POST /v1/simulation-data, the response gives you a unique simulationCode.
Reference the simulationCode when replaying the captured frames against your maps.
Update, download, or delete the simulation as your test set evolves.

Max upload size is 10 MB and the file must be a .zip. The uploaded part's Content-Type must be application/zip or application/x-zip-compressed, any other value (including the application/octet-stream default that some HTTP clients send) is rejected with Only zip files are allowed. The returned simulationCode is an 8-character alphanumeric identifier, use it in all subsequent calls.

Setting the part's Content-Type from curl: append ;type=application/zip to the -F value, for example -F 'file=@capture.zip;type=application/zip'. Browsers and SDKs normally set this header from the file's extension or detected type, so no extra work is needed there.

Zip File Format

The uploaded .zip represents a single capture session, a small set of AR camera frames plus the device pose and camera intrinsics at the moment each frame was captured. Replaying this archive against a map reproduces a real-world localization session offline.

What a capture contains

Each capture session contains exactly one dataset:

A fixed number of camera frames (4–6, default 5) stored as JPEGs.
The 6-DoF camera pose at the instant each frame was acquired, (x, y, z) position and (qx, qy, qz, qw) quaternion rotation, in a left-handed (LHS) world coordinate system (Unity convention). See Coordinate system below if your capture pipeline is right-handed.
The camera intrinsics for the session, focal length (fx, fy), principal point (px, py), and the image dimensions (width, height). Captured once and assumed constant for the rest of the session.

Coordinate system

All poses in the manifest must be expressed in a left-handed coordinate system (LHS), the same convention the MultiSet Unity SDK and the localization replay pipeline use. Uploading right-handed (RHS) poses without converting them first will produce poses that look mirrored along the X axis when replayed, and localization will not match the original capture.

If your capture pipeline produces RHS poses (for example, native iOS / Android, ARKit / ARCore raw transforms, or any OpenGL-style stack), convert each pose to LHS before writing it into the manifest. The full conversion is: negate position.x, negate rotation.qy and rotation.qz, keep the rest unchanged.

/**
 * Convert a 6-DoF pose from a right-handed coordinate system (RHS) to the
 * left-handed coordinate system (LHS) expected by the simulation data
 * manifest. Apply this to every per-frame pose before writing the JSON.
 */
function flipPoseHandedness(pose) {
    return {
        position: {
            x: -pose.position.x,
            y:  pose.position.y,
            z:  pose.position.z,
        },
        rotation: {
            qx:  pose.rotation.qx,
            qy: -pose.rotation.qy,
            qz: -pose.rotation.qz,
            qw:  pose.rotation.qw,
        },
    };
}

Captures produced by the MultiSet Unity SDK are already LHS, no conversion is needed.

Zip layout

Entries inside the zip are flat, there is no top-level folder:

SimulationData.zip
├── Image_0_<yyyyMMdd_HHmmss>.jpg
├── Image_1_<yyyyMMdd_HHmmss>.jpg
├── Image_2_<yyyyMMdd_HHmmss>.jpg
├── Image_3_<yyyyMMdd_HHmmss>.jpg
├── Image_4_<yyyyMMdd_HHmmss>.jpg
└── SimulationData_<yyyyMMdd_HHmmss>.json

Image filenames follow Image_<index>_<timestamp>.jpg, where <index> is the zero-based capture order. Images must appear in the same order as the entries in the JSON manifest's imageDataList so they can be paired positionally.
The timestamp suffix <yyyyMMdd_HHmmss> is identical for every file in the session.
JPEGs should be encoded at quality ~80.

`SimulationData_<timestamp>.json` manifest

The single JSON manifest at the root of the zip describes the intrinsics and the per-frame pose, in capture order:

Field

Type

Notes

width, height

int

Working image resolution in pixels (must match the JPEGs).

fx, fy

float

Camera focal length in pixels, scaled to match width/height.

px, py

float

Camera principal point in pixels, scaled to match width/height.

imageDataList

array

One entry per image. Same order as Image_0, Image_1, …

imageDataList[].x, .y, .z

float

Camera position at frame acquisition.

imageDataList[].qx, .qy, .qz, .qw

float

Camera rotation as a quaternion.

Example:

{
    "width": 720,
    "height": 960,
    "px": 361.3074645996094,
    "py": 481.46038818359377,
    "fx": 665.6408081054688,
    "fy": 665.6408081054688,
    "imageDataList": [
        {
            "x": 0.31831833720207217,
            "y": 1.156510353088379,
            "z": 1.3285411596298218,
            "qx": -0.009507684037089348,
            "qy": 0.30342480540275576,
            "qz": -0.00325992563739419,
            "qw": -0.9528024196624756
        },
        {
            "x": 0.3255421817302704,
            "y": 1.154714822769165,
            "z": 1.3292453289031983,
            "qx": -0.0043470230884850029,
            "qy": 0.27293628454208376,
            "qz": -0.006081813480705023,
            "qw": -0.9620030522346497
        },
        {
            "x": 0.3384963274002075,
            "y": 1.156157374382019,
            "z": 1.3352329730987549,
            "qx": -0.0042652105912566189,
            "qy": 0.18202008306980134,
            "qz": -0.007582413498312235,
            "qw": -0.9832563400268555
        },
        {
            "x": 0.37630680203437807,
            "y": 1.1523985862731934,
            "z": 1.3415110111236573,
            "qx": -0.0032018644269555809,
            "qy": 0.0914652869105339,
            "qz": -0.0009664428071118891,
            "qw": -0.995802640914917
        },
        {
            "x": 0.42654383182525637,
            "y": 1.1490235328674317,
            "z": 1.3500515222549439,
            "qx": -0.0047492762096226219,
            "qy": 0.0032952935434877874,
            "qz": -0.0013450992992147804,
            "qw": -0.9999824166297913
        }
    ]
}

imageDataList.length must equal the number of Image_<n>_*.jpg files in the zip, and each index n must have a corresponding entry at position n in the list. Mismatched counts or out-of-order indices cause the simulation to be rejected at replay time.

Upload Simulation Data

Upload a new simulation data zip. Returns a simulationCode you use to reference it later.

Upload simulation data

post

Upload a zip file containing simulation data for testing localization APIs. On success the response returns a unique simulationCode that you use to reference the simulation in all subsequent calls.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestring · max: 255Required

Name for the simulation data

Example: Test Simulation 1

descriptionstring · max: 1000Optional

Optional description for the simulation data

Example: Simulation data for AR localization testing

filestring · binaryRequired

Zip file containing simulation data (max 10 MB). The part's Content-Type header must be application/zip or application/x-zip-compressed. From curl, append ;type=application/zip to the -F file=@... value to set it.

Responses

201

Simulation data uploaded successfully

application/json

messagestringOptionalExample: Simulation data uploaded successfully

simulationCodestringOptional

8-character code that identifies this simulation in subsequent calls.

Example: A1B2C3D4

400

Bad request — invalid file type, size limit exceeded, account inactive, or missing required fields

401

Unauthorized — missing or invalid token

500

Internal server error

post/simulation-data

POST /v1/simulation-data HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 104

{
  "name": "Test Simulation 1",
  "description": "Simulation data for AR localization testing",
  "file": "binary"
}

{
  "message": "Simulation data uploaded successfully",
  "simulationCode": "A1B2C3D4"
}

List Simulation Data

Paginated list of simulation data for the authenticated account. Supports search by name and filtering by status.

List simulation data

get

Get a paginated list of simulation data for the authenticated account with optional filtering.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageinteger · min: 1Optional

Page number for pagination

Default: 1

limitinteger · min: 1 · max: 100Optional

Number of items per page

Default: 10

querystring · max: 255Optional

Case-insensitive partial match against the simulation name

statusstring · enumOptional

Filter by simulation data status

Possible values:

Responses

200

List of simulation data retrieved successfully

application/json

401

Unauthorized — missing or invalid token

500

Internal server error

get/simulation-data

GET /v1/simulation-data HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "simulationData": [
    {
      "simulationCode": "A1B2C3D4",
      "name": "Test Simulation 1",
      "description": "Simulation data for AR localization testing",
      "fileSize": 1024000,
      "originalFilename": "test_simulation.zip",
      "status": "active",
      "createdAt": "2026-02-06T10:30:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 45,
    "itemsPerPage": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Get Simulation Data by Code

Retrieve details (name, description, status, file size, timestamps) for a single simulation data record.

Get simulation data by code

get

Retrieve details (name, description, status, file size, timestamps) for a single simulation data record.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

simulationCodestringRequired

The 8-character code that identifies the simulation data

Example: A1B2C3D4

Responses

200

Simulation data details retrieved successfully

application/json

simulationCodestringOptionalExample: A1B2C3D4

namestringOptionalExample: Test Simulation 1

descriptionstringOptionalExample: Simulation data for AR localization testing

fileSizenumberOptionalExample: 1024000

originalFilenamestringOptionalExample: test_simulation.zip

statusstring · enumOptionalExample: activePossible values:

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Invalid simulation code format

401

Unauthorized — missing or invalid token

403

Forbidden — user doesn't have access to this simulation data

404

Simulation data not found

get/simulation-data/{simulationCode}

GET /v1/simulation-data/{simulationCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "simulationCode": "A1B2C3D4",
  "name": "Test Simulation 1",
  "description": "Simulation data for AR localization testing",
  "fileSize": 1024000,
  "originalFilename": "test_simulation.zip",
  "status": "active",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Update Simulation Data

Update the name and/or description of an existing simulation data record. At least one of the two fields must be supplied.

This endpoint updates metadata only. To replace the underlying zip file, delete the simulation and upload a new one.

Update simulation data

put

Update the name and/or description of an existing simulation data record. At least one of name or description must be provided in the request body.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

simulationCodestringRequired

The 8-character code that identifies the simulation data to update

Example: A1B2C3D4

Body

anyOptional

Responses

200

Simulation data updated successfully

application/json

messagestringOptionalExample: Simulation data updated successfully

simulationCodestringOptionalExample: A1B2C3D4

400

Invalid simulation code format or validation errors

401

Unauthorized — missing or invalid token

403

Forbidden — user doesn't have access to this simulation data

404

Simulation data not found

put/simulation-data/{simulationCode}

PUT /v1/simulation-data/{simulationCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "name": "Updated Test Simulation",
  "description": "Updated description for test simulation data"
}

{
  "message": "Simulation data updated successfully",
  "simulationCode": "A1B2C3D4"
}

Delete Simulation Data

Removes the simulation data record and deletes the underlying zip file from storage. This action is irreversible.

Delete simulation data

delete

Delete a simulation data record and remove the underlying file from storage.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

simulationCodestringRequired

The 8-character code that identifies the simulation data to delete

Example: A1B2C3D4

Responses

200

Simulation data deleted successfully

application/json

messagestringOptionalExample: Simulation data deleted successfully

simulationCodestringOptionalExample: A1B2C3D4

400

Invalid simulation code format

401

Unauthorized — missing or invalid token

403

Forbidden — user doesn't have access to this simulation data

404

Simulation data not found

delete/simulation-data/{simulationCode}

DELETE /v1/simulation-data/{simulationCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Simulation data deleted successfully",
  "simulationCode": "A1B2C3D4"
}

Download Simulation Data

Generates a short-lived pre-signed URL for downloading the zip. The response includes the URL, the original filename, and the file size.

Download simulation data

get

Generate a secure pre-signed download URL for the simulation data zip file.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

simulationCodestringRequired

The 8-character code that identifies the simulation data to download

Example: A1B2C3D4

Responses

200

Download URL generated successfully

application/json

messagestringOptionalExample: Download URL generated successfully

downloadUrlstring · uriOptionalExample: https://s3.amazonaws.com/bucket/path/to/file.zip?X-Amz-Algorithm=...

filenamestringOptionalExample: test_simulation.zip

fileSizenumberOptionalExample: 1024000

400

Invalid simulation code format or file not available

401

Unauthorized — missing or invalid token

403

Forbidden — user doesn't have access to this simulation data

404

Simulation data not found

get/simulation-data/{simulationCode}/download

GET /v1/simulation-data/{simulationCode}/download HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Download URL generated successfully",
  "downloadUrl": "https://s3.amazonaws.com/bucket/path/to/file.zip?X-Amz-Algorithm=...",
  "filename": "test_simulation.zip",
  "fileSize": 1024000
}

PreviousMap Version

NextThird Party Scans

Last updated 2 months ago

Was this helpful?

Zip File Format

What a capture contains

Coordinate system

Zip layout

SimulationData_<timestamp>.json manifest

Upload Simulation Data

Upload simulation data

List Simulation Data

List simulation data

Get Simulation Data by Code

Get simulation data by code

Update Simulation Data

Update simulation data

Delete Simulation Data

Delete simulation data

Download Simulation Data

Download simulation data

`SimulationData_<timestamp>.json` manifest