-
Notifications
You must be signed in to change notification settings - Fork 0
THREE ‐ API First Look
Welcome to a very cursory look at our public API for controlling the Matter and Form THREE scanner. This is NOT the proper documentation for the API, but merely a sneak preview of the calls that will be available to you on launch. Proper documentation will be provided on our first official release.
The THREE comes with a backend server that runs on boot. This server is able to send and receive messages via a websocket protocol. Everything the THREE does, except for the GUI, is available through the server. All the calls our frontend system makes are available to you for your personal projects.
Using the websocket server, you can build your own integration with automation systems like Home Assistant, or integrate with robotic arms. Take stereo images with the dual cameras or project graphics through the built in projector. Or go crazy and make an entirely new front end 3D scanning system, designed by you.
If you’re not familiar with websockets, you can read about it here. Or search for websocket libraries for whatever coding language interests you.
To connect to the running websocket server, use the following url: ws://matterandform.local:8081, or use the ip of the device directly: ws://192.168.XXX.XXX:8081.
Please remember that the THREE is a local network device, and will only respond on your local network.
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. Here is an initial look at the calls available at the moment.
All requests made to the server are queued as tasks. A list of the tasks with their description is below.
| Name | Description |
|---|---|
| StillImage | Get a still image from each camera. |
| StreamImage | Get a stream image from each camera. |
| DiskSpace | Get available and total disk space. |
| SoftwareVersionInstalled | Installed Software version. |
| SoftwareVersionAvailable | Available Software version. |
| SoftwareUpdate | Update software to a new version. |
| ListSettings | Get scanner settings. |
| PushSettings | Push the current scanner settings to a stack so they can be restored with PopSettings. |
| PopSettings | Pop and restore scanner settings from the stack and optionally apply the popped settings. |
| UpdateSettings | Update scanner settings. |
| CameraCalibration | Get the camera calibration descriptor for the current focus values. |
| TurntableCalibration | Get the turntable calibration descriptor. |
| CalibrationCaptureTargets | Get the camera calibration capture targets. |
| CalibrateCameras | Calibrate the cameras. |
| CalibrateTurntable | Calibrate the turntable. |
| StartVideo | Start the video stream. |
| StopVideo | Stop the video stream. |
| SetCameras | Apply settings to one or both cameras. (See Example) |
| SetProjector | Apply projector settings. |
| HasCameras | Check if both cameras are operational. |
| HasTurntable | Check if the server can connect to a turntable. |
| AutoFocus | Auto focus the cameras. |
| RotateTurntable | Rotate the turntable. |
| DetectCalibrationCard | Detect the calibration card. |
| ListProjects | List the projects in the workspace. |
| SetProject | Set project properties. |
| NewProject | Create a new project. |
| OpenProject | Open an existing project. |
| CloseProject | Close an open project. |
| RemoveProjects | Remove selected projects from the workspace. |
| ClearProjectActions | Clear the project undo and redo actions. |
| UndoProjectActions | Undo a number of project actions. |
| RedoProjectActions | Redo a number of project actions. |
| ListProjectActions | List the available project undo and redo actions. |
| ListScans | List the scans in the current project. |
| ScanData | Get geometry data for a selected scan. |
| NewScan | Capture and process a new scan. |
| ListGroups | List the groups in the current project. |
| SetGroup | Set scan group properties. |
| NewGroup | Create a scan group. |
| MoveGroup | Move a scan group. |
| FlattenGroup | Flatten a scan group such that it only consists of single scans. |
| SplitGroup | Split a scan group (ie. move its subgroups to its parent group). |
| RemoveGroups | Remove a scan group. |
| TransformGroup | Apply a rigid transformation to a group. |
| Align | Align two scan groups. |
| Merge | Merge two or more scan groups. |
| MergeData | Get geometry data for the current merged scan. |
| AddMergeToProject | Add a merged scan to the current project. |
| Export | Export a group of scans. |
| ExportMerge | Export a merged scan. |
| ListWifi | List the available wifi networks. |
| ConnectWifi | Connect to a specific wifi network. |
| ForgetWifi | Forget all wifi networks. |
| ListNetworkInterfaces | List the current network interfaces. |
| DepthMap | Create a depth map. |
| RemoveVertices | Remove Vertices. |
| Reboot | Reboot the scanner. |
| Shutdown | Shutdown the scanner. |
Here is a simple example of the formatting of a task that is sent to change the properties on a camera. The Index property is used for your application to keep track of calls and responses. The Input property contains the individual settings or attributes for your request, in this case camera settings. The Type property defines the type of request.
Set Camera Request:
{
"Task": {
"Index": 1,
"Input": {
"analogGain": 450.0,
"digitalGain": 128,
"exposure": 30000,
"focusMode": "Standard"
},
"Type": "SetCameras"
}
}Here is an example of the response given by the server. The Input property mimics the Input property of the request sent. The output property will give additional info on the settings.
Set Camera Request Reply:
{
"Task": {
"Index": 1,
"Input": {
"analogGain": 450.0,
"digitalGain": 128,
"exposure": 30000,
"focusMode": "Standard"
},
"Output": {
"camera": {
"analogGain": {
"default": 500.0,
"max": 1024.0,
"min": 256.0,
"value": 354.0
},
"digitalGain": {
"default": 256,
"max": 1000,
"min": 0,
"value": 256
},
"exposure": {
"default": 50000,
"max": 100000,
"min": 100,
"value": 53900
},
"focusMode": {
"default": "Standard",
"value": "Standard"
},
"nearFocus": {
"default": 450,
"max": 1024,
"min": 0,
"value": [ 425, 425 ]
},
"standardFocus": {
"default": 300,
"max": 1024,
"min": 0,
"value": [300,300]
}
},
"State": "Completed",
"Type": "SetCameras"
}
}
}