Skip to content

THREE ‐ API v4.0.0

Jump to bottom
Rhys Balevicius edited this page Jul 22, 2024 · 1 revision

Introduction

Welcome to the official documentation of the Matter and Form THREE scanner's public API. This documentation provides detailed information about the API calls available for controlling and interacting with the THREE scanner.

The THREE comes equipped with a backend server that activates on boot. This server communicates via a WebSocket protocol, allowing for full control over the scanner's functionalities—everything the THREE does, except for the GUI, is accessible through this server. All the calls our frontend system makes are also available for your personal projects.

Using the WebSocket server, you can build your own integrations with automation systems. Whether you want to take stereo images with the dual cameras, project graphics through the built-in projector, or even design a completely new front-end 3D scanning system, our API provides the flexibility for all these activities and more.

Overview

Getting Started

Connecting to the THREE

If you are new to WebSockets and would like to learn more, you can read about them here. Alternatively, you can search for WebSocket libraries that are compatible with the programming language of your choice.

Connect to the WebSocket server over port 8081: ws://matterandform.local:8081, or use the local IP address of the device: ws://192.168.XXX.XXX:8081. The projector displays the local IP address of the THREE scanner on boot.

Please note that the THREE scanner is a local network device and can only be communicated with from within the same network by default.

Refer to the Basic Usage section for a more complete code snippet in Python and JavaScript to help you get up and running.

const WebSocket = require('ws');

const ws = new WebSocket('ws://matterandform.local:8081');
import asyncio
import websockets

async def connect():
    await websockets.connect("ws://matterandform.local:8081")

asyncio.run(connect())

Interacting with the THREE

The server and the client exchange messages mainly in JSON format. The two exceptions are 3D scan data, and image data. The server will normally only respond to requests that are sent by an application.

Every action, whether it’s starting a new scan, adjusting settings, or querying the device status, is encapsulated as a task. When a task is submitted to the server, it is queued and processed in sequence.

Refer to the Basic Usage section for code snippets in both Python and JavaScript to help you get up and running.

Task Messages

Generic task message for the Three Scanner.

A task message is a generic message encoded as JSON which is used for enqueuing a task to be performed by the THREE Scanner. The THREE scanner dispatches updates and results for tasks to the client using the same message type.

Field Type Label Description
Index int32 A unique identifier generated by the client. This identifier associates all incoming and outgoing task messages with a specific task requested by the client.
Type string The string identifying the task type. See task definitions for the list of valid task strings.
Input Any optional Optional input message. See each task definition for details.
Output Any optional Optional output message. See each task definition for details.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

The following is an example of a raw JSON request from the client and response from the server which modifies the current camera settings using the SetCameras task.

Example request:

{
    "Task": {
        "Index": 1,
        "Type": "SetCameras"
        "Input": {
            "analogGain": 256,
            "digitalGain": 128,
            "exposure": 18000
        }
    }
}

Example response:

{
    "Task": {
        "Index": 1,
        "Type": "SetCameras"
        "Input": {
            "analogGain": 256,
            "digitalGain": 512,
            "exposure": 18000
        },
        "Output": {
            "analogGain": {
                "default": 512.0,
                "max": 1024.0, 
                "min": 256.0, 
                "value": 256.0
            },
            "digitalGain": {
                "default": 256,
                "max": 65536,
                "min": 256,
                "value": 512
            },
            "exposure": {
                "default": 27000,
                "max": 90000,
                "min": 9000,
                "value": 18000
            }
        },
        "State": "Completed"
    }
}

Task State

Name Description
None The task state is not defined.
Sent The task has been sent by the client.
Received The task has been received by the server.
Started The task started by the server.
Completed The task is completed by the server.
Cancelled The task has been cancelled by the client.
Failed The task has failed. A string describing the error is returned with the task.
Dropped The task has not been received by the server, or task IDs were sent out of sequence.
Disconnected The client has been disconnected from the server before the task could finish.

Buffer Messages

Generic buffer message for the Three Scanner.

Some tasks require the server and/or client to transfer binary data. In such cases the buffer message is sent to inform the server/client what the data is and what task it belongs to. The binary data it refers to is sent immediately following the buffer message.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The task associated with the data buffer. This informs the client which request this data buffer corresponds to.
Descriptor Any optional Optional data buffer descriptor. See each task definition for details.

Example request: the DownloadProject task requests for the server to transfer a ZIP file containing the project data to the client.

{
    "Task": {
        "Index": 1,
        "Type": "DownloadProject",
        "Input": 5
    }
}

The server responds with a buffer message informing the client to expect a binary data transfer. Notice that the buffer message Task field echoes the initial task request so that it is clear which request this data is a response to. A Size field is also included so that the client knows how many bytes it should expect to receive.

{
    "Buffer": {
        "Descriptor": "Project-5.zip",
        "Index": 0,
        "Size": 15682096,
        "Task": {
            "Index": 1,
            "Type": "DownloadProject",
            "Input": 5
        }
    }
}

The server then sends the 15682096 byte data buffer of the project ZIP file (in 32MB chunks at most). Once the server is finished streaming the binary buffer it sends a task completion message.

{
    "Task": {
        "Index": 1,
        "Type": "DownloadProject"
        "Input": 5,
        "State": "Completed"
    }
}

Basic Usage

This section contains step-by-step instructions for connecting to, and interacting with, the THREE WebSocket API. In particular, the example here demonstrates how to establish a connection, send tasks, and handle responses from the server, using Python and JavaScript.

Setup: Using Python

To run the Python code snippet, Python 3.8 or newer is required. You will also need to install the websockets library.

  • Ensure Python 3.8 or newer is installed. You can download it from python.org.
  • To install websockets, run pip install websockets in your command line.
  • Copy and paste the code snippets into a file named example.py.
  • Run the script with python /path/to/example.py or python3 /path/to/example.py, depending on your system configuration.

Setup: Using JavaScript

To run the JavaScript code snippet, Node.js 10.0.0 or newer is required. You will also need to install the ws library.

  • Ensure Node.js 10.0.0 or newer is installed. You can download it from nodejs.org.
  • To install ws, run npm install ws in your project directory.
  • Copy and paste the code snippets into a file named example.js.
  • Run the script with node /path/to/example.js or nodejs /path/to/example.js, depending on your system configuration.

Interacting with a Project

Connect to the server

In order to interact with the WebSocket API, we first need to connect to it. We can use the following Python or JavaScript code snippet to do that.

Using Python:

import asyncio
import json
import websockets

class THREE:
    def __init__(self, url):
        self.url = url

    async def connect(self):
        self.ws = await websockets.connect(self.url)

    async def send(self, task):
        await self.ws.send(json.dumps(task))

        async for message in self.ws:
            try:
                response = json.loads(message)
                if 'Task' in response and 'State' in response['Task'] and response['Task']['Index'] == task['Task']['Index']:
                    if response['Task']['State'] == 'Failed':
                        raise Exception(response['Task'])
                    elif response['Task']['State'] == 'Completed':
                        return response['Task'].get('Output', {})
            except Exception as e:
                raise e

async def main():
    three = THREE('ws://matterandform.local:8081')
    try:
        # Open a connection with the server
        await three.connect()
        print(f"Connected to the server @ {three.url}")

        # Your application logic here

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await three.ws.close()

asyncio.run(main())

Using JavaScript:

const WebSocket = require('ws');

function THREE(url) { this.url = url; }

THREE.prototype.connect = function() {
    this.ws = new WebSocket(this.url);
    return new Promise((resolve, reject) => {
        this.ws.onopen = resolve;
        this.ws.onclose = reject;
    });
};

THREE.prototype.send = function(task) {
    return new Promise((resolve, reject) => {
        this.ws.onmessage = event => {
            try {
                const response = JSON.parse(event.data);
                if (!response.Task || response.Task.Index !== task.Task.Index) return;
                if (response.Task.State === 'Failed') reject(response.Task);
                if (response.Task.State === 'Completed') resolve(response.Task.Output ?? {});
            } catch (error) { reject(error); }
        };
        this.ws.onerror = error => reject(error);
        this.ws.send(JSON.stringify(task));
    });
};

const main = async () => {
    const three = new THREE('ws://matterandform.local:8081');

    try {
        // Open a connection with the server
        await three.connect();
        console.log(`Connected to the server @ ${three.url}`);

        // Your application logic here
    }
    catch (error) { console.error('Error:', error); }
    finally { three.ws?.close(); }
}

main();

Caution

Note: these code snippets are intended to help you get up and running, and for quick prototyping only. In a production environment you will want to enhance this code (or simply re-write it) to be more robust and fault tolerant.

Creating a New Project

Scans are stored in project, and so before we may create a new scan we must first open a project. We can create a new project by sending a NewProject task with the Input field set to the name we want to give the project.

Once successful, the NewProject task will return a message with the State field set to Completed, and an Output field containing metadata about the newly created project including an index field which is used to identify it. We use the index field in the next step.

Using Python:

create_project_response = await three.send({
    "Task": {
        "Index": 1,
        "Type": "NewProject",
        "Input": "My Project Name"
    }
})
print('Project created:', create_project_response)

Using JavaScript:

const createProjectResponse = await three.send({
    Task: {
        Index: 1,
        Type: "NewProject",
        Input: "My Project Name"
    }
});
console.log('Project created:', createProjectResponse);

Example response:

{
  "groups": { "collapsed": false, "index": 0, "name": "", "visible": true },
  "index": 19,
  "name": "My Project Name"
}

Opening a Project

After creating a new project, we can open it. Opening a project allows the current socket connection to interact with it, such as adding and editing scan data. To open a project we send a OpenProject task with the Input field set to be the index obtained in the previous step.

Using Python:

# Open the project created in the previous step
open_project_response = await three.send({
    "Task": {
        "Index": 2,
        "Type": "OpenProject",
        "Input": create_project_response['index']
    }
})
print('Project opened:', open_project_response)

Using JavaScript:

// Open the project created in the previous step
const openProjectResponse = await three.send({
    Task: {
        Index: 2,
        Type: "OpenProject",
        Input: createProjectResponse.index
    }
});
console.log('Project opened:', openProjectResponse);

Example response:

{
  "groups": { "collapsed": false, "index": 0, "name": "", "visible": true },
  "index": 19,
  "name": "My Project Name"
}

Note

Note that the project will remain open for the lifetime of the socket connection or until you explicitly close it by sending a CloseProject task. Projects can only be open by a single socket connection at a given time.

Creating a Scan

Once we've opened a project we are ready to interact with it. For example, we can create a new scan by sending a NewScan task with the Input field set to be some scan configuration.

Using Python:

# Add a new scan to the opened project
new_scan_response = await three.send({
    "Task": {
        "Index": 3,
        "Type": "NewScan",
        "Input": {
            "camera": { "exposure": 18000, "analogGain": 256, "digitalGain": 256 },
            "capture": { "quality": "Medium", "texture": True },
            "projector": { "brightness": 0.8 }
        }
    }
})
print('New scan added:', new_scan_response)

Using JavaScript:

// Add a new scan to the opened project
const newScanResponse = await three.send({
    Task: {
        Index: 3,
        Type: "NewScan",
        Input: {
            camera: { exposure: 18000, analogGain: 256, digitalGain: 256 },
            capture: { quality: "Medium", texture: true },
            projector: { brightness: 0.8 }
        }
    }
});
console.log('New scan added:', newScanResponse);

Example response:

{
  "index": 0,
  "name": "",
  "collapsed": false,
  "groups": [
    {
      "index": 1,
      "name":"Scan-1",
      "collapsed": false,
      "color": [0.6150012612342834,0.8566378951072693,0.916047215461731,1],
      "rotation": [-0.003504337305992789,0.16057781988162367,-0.006117077953868702],
      "scan": 1,
      "translation": [-127.42007942138065,18.583630764869238,-293.1252968900822],
      "visible": true
    }
  ],
  "visible": true
}

Protocol Documentation

Table of Contents

Top

MF/V3/Buffer

Buffer

Generic buffer message for the Three Scanner.

Some tasks require the server and/or client to transfer binary data. In such cases the buffer message is sent to inform the server/client what the data is and what task it belongs to. The binary data it refers to is sent immediately following the buffer message.

For example, DownloadProject requires the server to transfer a ZIP file containing the project data to the client.

> First, the client sends the task request to the server:

{
    "Task":{
        "Index":1,
        "Type":"DownloadProject",
        "Input":5
    }
}

> The server sends the buffer message telling the client to expect a binary data transfer and what to do with it. Note that the buffer message Task field echoes the task request, making it clear which request this data is a response to.

{
    "Buffer":{
        "Descriptor":"Project-5.zip",
        "Index":0,
        "Size":15682096,
        "Task":{
            "Index":1,
            "Type":"DownloadProject",
            "Input":5
        }
    }
}

> The server then sends the 15682096 byte data buffer of the project ZIP file. > Finally, the server sends a task completion message.

{
    "Task":{
        "Index":1,
        "Type":"DownloadProject"
        "Input":5,
        "State":"Completed"
    }
}
Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The task associated with the data buffer. This informs the client which request this data buffer corresponds to.
Descriptor googlebuf.Any optional Optional data buffer descriptor. See each task definition for details.

Top

MF/V3/Descriptors/BoundingBox

BoundingBox

BoundingBox descriptor.

Field Type Label Description
center double repeated The center of the bounding box.
size double repeated The size of the bounding box.
rotation double repeated The 3x3 rotation matrix of the bounding box. The first, second and third column vectors are the x, y and z axes of the bounding box.
transform double repeated The 4x4 matrix that transforms the canonical cube with corners [±1, ±1, ±1] to the bounding box in world coordinates. The transform can be used as the model matrix for rendering the bounding box with an OpenGL shader.

Top

MF/V3/Descriptors/Calibration

Camera

Camera calibration descriptor.

Field Type Label Description
quality Quality Calibration quality.
date int32 repeated Calibration date and time [year, month, day, hour, minute, second].

CaptureTarget

Calibration capture target.

The camera calibration capture targets are used to draw quad overlays on the video stream to guide a user as to where to position the calibration card for each capture during camera calibration.

Field Type Label Description
camera int32 Index of the camera that is displayed to the user for this capture.
quads float repeated The target quad for each camera. This is a set of 16 numbers defining the quad coordinates on the left and right camera. The first 4 pairs of numbers define the quad on the left camera. The last 4 pairs of numbers define the quad on the right camera.

DetectedCard

Detected calibration card descriptor.

Field Type Label Description
size int32 repeated The calibration card columns and rows.
quad float repeated The calibration card bounding quadrilateral.
corners float repeated The detected corners of the calibration card.
target DetectedCard.Target optional The capture target properties, if a capture target is specified.

DetectedCard.Target

Calibration capture target properties.

Field Type Label Description
match float A normalized value indicating how closely the calibration card matches the target overlay. 0 indicates a poor match. 1 indicates a good match.
hold float A normalized value indicating how long the user has held the calibration card steady over the target overlay. When the value reaches 1, the user has held the calibration card steady for the complete required duration.

Turntable

Turntable calibration descriptor.

Field Type Label Description
quality Quality Calibration quality.
date int32 repeated Calibration date and time [year, month, day, hour, minute, second].
focus int32 repeated Focus values of each camera during calibration.

Quality

Calibration quality.

Name Number Description
None 0 The calibration does not exist.
Poor 1 Poor calibration quality.
Fair 2 Fair calibration quality.
Good 3 Good calibration quality.
Excellent 4 Excellent calibration quality.

Top

MF/V3/Descriptors/Export

Export

Scan data descriptor.

Field Type Label Description
format MF.V3.Settings.Export.Format Export format.
extension string Export file extension. e.g. ".ply"
description string Export format description. e.g. "Polygon format"
faces Export.Face repeated Types of supported faces.
normals bool Vertex normal support.
colors bool Vertex color support.
textures Export.Texture Texture (UV) support.

Export.Face

Geometry face types.

Name Number Description
NoFace 0 No faces.
Point 1 Point faces.
Line 2 Line faces.
Triangle 3 Triangle faces.
Quad 4 Quad faces.

Export.Texture

Texture support types.

Name Number Description
None 0 The format does not support textures.
Single 1 The format supports a single texture only.
Multiple 2 The format supports multiple textures.

Top

MF/V3/Descriptors/Image

Image

Image descriptor.

Field Type Label Description
width int32 Image width.
height int32 Image height.
step int32 Image row step in bytes.
type int32 OpenCV image type.

Top

MF/V3/Descriptors/Merge

Merge

Merge descriptor.

Field Type Label Description
scans uint32 The number of input scans.
textures uint32 The number of input textures.
maxSimplifyCount uint32 The maximum number of faces for the simplify merge step.
meshes Merge.Mesh repeated The set of merged mesh descriptors.

Merge.Mesh

Mesh descriptor.

Field Type Label Description
name string The mesh name.
triangles uint32 Number of mesh triangle faces.
quads uint32 Number of quad faces.
positions uint32 Number of vertex positions.
normals uint32 Number of vertex normals.
uvs uint32 Number of UV coordinates.
size uint32 Total mesh size in bytes.

Top

MF/V3/Descriptors/Network

Interface

Network interface descriptor.

Field Type Label Description
name string The name of the interface.
ip string The address associated with the interface.
ssid string The ssid or name of the network.

Top

MF/V3/Descriptors/Project

Project

V3 project descriptor.

Field Type Label Description
index int32 Project index.
name string Project name.
groups Project.Group

Project.Brief

V3 project brief descriptor.

Field Type Label Description
index int32 Project index.
name string Project name.
size uint64 Size in bytes.
modified int32 repeated Project last modified date and time [year, month, day, hour, minute, second].

Project.Group

V3 project scan group tree descriptor.

Field Type Label Description
index int32 Group index.
name string Group name.
color float repeated Color in the renderer.
visible bool Visibility in the renderer.
collapsed bool Collapsed state in the group tree.
rotation double repeated Axis-angle rotation vector. The direction of the vector is the rotation axis. The magnitude of the vector is rotation angle in radians.
translation double repeated Translation vector.
scan int32 optional The scan index. If defined this group is a scan and cannot have subgroups.
groups Project.Group repeated Subgroups.

Top

MF/V3/Descriptors/ProjectActions

ProjectAction

Descriptor for a project undo/redo action.

Field Type Label Description
task string The original websocket task that the action is undoing or redoing.
project Project optional The updated project data after undo or redo. If undefined, then there was no change to the project.
scans ProjectAction.Scan repeated The list of scans whose vertex/triangle elements were changed by the undo/redo action.

ProjectAction.Scan

Scan vertices removal/insertion metadata.

Field Type Label Description
index int32 The scan index.
vertices int32 The number of vertices after undo or redo.
triangles int32 The number of triangles after undo or redo.

ProjectActions

Project undo and redo action descriptors.

Field Type Label Description
undo string repeated Project undo action descriptors.
redo string repeated Project redo action descriptors.

Top

MF/V3/Descriptors/ScanData

ScanData

Scan data descriptor.

Field Type Label Description
index int32 Scan index.
name string Scan name.
buffers ScanData.Buffer repeated Scan buffer descriptors.
mean float repeated The mean (centroid) of the vertex positions.
stddev float repeated The standard deviation of the vertex positions.
axisAlignedBoundingBox float repeated The axis-aligned bounding box of the vertex positions.

ScanData.Buffer

Scan buffer descriptor.

Field Type Label Description
components ScanData.Buffer.Component repeated Scan buffer components.
stride int32 Scan buffer stride. This should be greater or equal to the sum of the component sizes.

ScanData.Buffer.Component

Scan buffer component descriptor.

Field Type Label Description
type ScanData.Buffer.Component.Type Scan buffer component type.
size int32 Scan buffer component size (ie. the number of elements).
offset int32 Scan buffer component offset. This is the starting element for this component at every stride of the buffer.
normalized bool Indicates if the data is normalized.

ScanData.Buffer.Component.Type

Scan buffer component types.

Name Number Description
Position 0 Vertex position.
Normal 1 Vertex normal.
Color 2 Vertex color.
UV 3 Vertex texture coordinate.
Triangle 4 Triangle index.
Texture 5 Texture.

Top

MF/V3/Descriptors/Settings/Advanced

Advanced

Advanced settings descriptor.

Field Type Label Description
capture Advanced.Capture Capture settings descriptor.
sampling Advanced.Sampling Sampling settings descriptor.
edgeDetection Advanced.EdgeDetection Edge detection settings descriptor.
phaseFilter Advanced.PhaseFilter Phase filter settings descriptor.
adaptiveSampling Advanced.AdaptiveSampling Adaptive sampling settings descriptor.
normalEstimation Advanced.NormalEstimation Normal estimation settings descriptor.
outlierRemoval Advanced.OutlierRemoval Outlier removal settings descriptor.
remesh Advanced.Remesh Remesh settings descriptor.

Advanced.AdaptiveSampling

Adaptive sampling settings descriptor.

Field Type Label Description
use Advanced.Use
type Advanced.AdaptiveSampling.Type
rate Advanced.AdaptiveSampling.Rate

Advanced.AdaptiveSampling.Rate

Field Type Label Description
value float
default float
min float
max float

Advanced.AdaptiveSampling.Type

Field Type Label Description
value MF.V3.Settings.Scan.Processing.AdaptiveSampling.Type
default MF.V3.Settings.Scan.Processing.AdaptiveSampling.Type

Advanced.Capture

Capture settings descriptor.

Field Type Label Description
use Advanced.Use
horizontalFrequencies Advanced.Capture.HorizontalFrequencies
verticalFrequencies Advanced.Capture.VerticalFrequencies

Advanced.Capture.HorizontalFrequencies

Field Type Label Description
value int32 repeated
default int32 repeated
min int32
max int32

Advanced.Capture.VerticalFrequencies

Field Type Label Description
value int32 repeated
default int32 repeated
min int32
max int32

Advanced.EdgeDetection

Edge detection settings descriptor.

Field Type Label Description
use Advanced.Use
threshold Advanced.EdgeDetection.Threshold
laplacianKernelRadius Advanced.EdgeDetection.LaplacianKernelRadius
gaussianBlurRadius Advanced.EdgeDetection.GaussianBlurRadius
gaussianBlurStdDev Advanced.EdgeDetection.GaussianBlurStdDev
maximumWidthForProcessing Advanced.EdgeDetection.MaximumWidthForProcessing

Advanced.EdgeDetection.GaussianBlurRadius

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.EdgeDetection.GaussianBlurStdDev

Field Type Label Description
value float
default float
min float
max float

Advanced.EdgeDetection.LaplacianKernelRadius

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.EdgeDetection.MaximumWidthForProcessing

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.EdgeDetection.Threshold

Field Type Label Description
value float
default float
min float
max float

Advanced.NormalEstimation

Normal estimation settings descriptor.

Field Type Label Description
use Advanced.Use
method Advanced.NormalEstimation.Method
maximumNeighbourCount Advanced.NormalEstimation.MaximumNeighbourCount
maximumNeighbourRadius Advanced.NormalEstimation.MaximumNeighbourRadius
useMaximumNeighbourCount Advanced.NormalEstimation.UseMaximumNeighbourCount
useMaximumNeighbourRadius Advanced.NormalEstimation.UseMaximumNeighbourRadius

Advanced.NormalEstimation.MaximumNeighbourCount

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.NormalEstimation.MaximumNeighbourRadius

Field Type Label Description
value float
default float
min float
max float

Advanced.NormalEstimation.Method

Field Type Label Description
value MF.V3.Settings.Scan.Processing.NormalEstimation.Method
default MF.V3.Settings.Scan.Processing.NormalEstimation.Method

Advanced.NormalEstimation.UseMaximumNeighbourCount

Field Type Label Description
value bool
default bool

Advanced.NormalEstimation.UseMaximumNeighbourRadius

Field Type Label Description
value bool
default bool

Advanced.OutlierRemoval

Outlier removal settings descriptor.

Field Type Label Description
use Advanced.Use
neighbourCount Advanced.OutlierRemoval.NeighbourCount
neighbourRadius Advanced.OutlierRemoval.NeighbourRadius

Advanced.OutlierRemoval.NeighbourCount

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.OutlierRemoval.NeighbourRadius

Field Type Label Description
value float
default float
min float
max float

Advanced.PhaseFilter

Phase filter settings descriptor.

Field Type Label Description
use Advanced.Use
kernelRadius Advanced.PhaseFilter.KernelRadius
spatialWeightStdDev Advanced.PhaseFilter.SpatialWeightStdDev

Advanced.PhaseFilter.KernelRadius

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.PhaseFilter.SpatialWeightStdDev

Field Type Label Description
value float
default float
min float
max float

Advanced.Remesh

Remesh settings descriptor.

Field Type Label Description
use Advanced.Use
voxelSize Advanced.Remesh.VoxelSize
depth Advanced.Remesh.Depth
scale Advanced.Remesh.Scale
linearInterpolation Advanced.Remesh.LinearInterpolation

Advanced.Remesh.Depth

Field Type Label Description
value int32
default int32
min int32
max int32

Advanced.Remesh.LinearInterpolation

Field Type Label Description
value bool
default bool

Advanced.Remesh.Scale

Field Type Label Description
value float
default float
min float
max float

Advanced.Remesh.VoxelSize

Field Type Label Description
value float
default float
min float
max float

Advanced.Sampling

Sampling settings descriptor.

Field Type Label Description
use Advanced.Use Use sampling settings.
projectorSampleRate Advanced.Sampling.ProjectorSampleRate
imageSampleRate Advanced.Sampling.ImageSampleRate

Advanced.Sampling.ImageSampleRate

Field Type Label Description
value float
default float
min float
max float

Advanced.Sampling.ProjectorSampleRate

Field Type Label Description
value float
default float
min float
max float

Advanced.Use

Use advanced settings.

Field Type Label Description
value bool
default bool

Top

MF/V3/Descriptors/Settings/Camera

Camera

Camera settings descriptor.

Field Type Label Description
autoExposure Camera.AutoExposure Auto exposure.
exposure Camera.Exposure Exposure.
analogGain Camera.AnalogGain Analog gain.
digitalGain Camera.DigitalGain Digital gain.
focus Camera.Focus Focus settings descriptor.

Camera.AnalogGain

Analog gain.

Field Type Label Description
value float
default float
min float
max float

Camera.AutoExposure

Auto exposure.

Field Type Label Description
value bool
default bool

Camera.DigitalGain

Digital gain.

Field Type Label Description
value int32
default int32
min int32
max int32

Camera.Exposure

Exposure.

Field Type Label Description
value int32
default int32
min int32
max int32

Camera.Focus

Focus settings descriptor.

Field Type Label Description
value Camera.Focus.Value Focus value.
box Camera.Focus.Box Auto focus box.

Camera.Focus.Box

Auto focus box.

Field Type Label Description
value MF.V3.Settings.Rectangle repeated
default MF.V3.Settings.Rectangle repeated

Camera.Focus.Value

Focus value.

Field Type Label Description
value int32 repeated
default int32 repeated
min int32
max int32

Top

MF/V3/Descriptors/Settings/Capture

Capture

Capture settings descriptor.

Field Type Label Description
quality Capture.Quality Capture quality preset.
texture Capture.Texture Capture texture.

Capture.Quality

Capture quality preset.

Field Type Label Description
value MF.V3.Settings.Quality
default MF.V3.Settings.Quality

Capture.Texture

Capture texture.

Field Type Label Description
value bool
default bool

Top

MF/V3/Descriptors/Settings/I18n

I18n

I18n language settings descriptor.

Field Type Label Description
language I18n.Language Language settings descriptor.

I18n.Language

Language settings descriptor.

Field Type Label Description
value MF.V3.Settings.I18n.Language
default MF.V3.Settings.I18n.Language

Top

MF/V3/Descriptors/Settings/Projector

Projector

Projector settings descriptor.

Field Type Label Description
brightness Projector.Brightness Projector brightness.
on Projector.On Projector on/off.

Projector.Brightness

Projector brightness.

Field Type Label Description
value float
default float
min float
max float

Projector.On

Projector on/off.

Field Type Label Description
value bool
default bool

Top

MF/V3/Descriptors/Settings/Scanner

Scanner

Scanner settings descriptor.

Field Type Label Description
advanced Advanced Advanced settings descriptor.
camera Camera Camera settings descriptor.
capture Capture Capture settings descriptor.
projector Projector Projector settings descriptor.
i18n I18n Internalization setting descriptor.
style Style Style settings descriptor.
turntable Turntable Turntable settings descriptor.
tutorials Tutorials Tutorials settings descriptor.
viewer Viewer Viewer settings descriptor.

Top

MF/V3/Descriptors/Settings/Style

Style

Style settings descriptor.

Field Type Label Description
theme Style.Theme Theme settings descriptor.

Style.Theme

Theme settings descriptor.

Field Type Label Description
value MF.V3.Settings.Style.Theme
default MF.V3.Settings.Style.Theme

Top

MF/V3/Descriptors/Settings/Turntable

Turntable

Turntable settings descriptor.

Field Type Label Description
steps Turntable.Steps The number of turntable steps.
sweep Turntable.Sweep Turntable angle sweep in degrees.
use Turntable.Use Use the turntable.

Turntable.Steps

The number of turntable steps.

Field Type Label Description
value int32
default int32
min int32
max int32

Turntable.Sweep

Turntable angle sweep in degrees.

Field Type Label Description
value int32
default int32
min int32
max int32

Turntable.Use

Use the turntable.

Field Type Label Description
value bool
default bool

Top

MF/V3/Descriptors/Settings/Tutorials

Tutorials

Tutorials settings descriptor.

Field Type Label Description
show Tutorials.Show Show tutorials.
viewed Tutorials.Viewed Viewed tutorials.

Tutorials.Show

Tutorials to show.

Field Type Label Description
value bool
default bool

Tutorials.Viewed

Viewed tutorials.

Field Type Label Description
pages Tutorials.Viewed.Pages Viewed tutorials pages.

Tutorials.Viewed.Pages

Viewed tutorials pages.

Field Type Label Description
value string repeated
default string repeated

Top

MF/V3/Descriptors/Settings/Viewer

Viewer

3D Viewer settings descriptor.

Field Type Label Description
textureOpacity Viewer.TextureOpacity Texture opacity.

Viewer.TextureOpacity

Texture opacity.

Field Type Label Description
value float
default float
min float
max float

Top

MF/V3/Descriptors/System

System

System descriptor.

Field Type Label Description
serialNumber string Serial number;
diskSpace System.DiskSpace Used and available disk space.
software System.Software Software descriptor.

System.DiskSpace

Disk space descriptor.

Field Type Label Description
capacity uint64 Disk space capacity in bytes.
available uint64 Available disk space in bytes.

System.Software

Software descriptor.

Field Type Label Description
installed System.Software.Package repeated Installed software versions.
available System.Software.Package repeated Available software versions.

System.Software.Package

Software package descriptor.

Field Type Label Description
name MF.V3.Settings.Software.Package The package name.
version System.Software.Version The package version.

System.Software.Version

Software version descriptor.

Field Type Label Description
major int32 The major version.
minor int32 The minor version.
patch int32 The patch version.
suffix string The alphanumeric suffix. e.g. "rc0"
string string The version string. e.g. "1.2.3-rc0"

Top

MF/V3/Descriptors/Transform

Transform

V3 transform descriptor.

Field Type Label Description
rotation double repeated Axis-angle rotation vector. The direction of the vector is the rotation axis. The magnitude of the vector is rotation angle in radians.
translation double repeated Translation vector.

Top

MF/V3/Descriptors/VideoFrame

VideoFrame

Video frame descriptor.

Field Type Label Description
codec MF.V3.Settings.Video.Codec Video codec.
format MF.V3.Settings.Video.Format Pixel format.
width int32 Image width.
height int32 Image height.
step int32 Image row step in bytes.
number int64 Frame number.
timestamp uint64 Frame timestamp.
duration uint64 Frame duration.
calibrationCard Calibration.DetectedCard Calibration card detection.

Top

MF/V3/Descriptors/Wifi

Wifi

The wifi descriptor.

Field Type Label Description
ssid string The wifi ssid.
networks Wifi.Network repeated The list of wifi networks.

Wifi.Network

The wifi network descriptor.

Field Type Label Description
ssid string The service set identifier.
isPublic bool Is the network public?
isActive bool Is the network active?
password string optional The network password.
quality int32 optional Signal quality [0 ; 100].

Top

MF/V3/Settings/Advanced

Advanced

Advanced settings.

Field Type Label Description
capture Advanced.Capture optional Capture settings.
sampling Advanced.Sampling optional Sampling settings.
edgeDetection Advanced.EdgeDetection optional Edge detection settings.
phaseFilter Advanced.PhaseFilter optional Phase filter settings.
adaptiveSampling Advanced.AdaptiveSampling optional Adaptive sampling settings.
normalEstimation Advanced.NormalEstimation optional Normal estimation settings.
outlierRemoval Advanced.OutlierRemoval optional Radius outlier removal settings.
remesh Advanced.Remesh optional Remesh settings.

Advanced.AdaptiveSampling

Adaptive sampling settings

Adaptive sampling will downsample points in regions of low detail and keep points in regions of high detail.

Field Type Label Description
type Scan.Processing.AdaptiveSampling.Type optional Sampling type.
rate float The sample rate [0..1] for the regions of low detail.
use bool optional Use the adaptive sampling settings.

Advanced.Capture

Capture settings.

Field Type Label Description
horizontalFrequencies int32 repeated Projector sample rate.
verticalFrequencies int32 repeated Image sample rate.
use bool optional Use the capture settings.

Advanced.EdgeDetection

Edge detection settings.

Field Type Label Description
threshold float optional The edge detection threshold.
laplacianKernelRadius int32 optional The Laplacian kernel radius. This must be in the range [1..5].
gaussianBlurRadius int32 optional Gaussian blur kernel radius. (Optional) To disable, set to 0.

The phase images can optionally blurred before taking the Laplacian to reduce noise. However as a result, the detected edges are wider. | | gaussianBlurStdDev | float | optional | Gaussian blur kernel standard deviation. This parameter is ignored if \p gaussianBlurSize is zero. | | maximumWidthForProcessing | int32 | optional | The maximum image width for processing. (Optional) To disable, set to 0.

If this value is greater than zero, the phase images are resized to the maximum width prior to computing the Laplacian and the the detected edges are then upsampled to the original size.

This would be done to speed up processing or to detect edges on a larger scale. | | use | bool | optional | Use the edge detection settings. |

Advanced.NormalEstimation

Normal estimation settings.

Field Type Label Description
method Scan.Processing.NormalEstimation.Method optional Normal estimation method.
maximumNeighbourCount int32 optional Maximum number of nearest neighbors used to compute the normal. This value is only used with the NORMAL_OPEN3D method.
maximumNeighbourRadius float optional Maximum radius for a point32 to be considered a neighbour.
useMaximumNeighbourCount bool optional
useMaximumNeighbourRadius bool optional
use bool optional Use the normal estimation settings.

Advanced.OutlierRemoval

Radius outlier removal settings.

Field Type Label Description
neighbourCount int32 optional The minimum number of points within the radius for a point32 to be retained.
neighbourRadius float optional The neighbour search radius.
use bool optional Use the outlier removal settings.

Advanced.PhaseFilter

Phase filter settings.

Field Type Label Description
kernelRadius int32 optional The filter kernel radius.

A neighboring value must be within this radius to be included in the filter. If the kernel radius is set to zero, the phase filtering is disabled. | | spatialWeightStdDev | float | optional | The standard deviation of the spatial weights.

The weight of a neighboring value is \f$ exp(-(r/s)^2) \f$ where \f$ r \f$ is the distance to the central value and \f$ s \f$ is the spatial weight standard deviation.

If the spatial weight standard deviation is set to zero, all the spatial weights are uniformly set to 1. | | use | bool | optional | Use the phase filter settings. |

Advanced.PointClipping

Point32 clipping settings.

Field Type Label Description
type Scan.Processing.PointClipping.Type optional Point32 clipping type.
transform double repeated 4x4 transform mapping 3D points to the canonical point32 clipping coordinates.
use bool optional Use the point32 clipping settings.

Advanced.Remesh

Remesh settings.

Field Type Label Description
quality Quality optional Remesh quality preset.
voxelSize float optional Voxel size.
depth int32 optional Depth.
scale float optional Scale.
linearInterpolation bool optional Linear Interpolation.
use bool optional Use the remesh settings.

Advanced.Sampling

Sampling settings.

Field Type Label Description
projectorSampleRate float optional Projector sample rate.
imageSampleRate float optional Image sample rate.
use bool optional Use the sampling settings.

Top

MF/V3/Settings/Align

Align

Alignment settings.

Field Type Label Description
source int32 Index of the scan or group to align.
target int32 Index of the scan or group to align to.
rough Align.Rough optional Rough alignment settings.
fine Align.Fine optional Fine alignment settings.

Align.Fine

Fine alignment settings.

Field Type Label Description
method Align.Fine.Method Fine alignment method.
icp Align.ICP optional Iterative closest point settings.
initialTransform Align.Fine.Transform optional The initial transform for fine alignment.

Align.Fine.Transform

Field Type Label Description
rotation double repeated
translation double repeated

Align.ICP

Iterative closest point alignment settings.

Field Type Label Description
matchDistance float The maximum distance for two points to be considered a match.

Align.Points

Point pair alignment settings.

Field Type Label Description
points float repeated The set of corresponding point pairs.
absoluteError float optional The maximum absolute error for a point pair to be an inlier to the model.
relativeError float optional The maximum error relative to the size of the aligned scans for a point pair to be an inlier to the model.
useAllPoints bool optional Ignore alignment errors and use all selected points for alignment.

Align.Ransac

Ransac alignment settings.

Field Type Label Description
downsampleVoxelSize float optional
maximumFeatureRadius float optional
maximumFeaturePointCount int32 optional
maximumMatchDistance float optional
minimumMatchSimilarity float optional
mutualFilter bool optional

Align.Rough

Rough alignment settings.

Field Type Label Description
method Align.Rough.Method Rough alignment method.
ransac Align.Ransac optional FastGlobal fastGlobal;
points Align.Points optional Point pair alignment settings.

Align.Fine.Method

Fine alignment methods.

Name Number Description
None 0 No fine alignment.
ICP 1 Iterative closest point alignment.

Align.Rough.Method

Rough alignment methods.

Name Number Description
None 0 No rough alignment.
FastGlobal 1 Fast global alignment.
Ransac 2 Ransac alignment.
Points 3 Point pair alignment.

Top

MF/V3/Settings/AutoFocus

AutoFocus

Auto focus settings.

Field Type Label Description
cameras AutoFocus.Camera repeated The set of cameras on which to apply auto focus.
applyAll bool Apply the final focus value to both cameras. This setting is ignored if more than one camera is selected.

AutoFocus.Camera

Auto focus camera settings.

Field Type Label Description
index int32 The index of the camera on which to apply auto focus.
box Rectangle optional The image rectangle in video image pixels on which to apply auto focus.

Top

MF/V3/Settings/BoundingBox

BoundingBox

Bounding box settings.

Field Type Label Description
selection ScanSelection The scan selection.
axisAligned bool If true, align the bounding box with the world axes. Otherwise orient the bounding box with the scans.

Top

MF/V3/Settings/Camera

Camera

Camera settings.

Field Type Label Description
selection int32 repeated Camera selection. Default is all cameras.
autoExposure bool optional Auto exposure.
exposure int32 optional Exposure.
analogGain float optional Analog gain.
digitalGain int32 optional Digital gain.
focus int32 optional Focus value.

Top

MF/V3/Settings/Capture

Capture

Capture settings.

Field Type Label Description
quality Quality optional Capture quality preset.
texture bool optional Capture texture.
calibrationCard bool optional Detect the calibration card.
horizontalFrequencies int32 repeated Horizontal pattern frequencies.
verticalFrequencies int32 repeated Vertical pattern frequencies.

Top

MF/V3/Settings/Export

Export

Export settings.

Field Type Label Description
selection ScanSelection optional The scan selection.
texture bool optional Export textures.
merge bool optional Merge the scans into a single file.
format Export.Format optional The export format.

Export.Format

Scan export formats.

Name Number Description
ply 0 Polygon format.
dae 1 Digital asset exchange format.
fbx 2 Autodesk format.
glb 3 GL transmission format.
obj 4 Wavefront format.
stl 5 Stereolithography format.
xyz 6 Chemical format.

Top

MF/V3/Settings/Group

Group

Scan group settings.

Field Type Label Description
index int32 The unique group index that identifies the group within the group tree.
name string optional Group name.
color float repeated Color in the renderer.
visible bool optional Visibility in the renderer.
collapsed bool optional Collapsed state in the group tree.
rotation double repeated Axis-angle rotation vector. The direction of the vector is the rotation axis. The magnitude of the vector is rotation angle in radians.
translation double repeated Translation vector.

Top

MF/V3/Settings/I18n

I18n

I18n language settings.

Field Type Label Description
language I18n.Language optional The language setting. Supported languages are ["en", "fr", "de"].

I18n.Language

Available languages.

Name Number Description
en 0
fr 1
de 2

Top

MF/V3/Settings/Merge

Merge

Scan merge settings.

Field Type Label Description
selection ScanSelection optional The scan selection.
remesh Merge.Remesh optional Remesh settings.
simplify Merge.Simplify optional Simplify settings.
texturize bool optional Apply textures to the merged mesh.

Merge.Remesh

Remesh settings.

Field Type Label Description
method Merge.Remesh.Method optional Remesh method.
quality Quality optional Remesh quality.
fast Merge.Remesh.Fast optional Fast remesh options (Ignored if method is 'Poison').
poisson Merge.Remesh.Poisson optional Poisson remesh options (Ignored if method is not 'Poisson').
voxelSize float optional Temporary for backwards compatibility Voxel size.
depth int32 optional Depth.
scale float optional Scale.
linearInterpolation bool optional Linear Interpolation.

Merge.Remesh.Fast

Fast remesh settings

Field Type Label Description
scale float optional Output resolution scale. Smaller means more faces.
faceCount int32 optional The approximate number of remeshed faces.
vertexCount int32 optional The approximate number of remeshed vertices.
creaseAngleThreshold float optional The crease angle threshold.
extrinsicSmoothness bool optional Use extrinsic smoothness.
alignToBoundaries bool optional Align mesh to boundaries.
smoothIterations int32 optional The number of smoothing iterations.
knnPoints int32 optional The number of KNN points (point cloud input only).
deterministic bool optional Use deterministic (repeatable) remeshing.

Merge.Remesh.Poisson

Field Type Label Description
voxelSize float optional Voxel size.
depth int32 optional Depth.
scale float optional Scale.
linearInterpolation bool optional Linear Interpolation.

Merge.Simplify

Simplify settings.

Field Type Label Description
triangleCount int32 Target triangle count.

Merge.Remesh.Method

Remesh method.

Name Number Description
FastTriangles 0 Fast remesh as triangles.
FastQuads 1 Fast remesh as quads.
FastQuadDominant 2 Fast remesh as quad-dominant mesh.
PoissonTriangles 3 Poisson remesh as triangles.

Top

MF/V3/Settings/NewGroup

NewGroup

Scan group settings.

Field Type Label Description
parentIndex int32 optional The index of the parent group in which the new group is created. If unspecified the new group is added to the root of the group tree.
baseName string optional Group base name. The new group name will start with the base name followed by a unique index number chosen by the backend.
color float repeated Group color.
visible bool optional Group visibility.
collapsed bool optional Collapsed state in the group tree.
rotation double repeated Group axis-angle rotation vector. The direction of the vector is the rotation axis. The magnitude of the vector is rotation angle in radians.
translation double repeated Group translation vector.

Top

MF/V3/Settings/Project

Project

Project settings.

Field Type Label Description
name string optional Project name.

Top

MF/V3/Settings/Projector

Projector

Projector settings.

Field Type Label Description
on bool optional Projector on/off.
brightness float optional Projector brightness.
pattern Projector.Pattern optional Structured light pattern.
image Projector.Image optional Image to project
color float repeated Solid color

Projector.Image

Projector image settings

Field Type Label Description
source Projector.Image.Source Image source.
target Rectangle Image target rectangle.

Projector.Image.Source

Image source.

Field Type Label Description
format Video.Format Source image format
width int32 Source image width.
height int32 Source image height.
step int32 Source image step in bytes.
fixAspectRatio bool Fix the source aspect ratio to the target rectangle.

Projector.Pattern

Structured light pattern.

Field Type Label Description
orientation Projector.Orientation Pattern orientation.
frequency int32 Pattern frequency index. [0 - 8]
phase int32 Pattern phase. [0 - 2]

Projector.Orientation

Pattern orientation.

Name Number Description
Horizontal 0 Horizontal pattern. Image columns are identical.
Vertical 1 Vertical pattern. Image rows are identical.

Top

MF/V3/Settings/Quality

Quality

Quality settings.

Name Number Description
Low 0 Low quality.
Medium 1 Medium quality.
High 2 High quality.

Top

MF/V3/Settings/Rectangle

Rectangle

Rectangle settings.

Field Type Label Description
x int32 Rectangle x offset.
y int32 Rectangle y offset.
width int32 Rectangle width.
height int32 Rectangle height.

Top

MF/V3/Settings/Remesh

Remesh

Field aligned remesh settings.

Field Type Label Description
scan int32 The scan index.
type Remesh.Type optional The type of output mesh.
scale float optional Scale
faceCount int32 optional The approximate number of remeshed faces.
vertexCount int32 optional The approximate number of remeshed vertices.
creaseAngleThreshold float optional The crease angle threshold.
extrinsicSmoothness bool optional Use extrinsic smoothness.
alignToBoundaries bool optional Align mesh to boundaries.
smoothIterations int32 optional The number of smoothing iterations.
knnPoints int32 optional The number of KNN points (point cloud input only).
deterministic bool optional Use deterministic (repeatable) remeshing.

Remesh.Type

Types of remesh output.

Name Number Description
triangle 0 Triangle mesh output.
quad 1 Quad mesh output.
quadDominant 2 Quad-dominant mesh output.

Top

MF/V3/Settings/Scan

Scan

Scan settings.

Field Type Label Description
camera Camera Camera settings.
projector Projector Projector settings.
turntable Turntable optional Turntable settings.
capture Capture Capture settings.
processing Scan.Processing optional Processing settings.

Scan.Processing

Scan processing settings.

Field Type Label Description
projectorSampleRate float optional Projector sample rate.
imageSampleRate float optional Image sample rate.
edgeDetection Scan.Processing.PhaseEdgeDetection optional Phase edge detection settings.
phaseFilter Scan.Processing.PhaseFilter optional Phase filter settings.
adaptiveSampling Scan.Processing.AdaptiveSampling optional Adaptive sampling settings.
pointClipping Scan.Processing.PointClipping repeated Point clipping settings.
normalEstimation Scan.Processing.NormalEstimation optional Normal estimation settings.
outlierRemoval Scan.Processing.OutlierRemoval optional Outlier removal settings.

Scan.Processing.AdaptiveSampling

Adaptive sampling settings

Adaptive sampling will downsample points in regions of low detail and keep points in regions of high detail.

Field Type Label Description
type Scan.Processing.AdaptiveSampling.Type Sampling type.
rate double The sample rate [0..1] for the regions of low detail.

Scan.Processing.NormalEstimation

Normal estimation settings.

Field Type Label Description
method Scan.Processing.NormalEstimation.Method Normal estimation method.
maximumNeighbourCount int32 Maximum number of nearest neighbors used to compute the normal. This value is only used with the NORMAL_OPEN3D method.
maximumNeighbourRadius float Maximum radius for a point to be considered a neighbour.
useMaximumNeighbourCount bool Use the maximum neighbour count.
useMaximumNeighbourRadius bool Use the maximum neighbour radius.

Scan.Processing.OutlierRemoval

Outlier removal settings.

Field Type Label Description
neighbourCount int32 The minimum number of points within the radius for a point to be retained.
neighbourRadius float The neighbour search radius.

Scan.Processing.PhaseEdgeDetection

Phase edge detection settings.

Phase edge detection produces a binary mask indicating the edges of a horizontal/vertical pair of phase images. Since flat geometries give a constant phase image gradient, we use the second derivative (Laplacian) of the phase image to detect edges rather than the gradient.

The edge mask generated by phase edge detection is an input to both phase filtering and adaptive sampling. If neither of these are enabled, the phase edge detection settings have no effect on the output point cloud.

Field Type Label Description
threshold double The edge detection threshold.
laplacianKernelRadius int32 The Laplacian kernel radius. This must be in the range [1..5].
gaussianBlurRadius int32 Gaussian blur kernel radius. (Optional) To disable, set to 0. The phase images can optionally blurred before taking the Laplacian to reduce noise. However as a result, the detected edges are wider.
gaussianBlurStdDev double Gaussian blur kernel standard deviation. This parameter is ignored if gaussianBlurSize is zero.
maximumWidthForProcessing int32 The maximum image width for processing. (Optional) To disable, set to 0. If this value is greater than zero, the phase images are resized to the maximum width prior to computing the Laplacian and the the detected edges are then upsampled to the original size. This would be done to speed up processing or to detect edges on a larger scale.

Scan.Processing.PhaseFilter

Phase filter settings.

Field Type Label Description
kernelRadius int32 The filter kernel radius. A neighboring value must be within this radius to be included in the filter. If the kernel radius is set to zero, the phase filtering is disabled.
spatialWeightStdDev double The standard deviation of the spatial weights. The weight of a neighboring value is $\exp(-(r/s)^2)$ where $r$ is the distance to the central value and $s$ is the spatial weight standard deviation. If the spatial weight standard deviation is set to zero, all the spatial weights are uniformly set to 1.

Scan.Processing.PointClipping

Point clipping settings.

Field Type Label Description
type Scan.Processing.PointClipping.Type Point clipping type.
transform double repeated 4x4 transform mapping 3D points to the canonical point clipping coordinates.

Scan.Processing.AdaptiveSampling.Type

Name Number Description
NONE 0 Do not use adaptive sampling.
REGULAR 1 Use a regular sampling mask in regions of low detail.
RANDOM 2 Use a random sampling mask in regions of low detail.

Scan.Processing.NormalEstimation.Method

Name Number Description
NORMAL_LLS 0 Linear least squares method
NORMAL_OPEN3D 1 Open3D method using KD tree search for nearest neighbors

Scan.Processing.PointClipping.Type

Point clipping type.

Name Number Description
OutsideCube 0 Clip points outside a unit cube.
OutsideCylinder 1 Clip points outside a unit cylinder.
OutsideSphere 2 Clip points outside a unit sphere.
InsideCube 3 Clip points inside a unit cube.
InsideCylinder 4 Clip points inside a unit cylinder.
InsideSphere 5 Clip points inside a unit sphere.

Top

MF/V3/Settings/ScanData

ScanData

Scan data request.

Field Type Label Description
index int32 Requested index of the scan in the current open project.
mergeStep ScanData.MergeStep optional The merge process step if requesting merge data.
buffers ScanData.Buffer repeated Requested scan buffers.
metadata ScanData.Metadata repeated Requested scan metadata.

ScanData.Buffer

Scan buffer type.

Name Number Description
Position 0 Vertex position.
Normal 1 Vertex normal.
Color 2 Vertex color.
UV 3 Vertex UVs
Triangle 4 Triangle index.
Texture 5 Texture.
All 6 All buffer types.

ScanData.MergeStep

The merge processing step.

Name Number Description
Combined 0 The scan meshes are simply combined into a single mesh.
Remeshed 1 The combined mesh is remeshed to give a single geometric surface.
Simplified 2 The combined or remeshed mesh is simplified to a reduced number of triangles.
Textured 3 The merged mesh has been textured.

ScanData.Metadata

Scan metadata type.

Name Number Description
Mean 0 The mean (centroid) of the vertex positions.
StdDev 1 The standard deviation of the vertex positions.
AxisAlignedBoundingBox 2 The axis-aligned bounding box of the vertex positions.

Top

MF/V3/Settings/ScanSelection

ScanSelection

Scan selection.

Field Type Label Description
mode ScanSelection.Mode The scan selection mode.
groups int32 repeated The set of user-selected groups. These are only used if the selection mode is 'selected'.

ScanSelection.Mode

Scan selection mode.

Name Number Description
selected 0 Select user-selected groups.
visible 1 Select visible scans.
all 2 Select all scans.

Top

MF/V3/Settings/Scanner

Scanner

Scanner settings.

Field Type Label Description
advanced Advanced optional Advanced settings.
camera Camera optional Camera settings.
capture Capture optional Capture settings.
i18n I18n optional I18n settings.
projector Projector optional Projector settings.
style Style optional Style settings.
turntable Turntable optional Turntable settings.
tutorials Tutorials optional Tutorials settings.
viewer Viewer optional Viewer settings.

Top

MF/V3/Settings/Software

Software

V3 software settings.

Field Type Label Description
installed Software.Package repeated Request installed software packages. If undefined all installed packages are returned.
available Software.Package repeated Request available software packages. If undefined all available packages are returned.

Software.Package

Software package types.

Name Number Description
server 0 The server software package.
frontend 1 The frontend software package.

Top

MF/V3/Settings/Style

Style

Style settings.

Field Type Label Description
theme Style.Theme optional Theme setting.

Style.Theme

Themes.

Name Number Description
Light 0 Light mode.
Dark 1 Dark mode.

Top

MF/V3/Settings/Turntable

Turntable

Turntable settings.

Field Type Label Description
use bool optional Use the turntable.
steps int32 The number of turntable steps.
sweep int32 Turntable angle sweep in degrees.

Top

MF/V3/Settings/Tutorials

Tutorials

Tutorials settings.

Field Type Label Description
show bool optional Show tutorials.
viewed Tutorials.Viewed optional Viewed tutorials.

Tutorials.Viewed

Viewed tutorials.

Field Type Label Description
pages string repeated Viewed tutorials pages.

Top

MF/V3/Settings/Video

Video

Video settings.

Field Type Label Description
codec Video.Codec Video codec.
format Video.Format Pixel format.
width int32 Image width.
height int32 Image height.

Video.Codec

Video codecs.

Name Number Description
NoCodec 0 No codec specified.
RAW 1 Raw encoding.
JPEG 2 JPEG encoding.
H264 3 H264 encoding.

Video.Format

Pixel formats.

Name Number Description
NoFormat 0 No format specified.
RGB565 1 RGB565 16-bit
RGB888 2 RGB888 24-bit.
BGR888 3 BGR888 24-bit.
YUV420 4 YUV 420 planar.

Top

MF/V3/Settings/Viewer

Viewer

3D Viewer settings.

Field Type Label Description
textureOpacity float optional Texture opacity.

Top

MF/V3/Settings/Wifi

Wifi

Wifi connection settings.

Field Type Label Description
ssid string The wifi ssid.
password string The wifi password.

Top

MF/V3/Task

Task

Generic task message for the Three Scanner.

The task message is the generic message used for requesting a task of the Three Scanner and receiving updates and results.

Example: Apply camera settings with the "SetCameras" task.

> Example request:

{
    "Task":{
        "Index":1,
        "Type":"SetCameras"
        "Input":{
            "analogGain":256,
            "digitalGain":128,
            "exposure":18000
        },
    }
}

> Example response:

{
    "Task":{
        "Index":1,
        "Type":"SetCameras"
        "Input":{
            "analogGain":256,
            "digitalGain":512,
            "exposure":18000
        },
        "Output":{
            "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
            "digitalGain":{"default":256,"max":65536,"min":256,"value":512},
            "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
        },
        "State":"Completed"
    }
}
Field Type Label Description
Index int32 A unique identifier generated by the client. This identifier associates all incoming and outgoing task messages with a specific task requested by the client.
Type string The string identifying the task type. See task definitions for the list of valid task strings.
Input googlebuf.Any optional Optional input message. See each task definition for details.
Output googlebuf.Any optional Optional output message. See each task definition for details.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

TaskState

Name Number Description
None 0 The task state is not defined.
Sent 1 The task has been sent by the client.
Received 2 The task has been received by the server.
Started 3 The task started by the server.
Completed 4 The task is completed by the server.
Cancelled 5 The task has been cancelled by the client.
Failed 6 The task has failed. A string describing the error is returned with the task.
Dropped 7 The task has not been received by the server, or task IDs were sent out of sequence.
Disconnected 8 The client has been disconnected from the server before the task could finish.

Top

MF/V3/Tasks/AddMergeToProject

AddMergeToProject

Add a merged scan to the current project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"AddMergeToProject"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"AddMergeToProject",
        "Output":{
            "groups":[
                {
                    "index":1,
                    "name":"Scan-1",
                    "scan": 1,
                    "color":[0.5, 0.8, 0.3]
                }
            ]
        },
        "State":"Completed"
    }
}

AddMergeToProject.Request

Client request for the AddMergeToProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "AddMergeToProject"

AddMergeToProject.Response

Server response for the AddMergeToProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "AddMergeToProject"
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/Align

Align

Align two scan groups.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"Align",
        "Input":{
            "source":1,
            "target":2,
            "rough":{"method": "FastGlobal"},
            "fine":{"method": "ICP"}
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"Align",
        "Input":{
            "source":1,
            "target":2,
            "rough":{"method": "FastGlobal"},
            "fine":{"method": "ICP"}
        },
        "Output":{
            "rotation":[0.2, 0.4, 0.6],
            "translation":[11, -10, 24]
        },
        "State":"Completed"
    }
}

Align.Request

Client request for the Align task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "Align"
Input Settings.Align The align settings.

Align.Response

Server response for the Align task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "Align"
Input Settings.Align The requested align settings.
Output Descriptors.Transform The transform that aligns the source scan group to the target scan group.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/AutoFocus

AutoFocus

Auto focus one or both cameras.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"AutoFocus",
        "Input":{
            "cameras":[{
                "index":1,
                 "box":{"x":196,"y":130,"width":64,"height":64}
            }],
            "applyAll":false
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"AutoFocus",
        "Input":{
            "cameras":[{
                "index":1,
                 "box":{"x":196,"y":130,"width":64,"height":64}
            }],
            "applyAll":false
        }
        "Output":{
            "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
            "autoExposure":{"default":false,"value":true},
            "digitalGain":{"default":256,"max":65536,"min":256,"value":320},
            "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
            "focus":{
                "box":{
                    "default":[
                        {"height":64,"width":64,"x":224,"y":158},
                        {"height":64,"width":64,"x":224,"y":158}
                    ],
                    "value":[
                        {"height":64,"width":64,"x":271,"y":134},
                        {"height":64,"width":64,"x":196,"y":130}
                    ]
                },
                "value":{"default":[350,350],"max":1024,"min":0,"value":[396,392]}
            }
        },
        "State":"Completed"
    }
}

AutoFocus.Request

Client request for the AutoFocus task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "AutoFocus"
Input Settings.AutoFocus optional AutoFocus settings.

AutoFocus.Response

Server response for the AutoFocus task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "AutoFocus"
Input Settings.AutoFocus optional Requested auto focus settings.
Output Descriptors.Settings.Camera optional Actual camera settings after auto focusing the camera(s).
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/BoundingBox

BoundingBox

Get the bounding box of a set of scan groups.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"BoundingBox",
        "Input":{
            "selection":{"mode":"visible"},
            "axisAligned":false
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"BoundingBox",
        "Input":{
            "selection":{"mode":"visible"},
            "axisAligned":false
        },
        "Output":{
            "center":[11.9,-10.1,94.5],
            "rotation":[
                0.7, -0.7, 0.0,
                0.7,  0.7, 0.0,
                0.0,  0.0, 1.0],
            "size":[442.2,253.1,447.1],
            "transform":[
                221, 0.0, 0.0,  11.9,
                0.0, 126, 0.0, -10.1,
                0.0, 0.0, 223,  94.5,
                0.0, 0.0, 0.0,   1.0]
        },
        "State":"Completed"
    }
}

BoundingBox.Request

Client request for the BoundingBox task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "BoundingBox"
Input Settings.BoundingBox The bounding box settings.

BoundingBox.Response

Server response for the BoundingBox task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "BoundingBox"
Input Settings.BoundingBox The requested bounding box settings.
Output Descriptors.BoundingBox The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/CalibrateCameras

CalibrateCameras

Calibrate the cameras.

This task starts the camera calibration capture sequence where the user is guided to place the calibration card with a card outline drawn on the video feed. Once each calibration card pose is captured, the cameras are calibrated and the calibration results are returned as a string. If the cameras cannot be calibrated the task finishes in a Failed state.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrateCameras"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrateCameras",
        "Output":"Camera calibration results: ...",
        "State":"Completed"
    }
}

CalibrateCameras.Request

Client request for the CalibrateCameras task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "CalibrateCameras"

CalibrateCameras.Response

Server response for the CalibrateCameras task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "CalibrateCameras"
Output string optional Camera calibration results.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/CalibrateTurntable

CalibrateTurntable

Calibrate the turntable.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrateTurntable"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrateTurntable",
        "Output":"Turntable calibration results: ...",
        "State":"Completed"
    }
}

CalibrateTurntable.Request

Client request for the CalibrateTurntable task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "CalibrateTurntable"

CalibrateTurntable.Response

Server response for the CalibrateTurntable task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "CalibrateTurntable"
Output string optional Turntable calibration results.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/CalibrationCaptureTargets

CalibrationCaptureTargets

Get the camera calibration targets.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrationCaptureTargets"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"CalibrationCaptureTargets",
        "Output":{[
            {
                "camera":0,
                "quads":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]
            },
            {
                "camera":1,
                "quads":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]
            },
        ]},
        "State":"Completed"
    }
}

CalibrationCaptureTargets.Request

Client request for the CalibrationCaptureTargets task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "CalibrationCaptureTargets"

CalibrationCaptureTargets.Response

Server response for the CalibrationCaptureTargets task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "CalibrationCaptureTargets"
Output Descriptors.Calibration.CaptureTarget optional The calibration capture target descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/CameraCalibration

CameraCalibration

Get the camera calibration descriptor.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"CameraCalibration"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"CameraCalibration",
        "Output":{
            "date":[2024,4,27,16,57,35],
            "quality":"Excellent"
        },
        "State":"Completed"
    }
}

CameraCalibration.Request

Client request for the CameraCalibration task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "CameraCalibration"

CameraCalibration.Response

Server response for the CameraCalibration task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "CameraCalibration"
Output Descriptors.Calibration.Camera optional The camera calibration descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/CloseProject

CloseProject

Close the current open project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"CloseProject",
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"CloseProject",
        "State":"Completed"
    }
}

CloseProject.Request

Client request for the CloseProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "CloseProject"

CloseProject.Response

Server response for the CloseProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "CloseProject"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ConnectWifi

ConnectWifi

Connect to a wifi network.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ConnectWifi",
        "Input":{
            "ssid":"Network1"
            "password":"password"   
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ConnectWifi",
        "Input":{
        {
            "ssid":"Network1"
            "password":"password"   
        }
        "State":"Completed"
    }
}

ConnectWifi.Request

Client request for the ConnectWifi task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ConnectWifi"
Input Settings.Wifi Wifi settings.

ConnectWifi.Response

Server response for the ConnectWifi task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ConnectWifi"
Input Settings.Wifi The requested wifi settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/DepthMap

DepthMap

Capture a new scan.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"DepthMap"
        "Input":{
            "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
            "capture":{"quality":"Medium","texture":true},
            "projector":{"brightness":0.8}
        },
    }
}

> Depth map buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":13128960,
        "Descriptor":{
            "cols":2104,
            "rows":1560,
            "step":8416,
            "type":5
        },
        "Task":{
            "Index":1,
            "Type":"DepthMap",
            "Input":{
                "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
                "capture":{"quality":"Medium","texture":true},
                "projector":{"brightness":0.8}
            }
        }
    }
}

> Depth map binary data transfer from server [13128960 bytes].

> Texture buffer message from server.

{
    "Buffer":{
        "Index":1,
        "Size":9846720,
        "Descriptor":{
            "cols":2104,
            "rows":1560,
            "step":6312,
            "type":16
        },
        "Task":{
            "Index":1,
            "Type":"DepthMap",
            "Input":{
                "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
                "capture":{"quality":"Medium","texture":true},
                "projector":{"brightness":0.8}
            }
        }
    }
}

> Texture binary data transfer from server [9846720 bytes].

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"DepthMap"
        "Input":{
            "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
            "capture":{"quality":"Medium","texture":true},
            "projector":{"brightness":0.8}
        },
        "Output":[2500,0,1052,0,2500,780,0,0,1],
        "State":"Completed"
    }
}

DepthMap.Buffer

Server buffer message for the DepthMap task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested DepthMap task.
Descriptor Descriptors.Image The image descriptor.

DepthMap.Request

Client request for the DepthMap task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "DepthMap"
Input Settings.Scan optional Scan settings.

DepthMap.Response

Server response for the DepthMap task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "DepthMap"
Input Settings.Scan optional Requested scan settings.
Output double repeated The 9 values of the camera matrix corresponding to the depth map (row-major).
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/DetectCalibrationCard

DetectCalibrationCard

Detect the calibration card on one or both cameras.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"DetectCalibrationCard",
        "Input":3
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Input":3,
        "Type":"DetectCalibrationCard",
        "State":"Completed"
    }
}

DetectCalibrationCard.Request

Client request for the DetectCalibrationCard task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "DetectCalibrationCard"
Input int32 Flag specifying on which camera(s) to detect the calibration card. [0: neither camera (disable), 1: left camera, 2: right camera, 3: both cameras]

DetectCalibrationCard.Response

Server response for the DetectCalibrationCard task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "DetectCalibrationCard"
Input int32 Flag sent in the request specifying on which camera(s) to detect the calibration card. [0: neither camera (disable), 1: left camera, 2: right camera, 3: both cameras]
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/DownloadProject

DownloadProject

Download a project from the scanner.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"DownloadProject",
        "Input":5
    }
}

> Buffer message from server.

{
    "Buffer":{
        "Descriptor":"Project-5.zip",
        "Index":0,
        "Size":15682096,
        "Task":{
            "Index":1,
            "Type":"DownloadProject",
            "Input":5
        }
    }
}

> Binary data transfer from server: The project zip file [15682096 bytes]. > Response example:

{
    "Task":{
        "Index":1,
        "Type":"DownloadProject"
        "Input":5,
        "State":"Completed"
    }
}

DownloadProject.Buffer

Server buffer message for the DownloadProject task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested DownloadProject task.
Descriptor string The downloaded project filename.

DownloadProject.Request

Client request for the DownloadProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "DownloadProject"
Input int32 Index of the project to download.

DownloadProject.Response

Server response for the DownloadProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "DownloadProject"
Input int32 Requested index of the project to download.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/Export

Export

Export a group of scans.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"Export",
        "Input":{
            "selection":{"mode":"visible"},
            "format":"obj",
            "texture":true,
            "merge":false
        }
    }
}

> Export file buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":8413737,
        "Task":{
            "Index":1,
            "Type":"Export",
            "Input":{
                "selection":{"mode":"visible"},
                "format":"obj",
                "texture":true,
                "merge":false
            }
        }
    }
}

> Export file binary data transfer from server [8413737 bytes].

> Response from server:

{
    "Task":{
        "Index":1,
        "Type":"Export"
        "Input":{
            "selection":{"mode":"visible"},
            "format":"obj",
            "texture":true,
            "merge":false
        },
        "State":"Completed"
    }
}

Export.Buffer

Server buffer message for the Export task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested Export task.

Export.Request

Client request for the Export task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "Export"
Input Settings.Export Export settings.

Export.Response

Server response for the Export task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "Export"
Input Settings.Export Requested export settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ExportLogs

ExportLogs

Export scanner logs.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ExportLogs",
        "Input":true
    }
}

> Export file buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":41337,
        "Task":{
            "Index":1,
            "Type":"ExportLogs",
            "Input":true
        }
    }
}

> Export file binary data transfer from server [41337 bytes].

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ExportLogs"
        "Input":true,
        "State":"Completed"
    }
}

ExportLogs.Buffer

Server buffer message for the ExportLogs task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested ExportLogs task.

ExportLogs.Request

Client request for the ExportLogs task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ExportLogs"
Input bool optional Export log images. If unspecified, log images are not exported.

ExportLogs.Response

Server response for the ExportLogs task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ExportLogs"
Input bool optional Requested export log images.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ExportMerge

ExportMerge

Export a merged scan.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ExportMerge",
        "Input":{
            "format":"obj",
            "texture":true
        }
    }
}

> Export file buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":8413737,
        "Task":{
            "Index":1,
            "Type":"ExportMerge",
            "Input":{
                "format":"obj",
                "texture":true
            }
        }
    }
}

> Export file binary data transfer from server [8413737 bytes].

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ExportMerge"
        "Input":{
            "format":"obj",
            "texture":true
        },
        "State":"Completed"
    }
}

ExportMerge.Buffer

Server buffer message for the ExportMerge task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested ExportMerge task.

ExportMerge.Request

Client request for the ExportMerge task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ExportMerge"
Input Settings.Export Export settings.

ExportMerge.Response

Server response for the ExportMerge task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ExportMerge"
Input Settings.Export Requested export settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/FlattenGroup

FlattenGroup

Flatten a scan group such that it only consists of single scans.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"FlattenGroup",
        "Input":0
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"FlattenGroup",
        "Input":0,
        "Output":{
            "groups":[{
                "index":2,
                "name":"Group 2",
                "groups":[{
                    "index":1,
                    "name":"Group 1"
                }]
            }],
        },
        "State":"Completed"
    }
}

FlattenGroup.Request

Client request for the FlattenGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "FlattenGroup"
Input int32 The index of the group to flatten.

FlattenGroup.Response

Server response for the FlattenGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "FlattenGroup"
Input int32 The requested index of the group to flatten.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ForgetWifi

ForgetWifi

Forget all wifi connections.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ForgetWifi"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ForgetWifi"
        "State":"Completed"
    }
}

ForgetWifi.Request

Client request for the ForgetWifi task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ForgetWifi"

ForgetWifi.Response

Server response for the ForgetWifi task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ForgetWifi"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/HasCameras

HasCameras

Check if the scanner has working cameras.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"HasCameras"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"HasCameras",
        "Output":true,
        "State":"Completed"
    }
}

HasCameras.Request

Client request for the HasCameras task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "HasCameras"

HasCameras.Response

Server response for the HasCameras task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "HasCameras"
Output bool optional The working state of the cameras.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/HasProjector

HasProjector

Check if the scanner has a working projector.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"HasProjector"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"HasProjector",
        "Output":true,
        "State":"Completed"
    }
}

HasProjector.Request

Client request for the HasProjector task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "HasProjector"

HasProjector.Response

Server response for the HasProjector task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "HasProjector"
Output bool optional The working state of the projector.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/HasTurntable

HasTurntable

Check if the scanner is connected to a working turntable.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"HasTurntable"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"HasTurntable",
        "Output":true,
        "State":"Completed"
    }
}

HasTurntable.Request

Client request for the HasTurntable task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "HasTurntable"

HasTurntable.Response

Server response for the HasTurntable task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "HasTurntable"
Output bool optional The working start of the connected turntable.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListExportFormats

ListExportFormats

List all export formats and the geometry elements they support.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListExportFormats"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListExportFormats",
        "Output":{[
            {
                "format": "ply",
                "colors": true,
                "description": "Polygon format",
                "extension": ".ply",
                "faces": ["Point","Triangle","Quad"],
                "normals": true,
                "textures": "Single"
            },
            {
                "format": "obj",
                "colors": true,
                "description": "Wavefront format",
                "extension": ".obj",
                "faces": ["Point","Triangle","Quad"],
                "normals": true,
                "textures": "Multiple"
            },
            {
                "format": "stl",
                "colors": false,
                "description": "Stereolithography format",
                "extension": ".stl",
                "faces": ["Point","Triangle"],
                "normals": true,
                "textures": "None"
            } 
        ]},
        "State":"Completed"
    }
}

ListExportFormats.Request

Client request for the ListExportFormats task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListExportFormats"

ListExportFormats.Response

Server response for the ListExportFormats task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListExportFormats"
Output Descriptors.Export repeated The list of export format descriptors.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListGroups

ListGroups

List the scan groups in the current open project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListGroups"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListGroups",
        "Output":{
            "groups":[
                {
                    "index":1,
                    "scan":1,
                    "name":"Scan-1",
                    "color":[0.75,0.5,0.2,1.0],
                    "rotation":[0.03,0.1,-0.01],
                    "translation":[-101,67,-561],
                    "visible":true
                },
                {
                    "index":2,
                    "scan":2,
                    "name":"Scan-2",
                    "color":[0.7,0.9,0.6,1.0],
                    "rotation":[0.1,0.2,0.5],
                    "translation":[-90,64,-553],
                    "visible":true
                },
                {
                    "index":3,
                    "scan":3,
                    "name":"Scan-3",
                    "color":[0.6,0.8,0.9,1.0],
                    "visible":true
                }
            ]
        },
        "State":"Completed"
    }
}

ListGroups.Request

Client request for the ListGroups task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListGroups"

ListGroups.Response

Server response for the ListGroups task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListGroups"
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListNetworkInterfaces

ListNetworkInterfaces

List network interfaces.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListNetworkInterfaces"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListNetworkInterfaces",
        "Output":[
            {"ip":"192.168.1.234","name":"eth0","ssid":""},
            {"ip":"127.0.0.1","name":"lo","ssid":""}
            {"ip":"192.168.2.345","name":"wlan0","ssid":"Network1"}
        ],
        "State":"Completed"
    }
}

ListNetworkInterfaces.Request

Client request for the ListNetworkInterfaces task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListNetworkInterfaces"

ListNetworkInterfaces.Response

Server response for the ListNetworkInterfaces task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListNetworkInterfaces"
Output Descriptors.Network.Interface optional Network interface descriptors.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListProjects

ListProjects

List all projects.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListProjects"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListProjects",
        "Output":[
            {"index":1,"modified":[2024,5,12,11,23,17],"name":"Project 1","size":35409834},
            {"index":2,"modified":[2024,5,12,11,2,37],"name":"Project 2","size":175025367},
            {"index":3,"modified":[2024,5,6,17,15,53],"name":"Project 3","size":24314083}
        ],
        "State":"Completed"
    }
}

ListProjects.Request

Client request for the ListProjects task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListProjects"

ListProjects.Response

Server response for the ListProjects task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListProjects"
Output Descriptors.Project.Brief optional Brief project descriptors.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListScans

ListScans

List the scans in the current open project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListScans"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListScans",
        "Output":{[
            {
                "color":[0.8,0.5,0.6,1.0],
                "index":1,
                "name":"Scan-1",
                "scan":1,
                "rotation":[0.2,0.8,-0.1],
                "translation":[-275,-32,-134],
                "visible":true
            },
            {
                "color":[0.5,0.7,0.2,1.0],
                "index":2,
                "name":"Scan-2",
                "scan":2,
                "rotation":[0.7,-0.5,0.3],
                "translation":[75,-62,38],
                "visible":true
            },
        ]},
        "State":"Completed"
    }
}

ListScans.Request

Client request for the ListScans task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListScans"

ListScans.Response

Server response for the ListScans task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListScans"
Output Descriptors.Project.Group repeated The list of scans in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListSettings

ListSettings

Get scanner settings.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListSettings"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListSettings",
        "Output":{
            "camera":{
                "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
                "autoExposure":{"default":false,"value":false},
                "digitalGain":{"default":256,"max":65536,"min":256,"value":320},
                "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
             },
            "projector":{
                "brightness":{"default":0.5,"max":1.0,"min":0.0,"value":0.800000011920929},
                "on":{"default":false,"value":true}
            },
            "turntable":{
                "steps":{"default":8,"max":24,"min":1,"value":3},
                "sweep":{"default":360,"max":360,"min":5,"value":90},
                "use":{"default":true,"value":true}
             },
            "capture":{
                "quality":{"default":"Medium","value":"Medium"},
                "texture":{"default":true,"value":true}
            },
            "i18n":{
                "language":{"default":"en","value":"en"}
            },
            "style":{
                "theme":{"default":"Dark","value":"Dark"}
            },
            "viewer":{
                "textureOpacity":{"default":0.5,"max":1.0,"min":0.0,"value":1.0}
            }
        },
        "State":"Completed"
    }
}

ListSettings.Request

Client request for the ListSettings task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListSettings"

ListSettings.Response

Server response for the ListSettings task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListSettings"
Output Descriptors.Settings.Scanner optional The scanner settings descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ListWifi

ListWifi

List available wifi networks.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ListWifi"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ListWifi",
        "Output":{
          "networks":[
              {"ssid":"Network1","isActive":true,"isPublic":false,"quality":90},
              {"ssid":"Network2","isActive":true,"isPublic":true,"quality":50},
              {"ssid":"Network3","isActive":true,"isPublic":true,"quality":75}
          ],
          "ssid":"Network1"
      },
        "State":"Completed"
    }
}

ListWifi.Request

Client request for the ListWifi task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ListWifi"

ListWifi.Response

Server response for the ListWifi task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ListWifi"
Output Descriptors.Wifi optional The wifi descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/Merge

Merge

Merge two or more scan groups.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"Merge",
        "Input":{
            "selection":{"mode":"visible"},
            "remesh":{
                "method": "FastTriangles",
                "quality": "Medium"
            },
            "simplify":{"triangleCount": 20000 }
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"Merge",
        "Input":{
            "selection":{"mode":"visible"},
            "remesh":{
                "method": "FastTriangles",
                "quality": "Medium"
            },
            "simplify":{"triangleCount": 20000 }
        },
        "Output":{
            "meshes":[
                {
                    "name":"Combined",
                    "positions":237757,
                    "normals":237757,
                    "triangles":459622,
                    "size":11221632
                },
                {
                    "name":"Remeshed",
                    "positions":34311,
                    "normals":0,
                    "triangles":29738,
                    "size":945540
                },
                {
                    "name":"Simplified",
                    "positions":32415,
                    "normals":0,
                    "triangles":20000,
                    "size":628980
                }
            ],
            "scans":3,
            "textures":3
        },
        "State":"Completed"
    }
}

Merge.Request

Client request for the Merge task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "Merge"
Input Settings.Merge The merge settings.

Merge.Response

Server response for the Merge task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "Merge"
Input Settings.Merge The requested merge settings.
Output Descriptors.Merge The merge descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/MergeData

MergeData

Download the raw scan data for the current merge process.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"MergeData",
        "Input":{
            "index":-1,
            "buffers":["All"]
        }
    }
}

> Vertex position buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":1558188,
        "Descriptor":{
            "components":[{
                "type":"Position"
                "size":3,
                "offset":0,
                "normalized":false,
            }],
            "stride":3
        },
        "Task":{
            "Index":1,
            "Type":"MergeData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex position binary data transfer from server [1558188 bytes].

> Vertex normal buffer message from server.

{
    "Buffer":{
        "Index":1,
        "Size":1558188,
        "Descriptor":{
            "components":[{
                "type":"Normal"
                "size":3,
                "offset":0,
                "normalized":false,
            }],
            "stride":3
        },
        "Task":{
            "Index":1,
            "Type":"MergeData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex normal binary data transfer from server [1558188 bytes].

> Vertex texture coordinate buffer message from server.

{
    "Buffer":{
        "Index":2,
        "Size":1038792,
        "Descriptor":{
            "components":[{
                "type":"UV"
                "size":2,
                "offset":0,
                "normalized":false,
            }],
            "stride":2
        },
        "Task":{
            "Index":1,
            "Type":"MergeData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex texture coordinate binary data transfer from server [1038792 bytes].

> Texture image buffer message from server.

{
    "Buffer":{
        "Index":3,
        "Size":3504494,
        "Descriptor":{
            "components":[{
                "type":"Texture"
                "size":0,
                "offset":0,
                "normalized":false,
            }],
            "stride":0
        },
        "Task":{
            "Index":1,
            "Type":"MergeData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Texture binary data transfer from server [3504494 bytes].

> Triangle index buffer message from server.

{
    "Buffer":{
        "Index":4,
        "Size":1996356,
        "Descriptor":{
            "components":[{
                "type":"Triangle"
                "size":1,
                "offset":0,
                "normalized":false,
            }],
            "stride":1
        },
        "Task":{
            "Index":1,
            "Type":"MergeData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Triangle index binary data transfer from server [1996356 bytes].

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"MergeData"
        "Input":{"index":-1,"buffers":["All"]},
        "Output":{
            "buffers":[
                {"components":[{"normalized":false,"offset":0,"size":3,"type":"Position"}],"stride":3},
                {"components":[{"normalized":false,"offset":0,"size":3,"type":"Normal"}],"stride":3},
                {"components":[{"normalized":false,"offset":0,"size":2,"type":"UV"}],"stride":2},
                {"components":[{"normalized":false,"offset":0,"size":0,"type":"Texture"}],"stride":0},
                {"components":[{"normalized":false,"offset":0,"size":1,"type":"Triangle"}],"stride":1}
            ],
            "index":1,
            "name":"Scan-1"
        },
        "State":"Completed"
    }
}

MergeData.Buffer

Server buffer message for the MergeData task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested MergeData task.
Descriptor Descriptors.ScanData.Buffer The scan data buffer descriptor.

MergeData.Request

Client request for the MergeData task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "MergeData"
Input Settings.ScanData Requested scan data.

MergeData.Response

Server response for the MergeData task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "MergeData"
Input Settings.ScanData The scan data requested by the client.
Output Descriptors.ScanData The scan data sent from the server.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/MoveGroup

MoveGroup

Move a scan group.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"MoveGroup",
        "Input":[1,2,0]
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"MoveGroup",
        "Input":[1,2,0],
        "Output":{
            "groups":[{
                "index":2,
                "name":"Group 2",
                "groups":[{
                    "index":1,
                    "name":"Group 1"
                }]
            }],
        },
        "State":"Completed"
    }
}

MoveGroup.Request

Client request for the MoveGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "MoveGroup"
Input int32 repeated The requested source and destination move indices. An Array of group indexes where 1. The first is the index of the source group: the group to be moved. 2. The second is the index of the parent group: the group into which the source group is moved. 3. (Optional) The third is the zero-based order in which the source group is placed the other children of the parent group. Use 0 to insert the source group at the beginning of the parent group's children. If omitted, the source group is inserted at the end of the parent group's children.

MoveGroup.Response

Server response for the MoveGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "MoveGroup"
Input int32 repeated The requested source and destination move indices.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/NewGroup

NewGroup

Create a new scan group.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"NewGroup",
        "Input":{
            "parentIndex":0,
            "baseName":"Group"
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"NewGroup",
        "Input":{
            "parentIndex":0,
            "baseName":"Group"
        },
        "Output":{
            "groups":[
                {
                    "index":1,
                    "name":"Group 1"
                }
            ]
        },
        "State":"Completed"
    }
}

NewGroup.Request

Client request for the NewGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "NewGroup"
Input Settings.NewGroup optional The requested new group settings.

NewGroup.Response

Server response for the NewGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "NewGroup"
Input Settings.NewGroup optional The requested new group settings.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/NewProject

NewProject

Create a new project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"NewProject",
        "Input":"New Project Name"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"NewProject",
        "Input":{
            "name":"New Project Name"
        },
        "Output":{
            "index":5,
            "name":"New Project Name"
        }
        "State":"Completed"
    }
}

NewProject.Request

Client request for the NewProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "NewProject"
Input string optional Optional new project name.

NewProject.Response

Server response for the NewProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "NewProject"
Input Settings.Project optional Requested new project name.
Output Descriptors.Project optional The new project descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/NewScan

NewScan

Capture a new scan.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"NewScan"
        "Input":{
            "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
            "capture":{"quality":"Medium","texture":true},
            "projector":{"brightness":0.8}
        },
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"NewScan"
        "Input":{
            "camera":{"exposure":18000,"analogGain":256,"digitalGain":256},
            "capture":{"quality":"Medium","texture":true},
            "projector":{"brightness":0.8}
        },
        "Output":{
            "groups":[{
                "color":[0.8,0.5,0.6,1.0],
                "index":1,
                "name":"Scan-1",
                "scan":1,
                "rotation":[0.2,0.8,-0.1],
                "translation":[-275,-32,-134],
                "visible":true
            }],
        },
        "State":"Completed"
    }
}

NewScan.Request

Client request for the NewScan task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "NewScan"
Input Settings.Scan optional Scan settings.

NewScan.Response

Server response for the NewScan task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "NewScan"
Input Settings.Scan optional Requested scan settings.
Output Descriptors.Project.Group optional Project group descriptor with the updated list of scans.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/OpenProject

OpenProject

Create a new project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"OpenProject",
        "Input":5
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"OpenProject",
        "Input":5,
        "Output":{
            "index":5,
            "name":"Project 5"
        }
        "State":"Completed"
    }
}

OpenProject.Request

Client request for the OpenProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "OpenProject"
Input int32 The index of the project to open. Project indices can be obtained from the ListProjects task.

OpenProject.Response

Server response for the OpenProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "OpenProject"
Input int32 The index of the project requested to open.
Output Descriptors.Project optional The open project descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/PopSettings

PopSettings

Pop and restore scanner settings from the stack and optionally apply the popped settings.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"PopSettings",
        "Input":true
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"PopSettings",
        "Input":true,
        "Output":{
            "camera":{
                "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
                "autoExposure":{"default":false,"value":false},
                "digitalGain":{"default":256,"max":65536,"min":256,"value":320},
                "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
             },
            "projector":{
                "brightness":{"default":0.5,"max":1.0,"min":0.0,"value":0.800000011920929},
                "on":{"default":false,"value":true}
            },
            "turntable":{
                "steps":{"default":8,"max":24,"min":1,"value":3},
                "sweep":{"default":360,"max":360,"min":5,"value":90},
                "use":{"default":true,"value":true}
             },
            "capture":{
                "quality":{"default":"Medium","value":"Medium"},
                "texture":{"default":true,"value":true}
            },
            "i18n":{
                "language":{"default":"en","value":"en"}
            },
            "style":{
                "theme":{"default":"Dark","value":"Dark"}
            },
            "viewer":{
                "textureOpacity":{"default":0.5,"max":1.0,"min":0.0,"value":1.0}
            }
        },
        "State":"Completed"
    }
}

PopSettings.Request

Client request for the PopSettings task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "PopSettings"
Input bool optional Apply the popped settings. If unspecified popped settings are not applied.

PopSettings.Response

Server response for the PopSettings task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "PopSettings"
Input bool optional Request to apply the popped settings.
Output Descriptors.Settings.Scanner optional The scanner settings descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/PushSettings

PushSettings

Push the current scanner settings to a stack so they can be restored with PopSettings.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"PushSettings"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"PushSettings",
        "Output":{
            "camera":{
                "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
                "autoExposure":{"default":false,"value":false},
                "digitalGain":{"default":256,"max":65536,"min":256,"value":320},
                "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
             },
            "projector":{
                "brightness":{"default":0.5,"max":1.0,"min":0.0,"value":0.800000011920929},
                "on":{"default":false,"value":true}
            },
            "turntable":{
                "steps":{"default":8,"max":24,"min":1,"value":3},
                "sweep":{"default":360,"max":360,"min":5,"value":90},
                "use":{"default":true,"value":true}
             },
            "capture":{
                "quality":{"default":"Medium","value":"Medium"},
                "texture":{"default":true,"value":true}
            },
            "i18n":{
                "language":{"default":"en","value":"en"}
            },
            "style":{
                "theme":{"default":"Dark","value":"Dark"}
            },
            "viewer":{
                "textureOpacity":{"default":0.5,"max":1.0,"min":0.0,"value":1.0}
            }
        },
        "State":"Completed"
    }
}

PushSettings.Request

Client request for the PushSettings task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "PushSettings"

PushSettings.Response

Server response for the PushSettings task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "PushSettings"
Output Descriptors.Settings.Scanner optional The scanner settings descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/Reboot

Reboot

Reboot the scanner.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"Reboot"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"Reboot"
        "State":"Completed"
    }
}

Reboot.Request

Client request for the Reboot task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "Reboot"

Reboot.Response

Server response for the Reboot task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "Reboot"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/RemoveGroups

RemoveGroups

Remove selected scan groups.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"RemoveGroups",
        "Input":[1,2]
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"RemoveGroups",
        "Input":[1,2],
        "Output":{"groups":[]},
        "State":"Completed"
    }
}

RemoveGroups.Request

Client request for the RemoveGroups task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "RemoveGroups"
Input int32 repeated The list of indices of the scan groups to remove.

RemoveGroups.Response

Server response for the RemoveGroups task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "RemoveGroups"
Input int32 repeated The requested of indices of the scan groups to remove.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/RemoveProjects

RemoveProjects

Remove selected projects.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"RemoveProjects",
        "Input":[1,3,6]  
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"RemoveProjects",
        "Input":[1,3,6],
        "Output":[
            {"index":2,"modified":[2024,5,12,11,23,17],"name":"Project 2","size":35409834},
            {"index":4,"modified":[2024,5,12,11,2,37],"name":"Project 4","size":175025367},
            {"index":5,"modified":[2024,5,6,17,15,53],"name":"Project 5","size":24314083}
        ],
        "State":"Completed"
    }
}

RemoveProjects.Request

Client request for the RemoveProjects task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "RemoveProjects"
Input int32 repeated The list of indices of the projects to remove.

RemoveProjects.Response

Server response for the RemoveProjects task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "RemoveProjects"
Input int32 repeated The list of indices of the requested projects to remove.
Output Descriptors.Project.Brief optional Brief descriptors of the remaining projects.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/RestoreFactoryCalibration

RestoreFactoryCalibration

Restore factory calibration.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"RestoreFactoryCalibration"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"RestoreFactoryCalibration",
        "State":"Completed"
    }
}

RestoreFactoryCalibration.Request

Client request for the RestoreFactoryCalibration task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "RestoreFactoryCalibration"

RestoreFactoryCalibration.Response

Server response for the RestoreFactoryCalibration task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "RestoreFactoryCalibration"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/RotateTurntable

RotateTurntable

Rotate the turntable.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"RotateTurntable",
        "Input":15
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"RotateTurntable",
        "Input":15,
        "State":"Completed"
    }
}

RotateTurntable.Request

Client request for the RotateTurntable task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "RotateTurntable"
Input int32 The rotation angle in degrees.

RotateTurntable.Response

Server response for the RotateTurntable task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "RotateTurntable"
Input int32 The requested rotation angle in degrees.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/ScanData

ScanData

Download the raw scan data for a scan in the current open project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"ScanData",
        "Input":{
            "index":1,
            "buffers":["All"]
        }
    }
}

> Vertex position buffer message from server.

{
    "Buffer":{
        "Index":0,
        "Size":1558188,
        "Descriptor":{
            "components":[{
                "type":"Position"
                "size":3,
                "offset":0,
                "normalized":false,
            }],
            "stride":3
        },
        "Task":{
            "Index":1,
            "Type":"ScanData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex position binary data transfer from server [1558188 bytes].

> Vertex normal buffer message from server.

{
    "Buffer":{
        "Index":1,
        "Size":1558188,
        "Descriptor":{
            "components":[{
                "type":"Normal"
                "size":3,
                "offset":0,
                "normalized":false,
            }],
            "stride":3
        },
        "Task":{
            "Index":1,
            "Type":"ScanData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex normal binary data transfer from server [1558188 bytes].

> Vertex texture coordinate buffer message from server.

{
    "Buffer":{
        "Index":2,
        "Size":1038792,
        "Descriptor":{
            "components":[{
                "type":"UV"
                "size":2,
                "offset":0,
                "normalized":false,
            }],
            "stride":2
        },
        "Task":{
            "Index":1,
            "Type":"ScanData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Vertex texture coordinate binary data transfer from server [1038792 bytes].

> Texture image buffer message from server.

{
    "Buffer":{
        "Index":3,
        "Size":3504494,
        "Descriptor":{
            "components":[{
                "type":"Texture"
                "size":0,
                "offset":0,
                "normalized":false,
            }],
            "stride":0
        },
        "Task":{
            "Index":1,
            "Type":"ScanData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Texture binary data transfer from server [3504494 bytes].

> Triangle index buffer message from server.

{
    "Buffer":{
        "Index":4,
        "Size":1996356,
        "Descriptor":{
            "components":[{
                "type":"Triangle"
                "size":1,
                "offset":0,
                "normalized":false,
            }],
            "stride":1
        },
        "Task":{
            "Index":1,
            "Type":"ScanData",
            "Input":{
                "index":1,
                "buffers":["All"]
            }
        }
    }
}

> Triangle index binary data transfer from server [1996356 bytes].

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"ScanData",
        "Input":{"buffers":["All"],"index":1},
        "Output":{
            "buffers":[
                {"components":[{"normalized":false,"offset":0,"size":3,"type":"Position"}],"stride":3},
                {"components":[{"normalized":false,"offset":0,"size":3,"type":"Normal"}],"stride":3},
                {"components":[{"normalized":false,"offset":0,"size":2,"type":"UV"}],"stride":2},
                {"components":[{"normalized":false,"offset":0,"size":0,"type":"Texture"}],"stride":0},
                {"components":[{"normalized":false,"offset":0,"size":1,"type":"Triangle"}],"stride":1}
            ],
            "index":1,
            "name":"Scan-1"
        },
        "State":"Completed"
    }
}

ScanData.Buffer

Server buffer message for the ScanData task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested ScanData task.
Descriptor Descriptors.ScanData.Buffer The scan data buffer descriptor.

ScanData.Request

Client request for the ScanData task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "ScanData"
Input Settings.ScanData Requested scan data.

ScanData.Response

Server response for the ScanData task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "ScanData"
Input Settings.ScanData The scan data requested by the client.
Output Descriptors.ScanData The scan data sent from the server.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SetCameras

SetCameras

Apply camera settings to one or both cameras.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"SetCameras",
        "Input":{
            "analogGain":256,
            "digitalGain":128,
            "exposure":18000
        },
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"SetCameras"
        "Input":{
            "analogGain":256,
            "digitalGain":512,
            "exposure":18000
        },
        "Output":{
            "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
            "digitalGain":{"default":256,"max":65536,"min":256,"value":512},
            "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
        },
        "State":"Completed"
    }
}

SetCameras.Request

Client request for the SetCameras task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SetCameras"
Input Settings.Camera optional Camera settings.

SetCameras.Response

Server response for the SetCameras task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SetCameras"
Input Settings.Camera optional Requested camera settings.
Output Descriptors.Settings.Camera optional Actual camera settings after applying the requested settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SetGroup

SetGroup

Set scan group properties.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"SetGroup",
        "Input":{
            "index":2, 
            "name":"Amazing Scan"
            "color":[1,0,0,1],
            "rotation":[0,3.14,0],
            "translation":[0,10,25]
        }   
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"SetGroup",
        "Input":{
            "index":2, 
            "name":"Amazing Scan"
            "color":[1,0,0,1],
            "rotation":[0,3.14,0],
            "translation":[0,10,25]
        }   
        "Output":{
            "groups":[
                {
                    "index":1,
                    "scan":1,
                    "name":"Scan-1",
                    "color":[0.75,0.5,0.2,1.0],
                    "rotation":[0.03,0.1,-0.01],
                    "translation":[-101,67,-561],
                    "visible":true
                },
                {
                    "index":2,
                    "scan":2,
                    "name":"Amazing Scan",
                    "color":[1,0,0,1],
                    "rotation":[0,3.14,0],
                    "translation":[0,10,25],
                    "visible":true
                },
                {
                    "index":3,
                    "scan":3,
                    "name":"Scan-3",
                    "color":[0.6,0.8,0.9,1.0],
                    "visible":true
                }
            ]
        },
        "State":"Completed"
    }
}

SetGroup.Request

Client request for the SetGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SetGroup"
Input Settings.Group The requested group settings.

SetGroup.Response

Server response for the SetGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SetGroup"
Input Settings.Group The requested group settings.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SetProject

SetProject

Apply settings to the current open project.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"SetProject",
        "Input":{
            "name":"My Project"
        },
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"SetProject",
        "Input":{
            "name":"My Project"
        },
        "Output":{
            "index":5,
            "name":"My Project",
            "groups":[{
                "color":[0.8,0.5,0.6,1.0],
                "index":1,
                "name":"Scan-1",
                "scan":1,
                "rotation":[0.2,0.8,-0.1],
                "translation":[-275,-32,-134],
                "visible":true
            }],
        }
        "State":"Completed"
    }
}

SetProject.Request

Client request for the SetProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SetProject"
Input Settings.Project optional Project settings.

SetProject.Response

Server response for the SetProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SetProject"
Input Settings.Project optional Requested project settings.
Output Descriptors.Project optional Actual project settings after applying the requested settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SetProjector

SetProjector

Apply projector settings.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"SetProjector"
        "Input":{
            "on":true,
            "brightness":0.75,
            "color":[1.0, 1.0, 1.0]
        },
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"SetProjector"
        "Input":{
            "on":true,
            "brightness":0.75,
            "color":[1.0, 1.0, 1.0]
        },
        "Output":{
            "on":{"default":false,"value":true},
            "brightness":{"default":0.5,"max":1.0,"min":0.0,"value":0.75}
        },
        "State":"Completed"
    }
}

SetProjector.Request

Client request for the SetProjector task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SetProjector"
Input Settings.Projector optional Projector settings.

SetProjector.Response

Server response for the SetProjector task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SetProjector"
Input Settings.Projector optional Requested projector settings.
Output Descriptors.Settings.Projector optional Actual projector settings after applying the requested settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/Shutdown

Shutdown

Shutdown the scanner.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"Shutdown"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"Shutdown"
        "State":"Completed"
    }
}

Shutdown.Request

Client request for the Shutdown task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "Shutdown"

Shutdown.Response

Server response for the Shutdown task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "Shutdown"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SplitGroup

SplitGroup

Split a scan group (ie. move its subgroups to its parent group).

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"SplitGroup",
        "Input":0
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"SplitGroup",
        "Input":0,
        "Output":{
            "groups":[
                {
                    "index":1,
                    "name":"Group 1",
                },
                {
                    "index":2,
                    "name":"Group 2"
                }
            ]
        },
        "State":"Completed"
    }
}

SplitGroup.Request

Client request for the SplitGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SplitGroup"
Input int32 The index of the group to split.

SplitGroup.Response

Server response for the SplitGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SplitGroup"
Input int32 The requested index of the group to split.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/StartVideo

StartVideo

Start the video stream.

The video frames are sent as task buffers associated with the reserved video task index -1. The left and right camera frames are sent in buffer 0 and 1, respectively.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"StartVideo"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"StartVideo",
        "Output":{
            "codec":"JPEG",
            "format":"YUV420",
            "width":510,
            "height":380
        },
        "State":"Completed"
    }
}

StartVideo.Request

Client request for the StartVideo task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "StartVideo"

StartVideo.Response

Server response for the StartVideo task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "StartVideo"
Output Settings.Video optional The video settings.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/StopVideo

StopVideo

Stop the video stream.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"StopVideo"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"StopVideo",
        "State":"Completed"
    }
}

StopVideo.Request

Client request for the StopVideo task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "StopVideo"

StopVideo.Response

Server response for the StopVideo task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "StopVideo"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/SystemInfo

SystemInfo

Get system information including the serial number, disk space and installed and available software versions.

Request example:

{
    "Task":{
        "Index":1,
        "Type":"SystemInfo",
        "Input":{
            "installed":["server","frontend"],
            "available":["server","frontend"]
        }
    }
}

Response example:

{
    "Task":{
        "Index":1,
        "Type":"SystemInfo"
        "Input":{
            "installed":["server","frontend"],
            "available":["server","frontend"]
        }
        "Output":{
            "serialNumber":"1000000012345678",
            "diskSpace":{"available":8523210752,"capacity":15082610688},
            "software:{
                "installed":[
                    {
                        "name":"server",
                        "version":{
                            "major":2,
                            "minor":21,
                            "patch":119,
                            "string":"2.21.119"
                        }
                    },
                    {
                        "name":"frontend",
                        "version":{
                            "major":2,
                            "minor":14,
                            "patch":39,
                            "string":"2.14.39"
                        }
                    }
                },
            ]
        },
        "State":"Completed"
    }
}

SystemInfo.Request

Client request for the SystemInfo task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "SystemInfo"
Input Settings.Software optional Software settings.

SystemInfo.Response

Server response for the SystemInfo task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "SystemInfo"
Input Settings.Software optional The requested software settings.
Output Descriptors.System The system descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/TransformGroup

TransformGroup

Apply a rigid transformation to a group.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"TransformGroup",
        "Input":{
            "index":1,
            "rotation":[0.5, 1.0, 1.5],
            "translation":[10, 20, 30]
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"TransformGroup",
        "Input":{
            "index":1,
            "rotation":[0.5, 1.0, 1.5],
            "translation":[10, 20, 30]
        },
        "Output":{
            "groups":[
                {
                    "index":1,
                    "name":"Group 1",
                    "rotation":[0.5, 1.0, 1.5],
                    "translation":[10, 20, 30]
                }
            ]
        },
        "State":"Completed"
    }
}

TransformGroup.Request

Client request for the TransformGroup task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "TransformGroup"
Input Settings.Group The group settings containing the requested rotation and translation.

TransformGroup.Response

Server response for the TransformGroup task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "TransformGroup"
Input Settings.Group The group settings containing the requested rotation and translation.
Output Descriptors.Project.Group The root scan group in the current open project.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/TurntableCalibration

TurntableCalibration

Get the turntable calibration descriptor.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"TurntableCalibration"
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"TurntableCalibration",
        "Output":{
            "date":[2024,4,27,16,57,35],
            "quality":"Excellent",
            "focus":[300,320]
        },
        "State":"Completed"
    }
}

TurntableCalibration.Request

Client request for the TurntableCalibration task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "TurntableCalibration"

TurntableCalibration.Response

Server response for the TurntableCalibration task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "TurntableCalibration"
Output Descriptors.Calibration.Turntable optional The turntable calibration descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/UpdateSettings

UpdateSettings

Update scanner settings.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"UpdateSettings",
        "Input":{
            "camera":{
                "analogGain":256,
                "digitalGain":320,
                "exposure":18000
            } 
        }
    }
}

> Response example:

{
    "Task":{
        "Index":1,
        "Type":"UpdateSettings",
        "Input":{
            "camera":{
                "analogGain":256,
                "digitalGain":320,
                "exposure":18000
            } 
        },
        "Output":{
            "camera":{
                "analogGain":{"default":512.0,"max":1024.0,"min":256.0,"value":256.0},
                "autoExposure":{"default":false,"value":false},
                "digitalGain":{"default":256,"max":65536,"min":256,"value":320},
                "exposure":{"default":27000,"max":90000,"min":9000,"value":18000},
             },
            "projector":{
                "brightness":{"default":0.5,"max":1.0,"min":0.0,"value":0.800000011920929},
                "on":{"default":false,"value":true}
            },
            "turntable":{
                "steps":{"default":8,"max":24,"min":1,"value":3},
                "sweep":{"default":360,"max":360,"min":5,"value":90},
                "use":{"default":true,"value":true}
             },
            "capture":{
                "quality":{"default":"Medium","value":"Medium"},
                "texture":{"default":true,"value":true}
            },
            "i18n":{
                "language":{"default":"en","value":"en"}
            },
            "style":{
                "theme":{"default":"Dark","value":"Dark"}
            },
            "viewer":{
                "textureOpacity":{"default":0.5,"max":1.0,"min":0.0,"value":1.0}
            }
        },
        "State":"Completed"
    }
}

UpdateSettings.Request

Client request for the UpdateSettings task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "UpdateSettings"
Input Settings.Scanner Scanner settings.

UpdateSettings.Response

Server response for the UpdateSettings task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "UpdateSettings"
Input Settings.Scanner The requested scanner settings.
Output Descriptors.Settings.Scanner optional The scanner settings descriptor.
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Tasks/UploadProject

UploadProject

Upload a project to the scanner. The project must be archived in a ZIP file.

> Request example:

{
    "Task":{
        "Index":1,
        "Type":"UploadProject"
    }
}

> Buffer message from client.

{
    "Buffer":{
        "Index":0,
        "Size":15682096,
        "Task":{
            "Index":1,
            "Type":"UploadProject"
        }
    }
}

> Binary data transfer from client: The project zip file [15682096 bytes]. > Response example:

{
    "Task":{
        "Index":1,
        "Type":"UploadProject"
        "State":"Completed"
    }
}

UploadProject.Buffer

Client buffer message for the UploadProject task.

Field Type Label Description
Index int32 The zero-based index identifying the data buffer.
Size uint64 The size of the incoming data buffer in bytes.
Task Task The requested UploadProject task.

UploadProject.Request

Client request for the UploadProject task.

Field Type Label Description
Index int32 A unique identifier generated by the client.
Type string "UploadProject"

UploadProject.Response

Server response for the UploadProject task.

Field Type Label Description
Index int32 The unique identifier generated by the client.
Type string "UploadProject"
State TaskState optional The current state of the task.
Error string optional A string describing the error if the task has failed.

Top

MF/V3/Three

Three

Three scanner API.

Method Name Request Type Response Type Description
ListNetworkInterfaces ListNetworkInterfaces.Request ListNetworkInterfaces.Response List available wifi networks.
ListWifi ListWifi.Request ListWifi.Response List available wifi networks.
ConnectWifi ConnectWifi.Request ConnectWifi.Response Connect to a wifi network.
ForgetWifi ForgetWifi.Request ForgetWifi.Response Forget all wifi connections.
ListSettings ListSettings.Request ListSettings.Response Get scanner settings.
PushSettings PushSettings.Request PushSettings.Response Push the current scanner settings to the settings stack.
PopSettings PopSettings.Request PopSettings.Response Pop and restore scanner settings from the settings stack.
UpdateSettings UpdateSettings.Request UpdateSettings.Response Update scanner settings.
ListProjects ListProjects.Request ListProjects.Response List all projects.
DownloadProject DownloadProject.Request DownloadProject.Response Download a project from the scanner.
UploadProject UploadProject.Request UploadProject.Response Upload a project to the scanner.
NewProject NewProject.Request NewProject.Response Create a new project.
OpenProject OpenProject.Request OpenProject.Response Open an existing project.
CloseProject CloseProject.Request CloseProject.Response Close the current open project.
RemoveProjects RemoveProjects.Request RemoveProjects.Response Remove selected projects.
ListGroups ListGroups.Request ListGroups.Response List the scan groups in the current open project.
ListScans ListScans.Request ListScans.Response List the scans in the current open project.
ScanData ScanData.Request ScanData.Response Download the raw scan data for a scan in the current open project.
SetProject SetProject.Request SetProject.Response Apply settings to the current open project.
SetGroup SetGroup.Request SetGroup.Response Set scan group properties.
NewGroup NewGroup.Request NewGroup.Response Create a new scan group.
MoveGroup MoveGroup.Request MoveGroup.Response Move a scan group.
FlattenGroup FlattenGroup.Request FlattenGroup.Response Flatten a scan group such that it only consists of single scans.
SplitGroup SplitGroup.Request SplitGroup.Response Split a scan group (ie. move its subgroups to its parent group).
TransformGroup TransformGroup.Request TransformGroup.Response Apply a rigid transformation to a group.
RemoveGroups RemoveGroups.Request RemoveGroups.Response Remove selected scan groups.
BoundingBox BoundingBox.Request BoundingBox.Response Get the bounding box of a set of scan groups.
Align Align.Request Align.Response Align two scan groups.
Merge Merge.Request Merge.Response Merge two or more scan groups.
MergeData MergeData.Request MergeData.Response Download the raw scan data for the current merge process.
AddMergeToProject AddMergeToProject.Request AddMergeToProject.Response Add a merged scan to the current project.
ListExportFormats ListExportFormats.Request ListExportFormats.Response List all export formats.
Export Export.Request Export.Response Export a group of scans.
ExportMerge ExportMerge.Request ExportMerge.Response Export a merged scan.
ExportLogs ExportLogs.Request ExportLogs.Response Export scanner logs.
HasCameras HasCameras.Request HasCameras.Response Check if the scanner has working cameras.
HasProjector HasProjector.Request HasProjector.Response Check if the scanner has a working projector.
HasTurntable HasTurntable.Request HasTurntable.Response Check if the scanner is connected to a working turntable.
SystemInfo SystemInfo.Request SystemInfo.Response Get system information.
CameraCalibration CameraCalibration.Request CameraCalibration.Response Get the camera calibration descriptor.
TurntableCalibration TurntableCalibration.Request TurntableCalibration.Response Get the turntable calibration descriptor.
CalibrationCaptureTargets CalibrationCaptureTargets.Request CalibrationCaptureTargets.Response Get the calibration capture target for each camera calibration capture.
CalibrateCameras CalibrateCameras.Request CalibrateCameras.Response Calibrate the cameras.
CalibrateTurntable CalibrateTurntable.Request CalibrateTurntable.Response Calibrate the turntable.
DetectCalibrationCard DetectCalibrationCard.Request DetectCalibrationCard.Response Detect the calibration card on one or both cameras.
RestoreFactoryCalibration RestoreFactoryCalibration.Request RestoreFactoryCalibration.Response Restore factory calibration.
StartVideo StartVideo.Request StartVideo.Response Start the video stream.
StopVideo StopVideo.Request StopVideo.Response Stop the video stream.
SetCameras SetCameras.Request SetCameras.Response Apply camera settings to one or both cameras.
SetProjector SetProjector.Request SetProjector.Response Apply projector settings.
AutoFocus AutoFocus.Request AutoFocus.Response Auto focus one or both cameras.
RotateTurntable RotateTurntable.Request RotateTurntable.Response Rotate the turntable.
NewScan NewScan.Request NewScan.Response Capture a new scan.
DepthMap DepthMap.Request DepthMap.Response Capture a depth map.
Reboot Reboot.Request Reboot.Response Reboot the scanner.
Shutdown Shutdown.Request Shutdown.Response Shutdown the scanner.

Scalar Value Types

Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)
Clone this wiki locally