# Welcome to M-XR's Docs

Use the bar at the top to navigate through documentation for each of our products. 

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><a data-mention href="/spaces/dSWZvUSEhiy6J2XcG20t">/spaces/dSWZvUSEhiy6J2XcG20t</a></td><td>For Marso Measure users</td><td><a href="/spaces/dSWZvUSEhiy6J2XcG20t">/spaces/dSWZvUSEhiy6J2XcG20t</a></td><td><a href="/files/6zB4ivpFiNjfrAchDSvH">/files/6zB4ivpFiNjfrAchDSvH</a></td></tr><tr><td><a data-mention href="/spaces/1qUuQhJ8sb2nM5XkrXfN">/spaces/1qUuQhJ8sb2nM5XkrXfN</a></td><td>For Marso Studio users</td><td><a href="/spaces/1qUuQhJ8sb2nM5XkrXfN">/spaces/1qUuQhJ8sb2nM5XkrXfN</a></td><td><a href="/files/VF1wg8uUVT3BsPmbAof1">/files/VF1wg8uUVT3BsPmbAof1</a></td></tr></tbody></table>

### Use cases

{% columns %}
{% column width="50%" %}
{% embed url="<https://www.datocms-assets.com/47385/1752024799-shoebootoilspill_web-gridvid_black_a.mp4>" %}
Fashion
{% endembed %}

{% embed url="<https://www.datocms-assets.com/47385/1752080929-cafe_armchair_web-gridvid_black_a.mp4>" %}
Furniture
{% endembed %}

{% endcolumn %}

{% column width="50%" %}
{% embed url="<https://www.datocms-assets.com/47385/1752024799-statuealigatorskullgold_web-gridvid_black_a.mp4>" %}
Cultural Heritage
{% endembed %}

{% embed url="<https://www.datocms-assets.com/47385/1752024799-petrol_can_green_web-gridvid_black_a.mp4>" %}
Gaming
{% endembed %}
{% endcolumn %}
{% endcolumns %}


# Welcome to Marso Measure by M-XR

{% embed url="<https://youtu.be/moNyx8W9F1Q?si=h5M1pcznDEcPW7zw>" %}

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/zNSzZvzgxKchsILGMmwW">/pages/zNSzZvzgxKchsILGMmwW</a></td><td><a href="/files/1PIKBHQO7UDvRiCBAHmm">/files/1PIKBHQO7UDvRiCBAHmm</a></td><td><a href="/pages/zNSzZvzgxKchsILGMmwW">/pages/zNSzZvzgxKchsILGMmwW</a></td></tr><tr><td><a href="/pages/z8EmGcR6Zyz3Vljxr27P">/pages/z8EmGcR6Zyz3Vljxr27P</a></td><td><a href="/files/9uNGVjqfbC7bj02zqXto">/files/9uNGVjqfbC7bj02zqXto</a></td><td><a href="/pages/z8EmGcR6Zyz3Vljxr27P">/pages/z8EmGcR6Zyz3Vljxr27P</a></td></tr><tr><td><a href="/pages/Tmk1xrpKdJrT7UQ8YbsL">/pages/Tmk1xrpKdJrT7UQ8YbsL</a></td><td><a href="/files/oORT78br4dbr8hNzQz29">/files/oORT78br4dbr8hNzQz29</a></td><td><a href="/pages/Tmk1xrpKdJrT7UQ8YbsL">/pages/Tmk1xrpKdJrT7UQ8YbsL</a></td></tr></tbody></table>


# Using Marso Measure

A step by step guide on the entire Marso Measure workflow.

### What is Marso Measure?

Marso Measure is our PBR material capture software, designed to create 3D assets that can be put into wider 3D worlds. It specialises in capturing hard-surface items, props, furniture and shoes.&#x20;

## Overview&#x20;

1\) [**Calibration**](#calibration)

**2)** [**Capture**](/marso-measure/getting-started/capture)

**3)** [**Develop**](#develop)

**4)** [**3D Solve**](#id-3d-solve-reality-capture-metashape)

**5)** [**Process**](#process-marso)

**6)** [**Using your asset**](#using-your-asset)

## Step by step

### Calibration - Marso Measure

When you first receive your build, you will need to calibrate your capture system. At this stage, we have seen incredible results with a simple camera and ring flash, a camera and small point light and a robotic capture system, like the Rigsters Arago.

#### [Exposure Calibration](/marso-measure/resources/creating-an-exposure-calibration) - Capturing an image of a [grey card](/marso-measure/resources/capturing-a-calibration-image/grey-cards-or-known-values).

#### [Light System Calibration](/marso-measure/resources/creating-a-light-system) - Measuring from camera sensor to flash.

### Capture

Once you have calibrated your system, you can start capturing. When capturing it is important to follow these hints to increase consistency across results:&#x20;

### Setup Your Scene&#x20;

* **Room Lighting** - Ensure your environment is dark when the camera's light or flash is turned off.
* **Markers** - Use markers to help alignment and to set scale of your scene.
* **Reflections** - Avoid shooting next to white walls or mirrors to avoid bounce light.

[Learn more about setting up your scene.](/marso-measure/requirements/capture-requirements#capture-scene)

### Capturing Your Asset

* **Trigger** - Only trigger one light source at a time if your using multiple lights.
* **Exposure** - Use manual settings to maintain a constant exposure per Marso Measure's requirements.
* **RAW** - Ensure your camera is set to shoot a raw file format.
* **Coverage** - Be sure to capture the object from as many views as possible, covering all angles.

[Learn more about capturing your asset.](/marso-measure/requirements/capture-requirements)

### Develop Images

Next up is the [Develop process](/marso-measure/getting-started/create-job#photogrammetry-image-preparation), you will see this word across our UI and in tutorials. This step is taking your RAW images captured in the previous step and preparing them to be imported into Reality Capture or Agisoft Metashape.&#x20;

{% hint style="danger" %}
It is very important you use the images generated by Marso Measure in the develop step to complete photogrammetry.&#x20;
{% endhint %}

### 3D Solve - Reality Capture/Metashape

Once you have your images from the develop step previously, these can be imported directly into Reality Capture or Metashape to complete your photogrammetry. We want to obtain an alembic and ST map.&#x20;

Our page dedicated to [photogrammetry](/marso-measure/getting-started/photogrammetry) gives a checklist to follow, **you will not get a usable result from Marso if you do not follow this checklist.**

### Process

Like the develop step, you will see the [p](/marso-measure/getting-started/processing)[rocess step](/marso-measure/getting-started/processing) throughout our UI and tutorials. This step takes your alembic and ST map acquired in the previous step, uses our ML model to give you your outputs. Full information on how to configure this step correctly can be found [here](/marso-measure/getting-started/processing).

### Using your asset

To export your asset, you can follow [these steps](/marso-measure/getting-started/processing#export-from-marso). You can then take your textures into [Blender](/marso-measure/using-results/blender) or [Unreal Engine 5+](/marso-measure/using-results/unreal-engine-5+).


# Capture Requirements

Please ensure you are familiar with the capture requirements, following these requirements will improve results considerably.

For your Capture System to be compatible with Marso Measure, it must:

* Capture images in RAW format, with manual exposure.
* Capture with the flash enabled, and little to no ambient light.
* Capture against a dark background, ideally black.

If you are unsure whether your system will work with Marso Measure, follow the recommendations below, or contact <info@m-xr.com> to discuss the details of your system.

***

* [Camera](#camera)
* [Lens](#lens)
* [Light(s)](#lights)
* [Capture Scene](#capture-scene)
  1. [Ambient Lighting](#ambient-lighting)
  2. [Background](#background)
  3. [Markers](#markers)
* [Framing](#framing)
* [Coverage](#coverage)
* [Files](#files)

## Camera

Marso Measure has been designed and developed with professional & prosumer cameras in mind, such as DSLRs, mirrorless cameras, and some smartphone cameras.

If you are capturing with multiple cameras, they must all be the same model. Marso Measure can only work with one camera model for each capture.

**Key Points**

* Save images in a RAW file format. Supported RAW formats can be found [here](/marso-measure/requirements/capture-requirements/supported-raw-formats).
* Set manual exposure (shutter speed / ISO / Aperture).
* Disable any image stabilisation, either on the lens, camera or both.
* A high aperture number will offer better results, by keeping more of the object in focus.

***

## Lens

We suggest use a lens around 28mm (wide). Marso Measure requires the whole object be kept in frame, see [here](#framing).

Ultra-wide and telephoto lenses are not recommended, due to the increased distortion making a photogrammetry solve more difficult.

***

## Lights

Usually the best option for lighting is the on-board flash, either on your DSLR camera or smartphone. If you don’t have an on-board flash, or wish to use an existing light setup, see [here](/marso-measure/requirements/capture-requirements/light-sources).

***

## Capture Scene

#### Ambient Lighting

Ideally the scene would have no ambient light at all. Failing this, the flash must be powerful enough to overpower any ambient light. See below for perfect, okay and bad ambient lighting examples.

{% tabs %}
{% tab title="Perfect Lighting" %}

<div><figure><img src="/files/N1wKZE6lw1kvkknN2y5G" alt="" width="300"><figcaption><p>Flash Off</p></figcaption></figure> <figure><img src="/files/7Xg3O90HIUHoQncqzk5X" alt="" width="300"><figcaption><p>Flash On</p></figcaption></figure></div>
{% endtab %}

{% tab title="Okay Lighting" %}

<div><figure><img src="/files/MIEnHDUIw9Rg3gp8lDsQ" alt="" width="300"><figcaption><p>Flash Off</p></figcaption></figure> <figure><img src="/files/v5Xoc5UxkVAFJ3WOi0qo" alt="" width="300"><figcaption><p>Flash On</p></figcaption></figure></div>
{% endtab %}

{% tab title="Bad Lighting" %}

<div><figure><img src="/files/PjCHDJxYxjYOJGRA6vkj" alt="" width="300"><figcaption><p>Flash Off</p></figcaption></figure> <figure><img src="/files/cuhENH3JIruaDzuvZnlX" alt="" width="300"><figcaption><p>Flash On</p></figcaption></figure></div>
{% endtab %}
{% endtabs %}

#### Background

In addition to reducing the ambient lighting, it is also important to reduce any bounced or reflected light. This is quite easy to do by ensuring that you are shooting against black, or by avoiding too much white in your surrounding area. Please see below for good and back background lighting examples.

{% tabs %}
{% tab title="Good Background" %}

<figure><img src="/files/8DHU2AQPZEegORiPuj5M" alt="" width="360"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Bad Background" %}

<figure><img src="/files/9j8zoxVMi4kmTyukb8Hj" alt="" width="360"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

#### Markers

Markers are recommended to improve the accuracy of the photogrammetry solve.

Marso Measure also requires the solved scene to be accurately scaled, so it is a good idea to have at least two markers and measure the distance between them, as this can be used to scale the scene.

If the subject is moving, for example on a turntable, it is **crucial** that the markers also move along with the object.

#### Marker Examples

<div align="left"><figure><img src="/files/8LwhXVnPHxW9uwW2Y1Gl" alt=""><figcaption></figcaption></figure> <figure><img src="/files/mmEpiw7AWfnEy6cglroC" alt=""><figcaption></figcaption></figure> <figure><img src="/files/XF4xRCYyc4qOEHjp5cY7" alt=""><figcaption></figcaption></figure></div>

#### Framing

It is important to keep as much of the object within the frame where possible.

{% tabs %}
{% tab title="Perfect Framing" %}

<figure><img src="/files/Piw1IxuNyzZXrNRw1GgZ" alt="" width="300"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Okay Framing" %}

<div><figure><img src="/files/4d4qaaS3y5ZLGeIELKMg" alt="" width="300"><figcaption></figcaption></figure> <figure><img src="/files/d1NHJvR7lVv6JQlzluIH" alt="" width="300"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Bad Framing" %}

<figure><img src="/files/9xzLpY0xKvJCEIV33RrF" alt="" width="300"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

***

## Coverage

Marso requires a high level of coverage, both above and below your asset. See our full coverage documentation [here](/marso-measure/requirements/capture-requirements/coverage).

{% hint style="info" %}
Replicating the coverage maps on this linked page will yield optimal results.
{% endhint %}

***

## Files

Marso expects that all captured images for a single subject will be in a single folder. Files must also be named so that they sort alpha-numerically into the order they were captured in. Most cameras do this automatically.

{% tabs %}
{% tab title="Good" %}
`Cam_000, Cam_001, Cam_002, Cam_003, …`

Names are in order

`DSC_1234, DSC_1235, DSC_1236, DSC_1237, …`\
Names don’t start at 0 but are in order
{% endtab %}

{% tab title="Bad" %}
`Cam_0, Cam_1, … , Cam_10, … , Cam_100`\
Numbers are not padded with 0s to the same length

`Cam_000, Image_001, DSC_002, Cam_003, ...`\
Numbers are ordered, but names are not
{% endtab %}
{% endtabs %}

If you are using multiple lights, the captures for each position should be grouped in the order they were captured when sorted.

The simplest way to do this is to name the files with the position first, followed by the light:\
Position\_X\_Light\_Y.dng


# Coverage

Coverage of your asset is extremely important, please read through the full documentation.

For Marso Measure to work properly, it is important to have good coverage. This means capturing enough perspectives of the object from directly above as well as below.

This may require more photography than previously required for basic photogrammetry.

{% embed url="<https://youtu.be/fgYSNYyvZgw?si=OvBziPjj8P256-ti>" %}

## Camera Position Examples

We have a dedicated [Sketchfab page](https://sketchfab.com/m-xr/collections/camera-coverage-f8798081e24745ba8cbbe485558b016a) to show example camera positions for scans we have completed internally, you can view this page [here](https://sketchfab.com/m-xr/collections/camera-coverage-f8798081e24745ba8cbbe485558b016a).

Following these examples when capturing your datasets will improve results.

## Examples of Camera Coverage

<div align="left"><figure><img src="/files/N5EdBChDkkL1lyaxhZjW" alt="" width="188"><figcaption><p>Perfect Coverage</p></figcaption></figure> <figure><img src="/files/ch7oU099ik5nqKnAtsqc" alt="" width="188"><figcaption><p>Okay Coverage</p></figcaption></figure> <figure><img src="/files/f9sB2wmNPmQ59UQlki41" alt="" width="188"><figcaption><p>Bad Coverage</p></figcaption></figure></div>

{% hint style="danger" %}
Red = Areas the cameras cannot see.&#x20;
{% endhint %}

<div align="left"><figure><img src="/files/Mx2I2mzJ6COdcki6JRYD" alt="" width="188"><figcaption><p>Perfect Coverage Map</p></figcaption></figure> <figure><img src="/files/iCMRP5b2VdHvs6Kb4vOH" alt="" width="188"><figcaption><p>Bad Coverage Map</p></figcaption></figure></div>

{% hint style="info" %}
Overshooting on the rotation will not compensate for missing positions at the top and bottom.
{% endhint %}

It is recommended to have a spacing of at most 12° in each axis *(30 positions to do a full 360° capture)*.

The spacing in each axis does not have to be equal to one another - *e.g.*: a latitude spacing of 10° with a longitude spacing of 5° will work well. However, a latitude spacing of 50° and a longitude of 5° will not - as this is above our maximum recommended spacing.

<figure><img src="/files/YjHk1H6ocQ1FpTrTjVzm" alt=""><figcaption><p>An ideal coverage map</p></figcaption></figure>


# Light Sources

Follow this page to understand supported light sources for Marso Measure.

## Light Types

For best results, we recommend using as small of a light as possible. Sometimes this can be achieved by removing any diffusion or reflectors attached to an existing light fixture to expose just the bulb.

#### Supported Light Sources

{% tabs %}
{% tab title="Supported Lights" %}

* Point Light&#x20;
* Built-in camera flash
* Single LED
* Ring Flash
  {% endtab %}

{% tab title="Not Supported" %}

* Softboxes
* Umbrella lights
* Reflectors
* Polarisation Filters
  {% endtab %}
  {% endtabs %}

{% hint style="warning" %}
When using an external light source, it is important to place it as close to the camera sensor as possible. Increased distance between the light source and the camera sensor will decrease the quality of results.
{% endhint %}

***

### Using a Ring Flash

If you would like to use a ring light, it is important to ensure that the distance from the camera to the subject large is enough to minimise the subject blocking any part of the light from the visible surface of the subject.

<details>

<summary>Good Ring Flash Positions</summary>

![](/files/v8qjJA7VUCjbWdEavbuc)

</details>

<details>

<summary>Bad Ring Flash Position</summary>

![](/files/Rt2IzaLeaLLKg1oU0wyo)

</details>

***

### Explore different light sources and their effects on an asset

<div align="left" data-full-width="false"><figure><img src="/files/7sgB4cHBqdsoxMGedDQc" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/RCN0P2ZGCWhK14HGmpXS" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/q23aq1FrAc9xwPFy0wuj" alt="" width="188"><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/4nOXjb0RI6A1nZ1ydwch" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/iGd2pyLbwbVxSbc2Ash8" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/sDczApSJjDMkoUhaCYFj" alt="" width="188"><figcaption></figcaption></figure></div>

<table><thead><tr><th width="201.4609375" align="center">Ideal Light Source</th><th width="200.6875" align="center">Not Compatible</th><th width="212.859375" align="center">Not Compatible</th></tr></thead><tbody><tr><td align="center">Small point light</td><td align="center">Soft shadows</td><td align="center">Large effective area</td></tr><tr><td align="center">Crisp shadows</td><td align="center">Irregular light falloff</td><td align="center">Soft shadows</td></tr><tr><td align="center">Sharp highlights</td><td align="center">Variable Intensity</td><td align="center">Soft / smooth reflections</td></tr></tbody></table>

***

## Light Placement

The closer a light is to the centre of the camera, the smaller the shadows will be in the source photography.

These shadows can interfere with the results from Marso Measure, making predictions worse.

As with the light size, this distance between a light and a camera is relative to the overall scale of the scene.

The closer the camera is to the subject, the greater the angle between the camera and light is at a point on the subject. Smaller angles will result in better results.

<figure><img src="/files/D7mv2IhulrFLJuZtZkup" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
We recommend an angle of 3° or less. For anything higher than 6.5°, you should use multiple lights
{% endhint %}

| Rig Size | Distance: Camera → Subject | Max Distance: Light → Camera |
| :------: | :------------------------: | :--------------------------: |
|   Small  |           \~50 cm          |            4.5 cm            |
|  Medium  |          \~100 cm          |            9.5 cm            |
|   Large  |          \~150 cm          |             14 cm            |


# Supported RAW Formats

RAW file formats your camera must be able to shoot in. If you want to shoot in a different RAW file format, please get in touch.

### **Marso Measure supports the following RAW file formats:**

* CR2
* CR3
* NEF
* ARW
* RAF
* DNG


# Processing Requirements

Please contact us if you have any questions regarding processing requirements.

Processing PBR textures with Marso Measure usually requires a desktop workstation, with a GPU available.

<table><thead><tr><th>Minimum Specification</th><th>Recommended Specification</th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><ul><li>OS: Windows 10+</li><li>RAM: 16+ GB</li><li>GPU: OpenGL 4.6+ Compatible</li><li>Hard Drive: ~256 GB available</li></ul></td><td><ul><li>OS: Windows 10+</li><li>RAM: 32+ GB</li><li>GPU: Nvidia (CUDA enabled), 8+ GB VRAM</li><li>Hard Drive: ~1TB available</li></ul></td><td></td><td></td></tr></tbody></table>

***

### Scratch Directory

Marso Measure makes use of a “Scratch Directory”, where intermediary files are written during processing, and will be deleted once no longer needed. The size of these files depends on the output texture resolution.

Faster R/W speeds on the scratch directory will greatly improve processing times, so it is recommended to use an internal SSD for the scratch directory. Results can be written to a different drive such as a network share.

{% hint style="info" %}
Recommended: 180000+ IOPS, 3000+ MiB/s
{% endhint %}


# Software Installation

If you need any help with installing Marso Measure, please reach out to support\@m-xr.com.

***

## Installation Steps

1. The installer is an MSI that installs to program files.&#x20;
2. You will be prompted to accept the T\&Cs upon installation, simply accept and continue.&#x20;
3. If you wish to uninstall, this can be done by locating Marso Measure and selecting uninstall. This process is the same as any other app you have on your workstation.&#x20;

## Next Steps

After the installer completes, Marso Measure can be launched from the start menu. You will then need to sign in to your M-XR Account again, then you will be ready to continue to [Setup](/marso-measure/getting-started/software-setup).

## Demo Data

Some data can be found [here](https://api.m-xr.com/v1/maestro/demo).

***


# Software Setup

Follow this page when you first setup Marso Measure.

## System Settings

You will need to create a "Scratch" folder and configure this within the settings area of Marso Measure.

### Scratch Directory:&#x20;

* Up to 256GB will be used during processing, for intermediary files that will be cleaned up once complete.
* Fast R/W speeds are highly recommended. Slower drive speeds will slow down processing.

&#x20;\
This can be accessed by clicking your profile in the bottom left corner then **Settings**.

<div align="left" data-full-width="false"><figure><img src="/files/UueJEjeSrX4hjufkfjGU" alt="" width="563"><figcaption></figcaption></figure></div>

***

### Developer Settings

**Keep Intermediary Files** and **Enable Verbose Logging** should only be enabled if you are collecting debugging information for M-XR, following an issue with processing.&#x20;

They should be disabled otherwise, to not consume too much disk space.


# Capture

Instructions for capturing a subject for best results from Marso Measure.

## First Capture

If this is the first capture you have done with the camera and light set-up, you will need to [c](/marso-measure/resources/capturing-a-calibration-image)[apture a calibration image](/marso-measure/resources/capturing-a-calibration-image). The RAW image and measurements will be used to create configuration presets later.

## Capture Methods

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>Camera (DSLR) + Ring Flash</td><td><a href="/pages/gaFdcTxmUKbiqbOi5wwz">Click here if you are capturing with a DSLR + Ring Flash. (Recommended)</a></td><td><a href="/files/mgpyvkGMvLLXQXjdAz8j">/files/mgpyvkGMvLLXQXjdAz8j</a></td></tr><tr><td>Camera (DSLR) + Point Light &#x26; Turntable</td><td><a href="/pages/Yxd7KHR0KtuE1hB6aiIq">Click here if you are capturing with a DSLR + Point Light.</a></td><td><a href="/files/2QxKJbt6fRbS8860euuh">/files/2QxKJbt6fRbS8860euuh</a></td></tr><tr><td>Rigsters Arago</td><td><a href="/pages/c3jv3flYvbe69KrtTFzb">Click here if you are capturing with a Rigsters Arago.</a></td><td><a href="/files/6M8cJ8XLfpnwk05p2etH">/files/6M8cJ8XLfpnwk05p2etH</a></td></tr></tbody></table>

### Capture Checklist

#### The room you are capturing in should be as dark as possible

If there is any ambient light, your light source must be able to overpower it.&#x20;

#### Ensure you can save in a RAW file format&#x20;

JPEG input is not supported by Marso Measure.

#### Set manual exposure settings (shutter speed / ISO / aperture)

Use the same exposure settings as the calibration image, otherwise you will need to take a new one.

#### Trigger your Light Source

Trigger your flash or light source on every capture.

#### Place markers to help alignment

Markers are recommended to improve the accuracy of the photogrammetry solve. Make sure that if the subject rotates, the markers rotate with them.

Marso Measure also requires the solved scene to be accurately scaled, so it is a good idea to have at least two markers placed at a known distance apart, as this can be used to scale the scene.

#### Get good coverage of the subject

Being able to capture angles above and below the asset will improve results considerably. Please visit [this](/marso-measure/requirements/capture-requirements/coverage) page for more information about coverage.&#x20;

Try to keep the subject large in the frame, while still capturing the whole subject in every frame.

#### Use only one model of camera

If you are using multiple cameras, they must be the same model.&#x20;

***

Once you have captured your photography, you can [Create a Job](/marso-measure/getting-started/create-job).


# Camera and Ring Flash

Follow the instructions if capturing with a camera & ring flash.

{% embed url="<https://www.youtube.com/watch?v=CIy-cUuSN5U>" %}

## Overview

1. [**Capture Distance**](#capture-distance) **-** Maintaining a good distance.
2. [**Consistent Brightness**](#consistent-brightness) **-** Key to record brightness settings.
3. [**Markers**](#markers) **-** Including if you have knocked a marker during scanning.
4. [**Consistent Focus**](#consistent-focus) **-** Focus on the subject, not the background.
5. [**Ambient Exposure**](#ambient-exposure) **-** Control the ambient lighting in your scene.
6. [**Overshooting**](#pro-tip-overshooting) **-** It is better to overshoot and delete images later.

### Capturing with a Ring Flash

Firstly it is important to make sure you have created the relevant presets for [exposure](/marso-measure/resources/creating-an-exposure-calibration) and [light](/marso-measure/resources/creating-a-light-system) calibration.&#x20;

Manual settings should be kept on at all times.

{% hint style="info" %}
When inputting figures for a Ring Flash light calibration, the X and Y axes should be left as 0, with the Z axis having the figure you get from your ruler measurement.
{% endhint %}

### Capture Distance

If you would like to use a ring flash, it is important to ensure that the distance from the camera to the subject large is enough to minimise the subject blocking any part of the light from the visible surface of the subject.

<details>

<summary>Good Ring Flash Positions</summary>

<div><figure><img src="/files/9ehSpSnbzXErdVoY5sBp" alt=""><figcaption></figcaption></figure> <figure><img src="/files/r8Hbf4LP8sEHzfyuiKKp" alt=""><figcaption></figcaption></figure> <figure><img src="/files/lhNDUrHNSV31uXZQyAGZ" alt=""><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Bad Ring Flash Position</summary>

<div><figure><img src="/files/IxTpdwUB2TJC0BESuxZM" alt=""><figcaption></figcaption></figure> <figure><img src="/files/HpfIaD9om1ZcPWjaGtAR" alt=""><figcaption></figcaption></figure> <figure><img src="/files/17OCgVSBpixQWRWVwQF0" alt=""><figcaption></figcaption></figure></div>

</details>

### Consistent Brightness

To ensure consistency across scans, we recommend checking your brightness. You can do this by taking lots of photos of a white wall, if the images are jumping around in brightness, then power should be increased.&#x20;

{% hint style="success" %}
Take a note of the flash power settings, this often isn't recorded in the metadata and will be needed for your exposure solve.
{% endhint %}

### Markers&#x20;

Including markers in your scene will help for scale and camera alignment. We recommend taping down your markers to avoid any movement.&#x20;

Moved a marker during scanning?

* **If you a part way through a scan, and move a marker, but haven't taken more photos** - remove this marker from the scene and place it out of shot. This will avoid any issues when performing a 3D solve.
* **If you are part way through a scan, and have taken lots of picture of the markers moved** - either reshoot the capture, or make a note of which markers were moved, and remove them from marker detection when performing your 3D solve later.

### Consistent Focus&#x20;

Ensure you're camera focuses on the subject not the background.

### Ambient Exposure&#x20;

Take a picture with the flash off to judge the effects of ambient lighting, you want this as dark as possible.

### Pro Tip: Overshooting

It is better to overshoot and delete images when doing your 3D solve, than undershoot and not be able to go back to your location


# Camera and Point Light

Follow this page if using a camera and point light.

We recommend using the SmallRig RM-01 Waterproof Portable Photography Light. For a more even illumination, it is recommended to remove the internal Fresnel lens. See instructions [below](#diffusion-modification):

#### Diffusion Modification

1. Use a small allen key to open the front housing of the light.&#x20;
2. Carefully remove the fresnel lens.&#x20;
3. Reassemble the front cover.&#x20;

{% hint style="success" %}
This results in a softer and more uniform light distribution, reducing hot spots and improving surface consistency for photogrammetry.&#x20;
{% endhint %}

## Overview

1. [Light Output and Working Distance](#light-output-and-working-distance) - Tips on the type of asset to capture.
2. [Camera Setting Considerations](#camera-setting-considerations) - Control your camera settings.
3. [Markers](#markers) - Including if you have knocked a marker during scanning.
4. [Consistent Focus](#consistent-focus) - Focus on the subject, not the background.
5. [Overshooting](#pro-tip-overshooting) - It is better to overshoot and delete images later.

***

### Capturing with a Point Light

Firstly it is important to make sure you have created the relevant presets for [exposure](/marso-measure/resources/creating-an-exposure-calibration) and [light](/marso-measure/resources/creating-a-light-system) calibration. Manual settings should be kept on at all times.&#x20;

{% hint style="warning" %}
Most point lights like the one we recommend above has limited output power, when the camera is positioned more than 0.5m away from your object, noticeable light fall-off may occur.
{% endhint %}

***

### Light Output and Working Distance

* As mentioned above, keep an eye on the light output and adjust the working distance. The light is best suited to **small objects and macro-scale capture.**&#x20;
* It is recommended to operate the light at **full power**.
* You can fit the light onto the **camera's hot shoe**, be sure to create the correct [exposure](/marso-measure/resources/creating-an-exposure-calibration) and [light](/marso-measure/resources/creating-a-light-system) calibration.

### Camera Setting Considerations

* Use a **low ISO** to minimise noise.&#x20;
* Use a **high f-number** (small aperture) to maximise depth of field.

Taking into account the above settings will mean:

* You will need to use a **slow shutter speed**.&#x20;
* A **tripod or rigid camera mount** to avoid motion blur.

### Markers&#x20;

Including markers in your scene will help for scale and camera alignment. We recommend taping down your markers to avoid any movement.&#x20;

Moved a marker during scanning?

* **If you a part way through a scan, and move a marker, but haven't taken more photos** - remove this marker from the scene and place it out of shot. This will avoid any issues when performing a 3D solve.
* **If you are part way through a scan, and have taken lots of picture of the markers moved** - either reshoot the capture, or make a note of which markers were moved, and remove them from marker detection when performing your 3D solve later.

### Consistent Focus&#x20;

* Ensure you're camera focuses on the subject not the background.

### Pro Tip: Overshooting

* It is better to overshoot and delete images when doing your 3D solve, than undershoot and not be able to go back to your location


# Rigsters Arago

Follow this page if you have a Rigsters Arago.

Firstly it is important to make sure you have created the relevant presets for [exposure](/marso-measure/resources/creating-an-exposure-calibration) and [light](/marso-measure/resources/creating-a-light-system) calibration.&#x20;

Manual settings should be kept on at all times.

{% hint style="success" %}
Marso Measure works by measuring how light interacts with an object, so getting the lighting in your scene right will result in better results.
{% endhint %}

If you need any help setting up the Arago, you can see Rigsters documentation [here](https://rigsters.com/arago/docs/).

***

### Setting up your scene

#### Lighting

Keep the environment as dark as possible, or dark enough that the light source over-powers any ambient lighting.

#### Background

As the Arago rotates the object on the turntable, avoid having anything in the background that the photogrammetry application might detect as “features” that remain static during the scan.&#x20;

{% hint style="success" %}
We have simply used a black cloth attached to a wall.
{% endhint %}

#### Markers

Placing markers on both the base plate and the posts of the Arago improves 3D reconstruction. These markers provide clear reference points for your photogrammetry software, making it easier to detect features and establish scale.

<div align="center"><figure><img src="/files/Oz3SQJHvE6egPOEqqDJp" alt="" width="375"><figcaption></figcaption></figure> <figure><img src="/files/d95K1alTyRxPj7CN9NRl" alt="" width="375"><figcaption></figcaption></figure></div>

***

### Camera Coverage

Coverage is critical in the Marso Measure workflow. Ensure the subject is framed consistently throughout the scan, and capture it from as many angles as possible - including top and bottom views - to achieve the best results.

{% hint style="success" %}
If you want to see an example of what a great coverage is, [click here](https://sketchfab.com/3d-models/coverage-sneaker-motion-controlled-eabe98949fed452b81054bbec9ed34e6).
{% endhint %}

#### Establish good framing&#x20;

Ensure the object fits well within the frame - it shouldn’t appear too small, but it also shouldn’t be cropped. To achieve good framing, use the live view mode on the Arago to look through the camera, and rotate the pedestal to position the object correctly.

#### Place a sphere over the object&#x20;

Create a sphere around your subject so it generally encloses the subject. If the sphere is too large, the Arago may struggle to keep it in frame; if it’s too small, parts of the object may be cropped.

<div align="center"><figure><img src="/files/8rdSsAAoVnqCWGjr2HaP" alt="" width="375"><figcaption></figcaption></figure></div>

#### Generate camera positions

Use the ‘Auto’ mode under the positions tab to generate camera views.

* **Low Camera Views** - It is important to have a high number for the ‘Cut-off MAX angle’ to ensure the Arago can take photographs from below. Be aware there is a physical limit to how low the camera can capture before it collides with the pedestal.
* **Distance** - Use the distance to set how far the cameras are placed from the surface of the sphere, aim to have the camera instanced at distance similar to the starting position when you established a good framing.
* **Experiment** - It is best to play around with the other settings to get a feel for how they alter the way camera positions are instanced.
* **Check Focus & Settings** - Be sure to double check the camera’s focus and settings before starting a capture sequence.

<div align="center"><figure><img src="/files/kFfuoMMrzfTYAhHZ3M4Q" alt="" width="375"><figcaption></figcaption></figure></div>


# Create Job

Follow this page when creating a job using Marso Measure.

In Marso Measure a **Job** is used to track the status of a particular subject from capture to textures. Once your capture is complete, and you have a folder of RAW photography you are ready to process with Marso Measure.

{% hint style="danger" %}
If your calibration image is in the same folder as the subject photography, move it to a different directory before continuing!
{% endhint %}

### Create Job

This is the area where you will be able to view all of your jobs. You can click "New Job" in the top right corner to create a new job.

<div align="left"><figure><img src="/files/i5N80ufskVENrjBnq3vD" alt="" width="563"><figcaption></figcaption></figure></div>

***

#### **Enter the required information:**

* **Job Name:** A descriptive name that will be used to identify the job throughout processing and once the results are ready.
* **Mode:** Select 'Multi-Viewpoint'. See [here](/marso-measure/resources/marso-measure-processing-options#capture-methods) for more information regarding your selection.
* **RAW Images Folder:** Specify the path to the folder containing the raw images for one subject.
* **RAW Images Extension:** Select the image file format, if there are multiple in the input folder.
* **Light Selection:** Choose the Light System. If you haven't already [Create a Light System](/marso-measure/resources/creating-a-light-system).

{% hint style="warning" %}
Job Name should contain only letters, numbers, and underscores. Do not use special characters or spaces.
{% endhint %}

<div align="left"><figure><img src="/files/rOpvQDWSExgZBke9bOoD" alt=""><figcaption></figcaption></figure></div>

***

### Photogrammetry Image Preparation

This process will take the RAW images from the capture folder, and process them into JPEG or EXR images that should be used for photogrammetry.

{% hint style="danger" %}
It is vital that Marso Measure generated photogrammetry images are used, to ensure consistency between the solved scene and the final textures.
{% endhint %}

Click the drop down on the right side of Marso Measure, the dropdown should give three options, Develop, Process and Delete. To prepare your images for import into Reality Capture or Agisoft, click Develop.&#x20;

<div align="left"><figure><img src="/files/3xroMmOCzRqPxji29PZw" alt="" width="563"><figcaption></figcaption></figure></div>

#### Develop Configuration

1. You can use the slide bar to adjust the brightness of images, this is down to user preference. This will not affect the final textures produced by Marso Measure, only the photogrammetry images.
2. You can choose your Output Type, either EXR or JPEG. Reality Capture recommends JPEGs, unless you need to manually modify the image content e.g. masking.&#x20;

{% hint style="danger" %}
If you are modifying the images, ensure that the names are not changed.
{% endhint %}

3. Choose the output path where the photogrammetry images will be saved.&#x20;
4. You can click Apply to save your chances, you can also Save & Queue Last, Save & Queue Next or Save & Start Now depending on your preference for this job.

<div align="left"><figure><img src="/files/5JetKiGT4LVO4tZSnhQ9" alt="" width="563"><figcaption></figcaption></figure></div>


# Photogrammetry

Follow this page when completing photogrammetry.

Once you have the photogrammetry images generated by Marso Measure, you can complete your normal Photogrammetry Workflow.

For specific tips depending on your photogrammetry software of choice, see [Photogrammetry Tips](/marso-measure/resources/photogrammetry-tips).

***

## Photogrammetry Checklist

#### Use the images generated by Marso Measure

Images with names *photogrammetry\_xxx* must be used. You can find these by pressing the `Images` button when the job is selected.

{% hint style="info" %}
At this time, you **cannot** use an external software like Lightroom to do this.
{% endhint %}

#### Ensure most cameras are solved accurately

Poorly solved cameras can lead to artifacts in the material measurement later on. We recommend attempting to re-align any bad camera solves. Cameras that cannot be aligned should be removed from the scene or disabled.

#### Include any stands or supports in your bounding box

Any geometry that might obstruct a camera's view of the subject should not be removed, but exported separately as a [Mesh Mask](/marso-measure/getting-started/photogrammetry/mask-mesh-and-manual-uv-unwrap)

#### Scale the Solved Scene

It is essential that the scene is scaled. The recommended approach is to place two markers at a known distance apart in the scene, and once solve apply the distance constraint.

{% hint style="info" %}
You can also re-scale with Blender by following the instructions [here](/marso-measure/resources/re-scaling-an-alembic-with-blender).
{% endhint %}

#### UV Unwrap the subject

A UV Unwrap is required for Marso Measure to export textures. This can be done automatically by the photogrammetry software by running the texturing process, or [Manually](/marso-measure/getting-started/photogrammetry/mask-mesh-and-manual-uv-unwrap) if you prefer.

{% hint style="info" %}
For optimal UVs we recommend generating the texture at the same resolution or lower resolution than the textures you wish to output from Marso Measure.&#x20;

A UV Unwrap at higher resolution than the final textures may cause artifacts.
{% endhint %}

***

{% hint style="warning" %}
A very high number of polygons in the mesh may cause Marso Measure to exceed the available VRAM on your system. If this occurs, simplify the mesh and reattempt the process.&#x20;

Marso Measure can produce highly detailed normals, even on medium to low poly meshes.
{% endhint %}

***


# Mask Mesh & Manual UV Unwrap

See this page for more information regarding Mash Mesh and Manual UV Unwrap.

### Mask Mesh

The Mask Mesh is a separate mesh file from the Subject Mesh. It should contain any geometry within the scene that occludes the subject from a given camera view.

In this example, the plinth occludes the shoe for the lower cameras (see below)

<div><figure><img src="/files/Tx0JOnwytBma36ijvJFO" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/GROdymxtmemaxBj687fU" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
If the plinth is not included within the scene, parts of the plinth will be mistakenly projected onto the underside of the shoe.
{% endhint %}

To avoid this, use a separate 'Mask Mesh' to denote unwanted geometry that occludes the subject, in this case, the plinth. **Blue (Asset)** will be used for the final texture, **Red (Plinth)** will not.

<div><figure><img src="/files/kUJauKrjVqVpUdxf0ZNy" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/CrqvV0XOynAUqrXuF7sF" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="danger" %}
Make sure the Subject is not present in the mask mesh, otherwise no textures will be produced.

Providing a mask mesh ensures that these areas will not affect the final asset, as otherwise they can be projected across the surface, leading to problems in the final textures.
{% endhint %}

***

### Manual UV Unwrap

You are welcome to UV unwrap the mesh yourself in an application of your choosing before importing it into Marso Measure.

**Photogrammetry → .abc → UV Unwrap → .abc → Marso Measure**

Just be sure to **adhere** to the following:

* You **must** export this new mesh as an alembic (.abc) file, with cameras, normals, and triangles rather than quads.
* Only do a single UV Page.
* Ensure the scale or units of the Object & Scene **does not change** upon export.
* Ensure that the cameras are exported within the alembic (.abc) file and have not been renamed or re-ordered.


# Processing

Follow this page when you are ready to process.

{% hint style="success" %}
Once you have produced an Alembic, ST Map(s), and optional Mask Mesh, you are ready to process the Job to produce your textures.
{% endhint %}

1. Hover over Actions on the right side and click Process.

<div align="left"><figure><img src="/files/G483nJUGkWKqIpj8ibMo" alt="" width="563"><figcaption></figcaption></figure></div>

2. Select your exposure preset by clicking the drop down, if you are yet to create your exposure preset, see [here](/marso-measure/resources/creating-an-exposure-calibration).
3. Select the light system used by clicking the drop down, if you are yet to create a light system, see [here](/marso-measure/resources/creating-a-light-system).
4. Choose the photogrammetry software you used, for more information on photogrammetry, see [here](/marso-measure/getting-started/photogrammetry).
5. In the mesh file, mask mesh (Optional) and ST map area, provide the necessary paths.
6. Select your desired output resolution, if multiple are selected, the materials will be processed at the highest resolution and smaller textures will be down-sampled from it).
7. Select your Model
8. Once done you can apply the changes to keep them for later without adding to the queue, or save and queue last to put at the back of the queue. Additional queue options are available in the drop-down menu.

<div align="left"><figure><img src="/files/z6wT6ZIE9u4QfLlVbz6K" alt="" width="563"><figcaption></figcaption></figure></div>

***

#### Export from Marso Measure

When processing is complete you will find an new item in the asset library. This shows all assets that are available for export.

1. Click on Asset Library.
2. Find your desired job and click Export.
3. Select your export file format, multiple formats can be selected.&#x20;
4. Choose your desired output path for results.

***

#### Interrupting a job

<figure><img src="/files/j8fySl6pD4JkznubeSkc" alt=""><figcaption></figcaption></figure>

A running job can be interrupted with either the stop or skip button. Both will lose any progress up to this point.

&#x20;The stop button will return it to the front of the queue, and stop processing queue items, while the skip button will immediately start processing the next item in the queue.

***


# Blender

Follow this page for guidance when using your asset in Blender.

***

## Using your asset in Blender

1. Import your mesh from the alembic. (Camera's can be hidden or deleted)
2. Choose your settings, set 'Render Engine' to 'Cycles' and 'Device' to 'GPU Compute'.
3. Apply your textures, see below for choices:

#### [Blender Cycles - Recommended ](#blender-cycles-recommended-1)

#### [Blender Cycles Specular Workflow - Experimental](#blender-cycles-specular-workflow-experimental-1)

***

## Applying Textures

{% tabs %}
{% tab title="Blender Cycles - Recommended" %}
{% hint style="info" %}
Marso Measure’s default texture output BlenderCyles is designed for Blender’s Principle BSDF shader which is a **metallic-workflow** - however, we have had difficulties delivering the metallic texture map.
{% endhint %}

1. In the shading workspace, create a material on your mesh object by going to: Add > Shader > Principled BSDF.

<figure><img src="/files/bbz8GTkLPAOv7z71pDZD" alt="" width="563"><figcaption></figcaption></figure>

2. Load in each of your image textures using an image node. Connect them up as shown below, being careful to set all of their 'Color Space' to 'Linear' (when exr) except 'Normals' which should be set to 'Non-Color' and should go into the shader through a 'Normal Map' node with the UV map selected.

<figure><img src="/files/H7e8y8W8zgOkqYfRGBzq" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Blender Cycles Specular Workflow - Experimental" %}
{% hint style="info" %}
For Marso Measure’s new specular workflow, a custom node-graph is required, as BlenderCycles does not natively support a true specular workflow.
{% endhint %}

1. For our experimental specular workflow , you will need to use the ‘Add Shader’ node to add a Principle BSDF shader to a Diffuse BSDF shader. It is important that you also set Metallic & Specular to 1 as shown below.

<figure><img src="/files/LDEyLn6BcCoRN6iRufSM" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}


# Unreal Engine 5+

Please follow the guidance on this page when using Unreal Engine 5+.

{% hint style="info" %}
Despite both shader workflow names both including ‘Blender’, textures can be used in other render engines successfully.
{% endhint %}

## Using your asset in Unreal Engine 5

1. Start a new project, ensure that 'Quality Preset' is set to maximum and 'Raytracing' is enabled.&#x20;
2. Once loaded in, in the content browser, select import.
3. Navigate to your alembic file and select it in file explorer, use the settings below

<figure><img src="/files/NOVOVhTc0mKaGsvBDPI3" alt="" width="264"><figcaption></figcaption></figure>

4. Once imported, from the content drawer, drag your object into the viewport to place it.

{% hint style="info" %}
The scaling of units may be off, see the screenshot below. We have scaled up the mesh by 500.
{% endhint %}

<figure><img src="/files/KVxgDjY786rTOcelT6Pm" alt="" width="373"><figcaption></figcaption></figure>

5. Then select all of the EXR files in the results from Marso and add them to your content drawer (see image below):

<figure><img src="/files/MhwqMQCGkzdgqQbRZCnZ" alt="" width="375"><figcaption></figcaption></figure>

6. Double click on the normals and it will open the file inside Unreal Engine (see image below):

<figure><img src="/files/lf0dwoX5UXA8hA7QDmqF" alt="" width="375"><figcaption></figcaption></figure>

7. Then follow and set the same settings you see in the image below:&#x20;

<figure><img src="/files/YxBVBKRiQI2uU7hZ8ZSh" alt="" width="240"><figcaption></figcaption></figure>

8. Now, from the content drawer, create a new material.&#x20;
9. Double click to open the material editor. Then setup your nodegraph using the texture files from the content drawer to look like this (see below):&#x20;

<figure><img src="/files/6teO50YTEKiU9k5fccqc" alt="" width="375"><figcaption></figcaption></figure>

10. Save the material and return to the viewport.
11. Drag and drop the material from the content drawer onto your mesh (see below):

<figure><img src="/files/YnLWKYatWfZAYK7GW3CH" alt="" width="375"><figcaption></figcaption></figure>

11. Your asset should now be ready for use in Unreal Engine.


# Capturing a Calibration Image

Follow this page when capturing a calibration image.

Marso Measure requires a Calibration Image to produce correct results for the specific capture conditions. This includes the light source, camera, lens and exposure settings. The calibration image will be used to [Create an Exposure Calibration](/marso-measure/resources/creating-an-exposure-calibration).

You will also need to measure the distance between the light source and the grey card.

A Calibration Image is an image of a standardised grey card under your capture lighting conditions. This means lit only by your flash or light source, and with manual exposure and focus.

<figure><img src="/files/R0dlpL3bOsDwqS3FJNlu" alt=""><figcaption><p>Example Calibration setup</p></figcaption></figure>

{% hint style="warning" %}
If any capture parameters change, you will need to capture a new calibration image, otherwise the resulting textures may be less accurate
{% endhint %}

***

## Grey Card <a href="#capturingacalibrationimage-greycard" id="capturingacalibrationimage-greycard"></a>

If you do not already have a calibration grey card, M-XR recommends the [Datacolor SpyderCheckr24](https://www.datacolor.com/spyder/products/spyder-checkr-24/).

If you do have a grey card, check that it is listed on the [Grey Cards | Known Values](/marso-measure/resources/capturing-a-calibration-image/grey-cards-or-known-values) page, as you will need to know the grey value of at least one tile, ideally a mid grey.

***

### Set Up

Place the grey card at a similar distance from the camera as you are you are likely to capture. Try to ensure the grey card positioned as close to perpendicular to the camera as possible.&#x20;

If you are not using the on board flash, attach the light source to your camera as it will be mounted for capture.

Fix the position of the camera also. You will need to measure the distance from the light to the grey card, so this will be easier if the camera is stationary.

***

## Take Measurements <a href="#capturingacalibrationimage-takemeasurements" id="capturingacalibrationimage-takemeasurements"></a>

### Light to Grey Card

Measure the distance from the Light to the Grey-Card. This can be done by holding a piece of string from the light to the subject, and marking the ends, then measuring it with a ruler.

If you have multiple lights, you only need to measure the distance to one light, as they should all be a similar distance from the Grey Card if they are positioned rotationally symmetrically around the camera.

### Sensor to Light

Marso Measure also requires the position of each light relative to the sensor on the camera. The sensor is located in the centre of the lens, aligned with a mark ϕ on the body of the camera.

<figure><img src="/files/SVZdYayY3I97KtEdRXjn" alt="" width="319"><figcaption></figcaption></figure>

The Light position needs to me measured in each dimension (<mark style="color:red;">X</mark>, <mark style="color:green;">Y</mark>, <mark style="color:blue;">Z</mark>), rather than straight line distance.&#x20;

<figure><img src="/files/QEBk1V85tW4x4oIqlkZL" alt="" width="188"><figcaption></figcaption></figure>

If you are using a Ring Flash, measure to the centre of the ring.

{% hint style="success" %}
Make a note of all of these measurements. You will need them to calibrate Marso
{% endhint %}

***

## Optimal Camera Settings <a href="#capturingacalibrationimage-optimalcamerasettings" id="capturingacalibrationimage-optimalcamerasettings"></a>

For best results, it is recommended to shoot -2.5 stops underexposed when spot metering on a middle grey card (50%). An under-exposed image will preserve the specular highlights, whilst maintaining a good amount of the shadows.

{% hint style="success" %}
The exposure settings used for calibration must also be used for any future scanning sessions, otherwise a new calibration will be required
{% endhint %}

***

## Capture Image <a href="#capturingacalibrationimage-captureimage" id="capturingacalibrationimage-captureimage"></a>

Once an exposure value has been identified, take a **RAW** photograph. Save it with a descriptive name. This will be used in the Marso Measure calibration process.


# Grey Cards | Known Values

See this page to find out you % value input when setting up your exposure parameters

{% hint style="info" %}
If you are unable to find the card that you are using, please contact M-XR so that we can update the below documentation.
{% endhint %}

<table><thead><tr><th align="center">Manufacturer</th><th align="center">Product</th><th align="center">M-XR Values</th><th align="center">Product Website</th><th data-hidden></th></tr></thead><tbody><tr><td align="center">datacolor</td><td align="center">Spyder Checkr 24</td><td align="center"><a href="/pages/OteZfPKyifFnALWI3aXK">Values Here</a></td><td align="center"><a href="https://www.datacolor.com/spyder/products/spyder-checkr-photo/">website</a></td><td></td></tr><tr><td align="center">datacolor</td><td align="center">Spyder Checkr 48</td><td align="center"><a href="/pages/OteZfPKyifFnALWI3aXK">Values Here</a></td><td align="center"><a href="https://www.datacolor.com/spyder/products/spyder-checkr/">website</a></td><td></td></tr><tr><td align="center">X-Rite</td><td align="center">ColorChecker Passport Photo 2</td><td align="center"><a href="/pages/MRFVrWEgfayXXnc50zsc">Values Here</a></td><td align="center"><a href="https://www.xrite.com/categories/calibration-profiling/colorchecker-classic-family/colorchecker-passport-photo-2">website</a></td><td></td></tr><tr><td align="center">X-Rite</td><td align="center"><p>ColorChecker® Classic</p><p>ColorChecker Classic Mega</p><p>ColorChecker Classic Mini</p><p>ColorChecker Classic Nano</p><p>ColorChecker Classic XL</p></td><td align="center"><a href="/pages/MRFVrWEgfayXXnc50zsc">Values Here</a></td><td align="center"><a href="https://www.xrite.com/categories/calibration-profiling/colorchecker-classic">website</a></td><td></td></tr></tbody></table>


# Spyder Checkr | Datacolor

See this page for percent values is you are using the Spyder Checkr

{% hint style="info" %}
For optimal results, we recommend using the large middle grey tile.
{% endhint %}

<div align="center" data-full-width="true"><figure><img src="/files/2Ni36UnbcqlIVzc2M9fo" alt="" width="255"><figcaption></figcaption></figure> <figure><img src="/files/6JCzF99REMvLGf50iuXm" alt="" width="188"><figcaption></figcaption></figure></div>

<table><thead><tr><th align="center">ID</th><th width="245.0234375" align="center">Value %</th><th align="center">ID</th><th align="center">Value %</th></tr></thead><tbody><tr><td align="center">1E</td><td align="center">95%</td><td align="center"><strong>Middle</strong></td><td align="center"><strong>28%</strong></td></tr><tr><td align="center">2E</td><td align="center">59%</td><td align="center"></td><td align="center"></td></tr><tr><td align="center">3E</td><td align="center">36%</td><td align="center"></td><td align="center"></td></tr><tr><td align="center"><strong>4E</strong></td><td align="center"><strong>19%</strong></td><td align="center"></td><td align="center"></td></tr><tr><td align="center">5E</td><td align="center">8%</td><td align="center"></td><td align="center"></td></tr><tr><td align="center">6E</td><td align="center">2%</td><td align="center"></td><td align="center"></td></tr></tbody></table>


# ColourChecker Passport Photo 2 | X-Rite

See this page for percent values is using the ColourChecker

{% hint style="info" %}
For optimal results, we recommend using the medium grey tile 3A.
{% endhint %}

<figure><img src="/files/Vb3XM32OVe17uVa8VUS4" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th align="center">ID</th><th align="center">Value % (Linear)</th><th data-hidden></th></tr></thead><tbody><tr><td align="center">1A</td><td align="center">3%</td><td></td></tr><tr><td align="center">2A</td><td align="center">9%</td><td></td></tr><tr><td align="center"><strong>3A</strong></td><td align="center"><strong>19%</strong></td><td></td></tr><tr><td align="center">4A</td><td align="center">35%</td><td></td></tr><tr><td align="center">5A</td><td align="center">58%</td><td></td></tr><tr><td align="center">6A</td><td align="center">90%</td><td></td></tr></tbody></table>


# Advanced Exposure Calibration

The Advanced Exposure Solve allows Marso Measure to calculate an accurate exposure compensation directly from a photogrammetry reconstruction. This allows precise exposure calibration.

### Why complete an advanced exposure calibration?&#x20;

This process helps with maintaining colour accuracy and an even exposure.

### **Prerequisites**

Before starting, ensure you have:

* A **colour checker,** check compatible colour checkers [here](/marso-measure/resources/capturing-a-calibration-image/grey-cards-or-known-values)
* Your **chosen lighting preset** configured
* Final **camera settings** locked in (shutter speed, ISO, aperture)
* A capture space with **textured surfaces and markers** for a clean photogrammetry solve

***

### **Notes & Best Practices**

* Always use **consistent lighting** between calibration and real captures
* Recreate the exposure solve whenever lighting presets or camera settings change
* Ensure the grey tile mesh is smooth and evenly reconstructed - clean the tile before capturing if there are any scuffs or marks on the grey tile you want to capture
* Use plenty of markers to guarantee scale accuracy

***

### **1. Capture your grey card**

The goal is to create a high-quality reconstruction of the grey tile under your chosen lighting conditions.

{% hint style="success" %}
Use a flat, detailed surface **on the ground** and surround the chart with **markers and measurements** for alignment accuracy.
{% endhint %}

### **1. Capture**

1. **Set the lighting and camera exposure**\
   Use the exact lighting strength, flash mode, and exposure settings you intend to use in production captures.
2. **Top-down orthographic pass**\
   Capture the colour checker in a grid pattern from above.
   * Purpose: the grey value should be lit evenly from all frontal angles.
3. **Ring formation pass**\
   Capture the colour checker in a circular sweep at multiple heights.
   * Purpose: to provide data from different incidence angles for a more robust 3D solve.

#### Example capture&#x20;

{% hint style="info" %}
You will see on the image below, we have placed the colour card on a pair of jeans with detail that helps align the mesh. You can use any object that has enough detail, avoid glossy or featureless floors.
{% endhint %}

![](/files/AblMmimcM4q0ZeE1gqiM)

***

### **2. Process the Images Through Marso Measure Develop**

Once all photos are captured:

1. Run the images through **Marso Measure Develop step**\
   → this converts the raw files into a format suitable for your photogrammetry software.

***

### **3. Create a Mesh of the Colour Checker**

Import your processed images into your photogrammetry software (Metashape or Reality Capture).

#### **Steps**

1. Solve alignment
2. Build the dense cloud and mesh
3. Use markers and scale bars for maximum accuracy
4. Ensure the colour checker surface is reconstructed cleanly

***

### **4. Isolate the Grey Tile**

The Advanced Exposure System requires a **mesh containing only the grey tile**.

#### **How to Isolate**

**Metashape:**

* Select the grey region using the bounding box
* Right-click the mesh → **Duplicate**
* **Clip by Region** to isolate the patch

**Reality Capture:**

* Use:\
  `Scene 3D > Tools > Mesh Model > Cut by Box`

***

### **5. Export Required Files**

Export the following from your isolated grey tile:

| File Type          | Purpose                                   |
| ------------------ | ----------------------------------------- |
| **Alembic (.abc)** | 3D mesh of the grey square                |
| **ST Map (EXR)**   | Lens distortion map from solve            |
| **PNG UV Mask**    | Isolates the grey patch during processing |

***

### **6. Create the Advanced Exposure System in Marso Measure**

If you haven’t already, [create a **Light System** for your light](https://docs.m-xr.com/marso-measure/resources/creating-a-light-system)

Then, in Marso Measure, navigate to:

**Exposure Systems → New Exposure System → Toggle from “Basic” to “Advanced”**

<div align="left"><figure><img src="/files/5jp0G1NTKgfnH17nUm4i" alt=""><figcaption></figcaption></figure></div>

***

### **7. Configure the Advanced Exposure System**

Fill in the following fields:

#### **Exposure System Name**

Use a clear naming scheme including camera model + exposure + light preset.\
e.g.,\
`A7R4_ISO100_F11_1/125_PtLight70%`

#### **Light System**

Select the light system previously created for your rig.

#### **Raw Calibration Image(s)**

Raw images used for the colour checker photoscan.

#### **Raw Image Extension**

#### **Colour Card Mesh File**

The Alembic mesh of the isolated grey tile.

#### **Reconstruction Tool**

Photogrammetry tool used:

* Metashape
* Reality Capture

#### **ST Map File**

EXR export from your grey square mesh.

#### **Colour Card UV Mask**

PNG mask defining the grey region.

#### **Grey Value**

Decimal place of the percentage of the grey value of your selected grey tile.\
Reference values can be found [here](/marso-measure/resources/capturing-a-calibration-image/grey-cards-or-known-values).

<div align="left"><figure><img src="/files/Hbz83xBLKuU6dxHi9HLi" alt=""><figcaption></figcaption></figure></div>

***

### **8. Finalise the Exposure System**

Click **Create Exposure System**\
→ Marso will now use the 3D geometry and lighting information to accurately calculate grey values across your capture workflow.


# Creating an Exposure Calibration

Follow the steps on this page when creating an exposure preset for Marso Measure.

{% hint style="warning" %}
To create an exposure preset, you will need to capture a photo of a calibration grey card under similar conditions to how you will capture any subjects. See [Capturing a Calibration Image](/marso-measure/resources/capturing-a-calibration-image).
{% endhint %}

1. Click Exposure Systems on the left side of Marso Measure.
2. Click New Exposure System in the top right corner.
3. Fill in the information in the Create Exposure System area, give it a meaningful system name, include your [calibration image](/marso-measure/resources/capturing-a-calibration-image), the distance from the flash to grey card and [grey value](/marso-measure/resources/capturing-a-calibration-image/grey-cards-or-known-values).
4. Click Create.

<div align="left"><figure><img src="/files/JugHiXQcWO5f1w9ct2hP" alt="" width="563"><figcaption></figcaption></figure></div>

5. After a short delay a new window will be launched with the calibration image shown.
6. Click and drag to create a selection box on the image. Select the region corresponding to the grey value given.

{% columns %}
{% column %}

<div align="left"><figure><img src="/files/z91bUpRLCPDmCFcQMMTb" alt="" width="375"><figcaption></figcaption></figure></div>
{% endcolumn %}

{% column %}
{% hint style="info" %}
If you are unable to see the grey card to make a selection, use the hotkeys to adjust the brightness.

**W/S** - Key to make the preview image brighter or darker.\
**R** - To reset the brightness

This is just for preview purposes and does not affect the final calibration.
{% endhint %}

{% endcolumn %}
{% endcolumns %}

6. Press Enter to Confirm the selection.
7. The calibration tool will then run in the background. This may take up to 10 minutes depending on your system and the resolution of your input images. When it is complete the adjusted image will be shown for confirmation. It should appear balanced, and slightly under-exposed.

<div align="left"><figure><img src="/files/zuKze1p9YWYZ9bMPvGZy" alt="" width="375"><figcaption></figcaption></figure></div>

8. After pressing Enter to accept the adjusted image, you will be returned to Marso Measure. The new exposure preset will be available in the list.


# Creating a Light System

Follow the steps on this page when creating a light system for Marso Measure.

{% hint style="warning" %}
The Light System preset describes the location of you light(s) **relative to the camera sensor**. If you have multiple lights, the Light System preset also describes the order that lights will be triggered in when capturing.
{% endhint %}

1. Click Light Systems on the left side of Marso Measure.
2. Click New Light System in the top right corner.
3. Give your Light System a meaningful name.
4. In order of how lights will be triggered, add the lights in relation to the camera sensor. Be sure to measure carefully with a ruler and input your lights in the necessary axis. Simply click Add Light after you put light information in to the X, Y or Z axes.
5. Once each light is created (or one if you have a one light system), click create. Your light system should now be visible.

{% hint style="info" %}
If you are using a Ring Flash, leave the X and Y axes as 0. Measure forward from the camera sensor to where the Ring Flash sits and input this figure into the Z axis.
{% endhint %}

<div align="left"><figure><img src="/files/FL0U0LkQCj1c4ZebDH8F" alt="" width="563"><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/hTpnKvMpnTbddmrwGznS" alt="" width="563"><figcaption></figcaption></figure></div>


# Photogrammetry Tips

Tips for specific Photogrammetry Software

* [Agisoft Metashape](/marso-measure/resources/photogrammetry-tips/agisoft-metashape)
* [Reality Capture](/marso-measure/resources/photogrammetry-tips/reality-capture)


# Agisoft Metashape

If you are using Agisoft for photogrammetry, please follow this page for guidance.

## Scaling

<details>

<summary>Agisoft Metashape | Standard</summary>

Agisoft Metashape Standard does not offer a way to automatically set scale. For best practice, we recommend using [Blender](https://www.blender.org/download/) (a free 3D application) to do this by hand.

{% hint style="info" %}
You will require an Alembic file that includes cameras & a UV unwrapped mesh.
{% endhint %}

Open a new ‘General’ blender scene and delete all of the default objects, your scene should look like this:

<img src="/files/JZY5TE5ybcFCrWol4GWy" alt="" data-size="original">

To Import an Alembic file : `File -> Import -> Alembic`

<img src="/files/4E9XZlnABDXiHJrYNDdw" alt="" data-size="original">

<img src="/files/ktDq1SLKbYGrLgdt1pUm" alt="" data-size="original">

After importing, the mesh and cameras should be in your scene. Create an empty object, this will be used to apply the same scale to the mesh and all the cameras:

<img src="/files/lczhJvnzO8q6AVpuqPrC" alt="" data-size="original">

Select everything except the ‘Empty’:

<img src="/files/EJ0HURkVOJbHAZBisbDf" alt="" data-size="original">

Then Shift+Drag the selected items into the empty:

<img src="/files/bLc2LxyHkdkMEp4RJYA5" alt="" data-size="original">

It should look like this:

<img src="/files/winaQFRhXOExd677YrTH" alt="" data-size="original">

Using the measure tool (Shift+Spacebar, M), hold Ctrl to snap the tool to two points in the mesh, like so:

<img src="/files/73edHOxQ2Hui8hFmC66k" alt="" data-size="original">

\
Then compare this distance to the real life distance. If you divide this distance by the real life distance you end up with a scale factor.&#x20;

On the object properties menu for the ‘Empty’, insert the computed scale factor into the three scale input boxes:

<img src="/files/fHPEgzRNyonl5eET81Pw" alt="" data-size="original">

Use the measure tool again to confirm the distance is now correct.

Now select all cameras and the mesh, press Alt+P to bring up the Clear Parent dialog, and select Clear and Keep Transformation:

<img src="/files/EuvjMRfToDbqJoT2bTay" alt="" data-size="original">

Delete the ‘Empty’ from the scene, your outline should only have the cameras and mesh now:

<img src="/files/j5uGIgECzHjjMJ3dqOiN" alt="" data-size="original">

Now export the scaled alembic:

<img src="/files/qfCOE9lOOd9cZZHg7DbG" alt="" data-size="original">

<img src="/files/Ji22ywGEq2Z8NetDS5wQ" alt="" data-size="original">

This scaled alembic is the one you want to select during the run dialog in Marso.

</details>

<details>

<summary>Agisoft Metashape | Pro</summary>

Scaling can be done quite easily by using markers and setting a scale bar.

</details>

## Exporting

{% tabs %}
{% tab title=" Exporting Alembic" %}
To export an alembic from Agisoft:&#x20;

1. Go to file.
2. Go down to export, then click on export model.&#x20;
3. Select a name and press save.

After pressing save, an export model window will appear.

{% hint style="warning" %}
You must enable vertex normals and cameras, your settings should look like the below images.
{% endhint %}

<figure><img src="/files/ISe4ytI6zANwIErLdjuT" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/MbPha7Pg89OV3fd3Pvef" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Exporting ST Map" %}
In Agisoft Metashape, by default, all cameras should solve into a single group resulting in them all sharing the same lens distortion profile.

To export an ST Map:&#x20;

1. Go to tools.&#x20;
2. Go down to camera calibration.
3. You should see a single-camera group on the left pane (see below for an example).

<figure><img src="/files/4W4y5gOHAN4JRKWqEeXp" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="danger" %}
If you have multiple camera groups within your scene with different camera solves, Marso will not work.
{% endhint %}

4. Switch from the 'initial' to the 'adjusted' tab.

<figure><img src="/files/GXSI6tfo9OmlYdg7OAcd" alt="" width="317"><figcaption></figcaption></figure>

5. Set the save type as 'STMap (\*tif\*.exr)'. Type in a meaninful file name such as 'Lens\_Profile'. By default, the extension of the file will be ‘.tif' , **ensure** that this is changed to ‘.exr’.

<figure><img src="/files/toI5FrMjaWkqsM2MPm9w" alt="" width="236"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}


# Reality Capture

If you are using Reality Capture for photogrammetry, please follow this page for guidance.

## Scaling

This can be done quite easily by using markers and setting a constraint, then updating the alignment to apply the constraint.

## Exporting

{% tabs %}
{% tab title="Exporting Alembic" %}

1. Go to exports.
2. Make sure the settings are the same as the ones in the screenshot below.

{% hint style="warning" %}
Be sure to enable normals when exporting your alembic.
{% endhint %}

<figure><img src="/files/4rtP7G8cQ10lLjKGfIpf" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Exporting CSV" %}

1. Go to exports.&#x20;
2. Go to camera alignment, select `OpenCV-compliant Internal/External Camera Parameters`&#x20;

<figure><img src="/files/y5Wez3f8iGBBNawbXA6F" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Legacy - Exporting ST Map " %}

1. Go to exports.&#x20;
2. Make sure the settings are the same as the ones in the screenshot below.

<figure><img src="/files/nUOgZiIc9sbgUdAMbraZ" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}


# Marso Measure & Reality Scan - Cross-Pol or Sprayed workflow

Follow this page if you would like to use cross-polarisation or scanning spray.

### Capture

1. Initially capture your dataset following Marso Measure's [capture guidelines](/marso-measure/getting-started/capture).

{% hint style="success" %}
Shoot in RAW

Get a good equal coverage of cameras, making sure to capture the top and bottom of the asset

Keep your camera settings consistent throughout your scan
{% endhint %}

2. Then spray your object in scanning spray, and capture the object again. This time you can capture in JPG, making sure the capture is evenly exposed. You do not need to follow the Marso Measure capture technique in this instance, it can simply be how you would usually get a good photogrammetry scan.

{% hint style="danger" %}
The subject should not move between captures and the same markers should be visible - do not spray the markers.
{% endhint %}

***

### Develop

1. Follow the [Develop step](/marso-measure/getting-started/create-job#develop-configuration) in Marso Measure to develop the RAWs for Reality Scan, if you have a shiny object, more brightening may be required when following this step.

***

### Processing in Reality Scan

#### Alignment

1. Bring both the sprayed images and the Marso Measure images to RS, detect markers with a minimum of 10 measurements and align.

<div align="left"><figure><img src="/files/gCjyt4UcR7apHOcAaCwx" alt="" width="375"><figcaption></figcaption></figure></div>

2. Both datasets should align together at this stage.
3. Define a known distance between 2 control points. These could be 2 markers.
4. Remove any control points with poor measurement accuracy, or remove all control points except those required for scaling if you feel you will get a nice alignment second time round based on your first effort.
5. Align again.&#x20;

#### Meshing and Preparing

1. Set the recon region for meshing.
2. Now only select the Marso Measure images and not the sprayed ones.

{% hint style="info" %}
To complete step 2, head to the console and use `-selectImage g/photo/`
{% endhint %}

3. Disable those images for meshing. If you do not have scanning spray and are only using cross-polarisation, skip this step and use all images for meshing.
4. Set the reconstruction region for meshing and mesh in normal detail.
5. Clean up mesh and make mask mesh if necessary.
6. Simplify and smooth mesh.
7. Unwrap mesh to a single 8k texture.

#### Export

{% hint style="warning" %}
Select only Marso Measure cameras again, using `-selectImage g/photo/`
{% endhint %}

1. Export the alembic.
2. Make sure only Marso Measure cameras are used again, then export your ST maps.


# Re-Scaling an alembic with Blender

Follow this page if you want to re-scale with Blender.

1. Import your alembic.

<div><figure><img src="/files/MUYOuf4jIDX6fP7tu76E" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/JiUjabaHZyLYI78p2oDe" alt="" width="386"><figcaption></figcaption></figure> <figure><img src="/files/9VShsq9Smu6m1IJuCQwM" alt="" width="563"><figcaption></figcaption></figure></div>

2. Parent cameras and model under an empty object.

<div><figure><img src="/files/QSFWrcucSNgdP4tHOgYF" alt="" width="258"><figcaption></figcaption></figure> <figure><img src="/files/N62OXID29RvAifBA0aR7" alt="" width="246"><figcaption></figcaption></figure> <figure><img src="/files/S2OP8kGaPYpnCzY4rK9j" alt="" width="235"><figcaption></figcaption></figure></div>

3. Measure size of model and calculate scale factor.

<div><figure><img src="/files/31EYDh2KPmLVEMybg4NO" alt="" width="283"><figcaption></figcaption></figure> <figure><img src="/files/62uXdgKLHdXSvvCMD3ii" alt="" width="247"><figcaption></figcaption></figure></div>

4. Select all cameras and model. Then clear parent and keep transformation.

<div><figure><img src="/files/REcswZ5usTcVtE0IjeEn" alt="" width="249"><figcaption></figcaption></figure> <figure><img src="/files/8LeI01kzf4vURnhMUzMa" alt="" width="329"><figcaption></figcaption></figure></div>

5. Export alembic.

<div><figure><img src="/files/xYmr576LxA1uGsqg79aa" alt="" width="360"><figcaption></figcaption></figure> <figure><img src="/files/x8QVguQ7mm90fMgIb2wM" alt="" width="563"><figcaption></figcaption></figure></div>


# Multiple Machines

Follow this page if you are going to be using multiple machines.

Your M-XR Account can be used to access Marso Measure from multiple machines, however **only one can be activated for using Marso Measure at a time**.

The first time you log in to a new machine, you will be prompted to activate it, this will deactivate your previously active machine. The system settings will also need to be set per machine.

Your presets will then be available to you, across any machine.&#x20;

{% hint style="danger" %}
Activating another machine while a job is processing may cause unexpected behaviour on both machines.&#x20;
{% endhint %}

***

## Sharing Jobs

Jobs can be accessed from any machine logged into your account.&#x20;

Jobs can only be processed or exported if the raw photography is available at the same path as it was when the job was created, and the scratch directory is shared.


# Advanced features

Follow this page for information regarding advanced features.

## CLI Command Reference

Marso Measure supports a Command Line Interface (CLI) for use in programmatic workflows where a GUI would be undesirable.&#x20;

A number of subcommands are available for querying, creating, configuring, and executing jobs. These commands can be chained together into a single invocation as required.

### Subcommands

```
logout       Logout from the current account
login        Login to an account
activate     Activate the current machine for processing with Marso
configure    Configure the application settings
status       Show current system status
models       Interact with available models and their details.
job          Manage jobs in the Marso Processing Service
queue        View and manage the processing queue
lights       View available light systems
exposures    View available exposure presets
```

All sub-commnds can be run with initial options to control the console behaviour:

```
-q,--quiet      Suppress all terminal output
-v,--verbose    Enable Verbose logging
-V,--trace      Enable Trace logging
```

E.g. No console output, trace logs in the log file:

```
M-XR_Marso_CLI.exe -q -V login
```

#### Configure

```
M-XR_Marso_CLI configure --scratch-path <path> show
```

Sets the scratch directory for the current machine. This is where temporary files will be stored during processing. It is recommended that the scratch directory is on a drive with fast R/W speeds to improve processing times, and has 250 - 750GB of available space, depending on the resolution you wish to process at.

The `show` option displays the current configuration after it has been set.

#### Job

The job command is used to control jobs and has several subcommands:

```
list          List all available jobs
create        Create a new job
deactivate    Deactivate the currently active job
delete        Delete a job
activate      Activate the current job for use with future commands
lights        Set the lights for a job
exposure      Set the exposure for a job
prepare       Prepare Job for geometry solve
process       Execute Marso Processing for the Job
export        Export the textures predicted by a job
```

Some common command combinations are listed below.

***

Create a new job, set it as the currently active job for future commands, set the light system, and execute the prepare step to create images for photogrammetry.

```
M-XR_Marso_CLI.exe job create --name <name> --raw-folder <path> activate lights --add-light 0 0 0.2 prepare --file-type .exr --output-path <path>
```

After this the job will have been created, and photogrammetry can be done with the files produced by `prepare`.

***

Set the exposure for a job. The job id must be specified if there is no active job.

```
M-XR_Marso_CLI.exe job exposure --calibration-raw-file <path> --distance <value> --grey-value <value>
```

***

Process a job. The job id must be specified if there is no active job.

```
M-XR_Marso_CLI.exe job process --abc <path> --st-map <path> -r <resolution> --models <model1> <model2>
```

***

Export the textures predicted by a job. The job id must be specified if there is no active job.

```
M-XR_Marso_CLI.exe job export --output-path <path> --file-type <file_type>
```

Export also has a `list` subcommand to list the available exports, as each model must be exported individually if the process stage was run with multiple models.

Previous runs of the job can also be re-exported by specifying the `--previous-run` option with the number from the `list` row.


# Marso Measure Processing Options

This page will assist you in selecting processing options for Marso Measure.

### Capture Methods

**Multi-Viewpoint** = Freehand, Turntable, Lightstage, Robot Controlled.

### Generation

**Gen 1.0** = Works well for most scans, does require a high coverage count and well aligned camera poses.

**Gen 2.0** = Improves results for freehand scans that have low image overlap, increased material clarity. Only available for the Narrow Material Gamut.

**Gen 1.1** = Gen 1.1 brings meaningful improvements to material accuracy across the board. The model now more reliably distinguishes between metallic and non-metallic surfaces, produces more consistent roughness values, and outputs stronger normal maps. Colour reproduction has also been improved.

### Material Gamut

**Wide** = A wider gamut of materials, including reflective and colour metals. Good quality but less accurate then the narrow material gamut.

**Narrow** = Fine-Tuned on a narrow gamut of materials, not including metals. Great for leathers, woods and plastics e.g Shoes & Furniture.

**Combined** = Combined gamut of materials, including metals. Good ability to distinguish between metals and non-metals. Our most accurate model.

## Understanding Materials Gamuts

### What is PBR?

PBR-material-properties can describe a wide range of physical materials, ranging from the simple leathers, woods, and all the way through to complex physical materials such as metal chromes, copper, and shiny coloured nylons.

### Two Principal Shaders&#x20;

PBR generally describes two main workflows: a Specular-Workflow or a Metallic-Workflow. They both aim to do roughly the same thing, but are built for slightly different use cases.

The **Specular Workflow** can describe far more materials at the cost of having to store more data, and being slightly less intuitive for artists. It has a coloured specular texture, which is able to describe both matte objects, glossy surfaces, and transition all the way up to metal objects within a 0-1 range.

The **Metallic Workflow** is a simplification of the specular-workflow, aimed at being more data efficient and artist-friendly. The metallic-workflow, uses a greyscale texture map which is often binary, to describe if the surface is a metal or a non metal. In contrast to the specular workflow which uses a coloured texture map to describe the full scope of both metal and non-metals, with a transition occurring somewhere along this range.

For this reason, a specular-workflow covers more of the potential material property space than the metallic-workflow, whilst being able to be converted into mapped into a metal shader.

{% hint style="success" %}
Marso Measure, by default, authors material textures into both workflows simultaneously making it easy to plug into a variety of different 3D applications.
{% endhint %}

### &#x20;How Marso Measure handles complex and easy material types

Marso Measure has been designed to capture as many material types (real world) as possible, and M-XR’s researchers are continuing to push the bounds of what Marso Measure can acquire!

Think of all these possible materials as a spectrum of space, similar to a colour space, and M-XR’s ambitions with Marso Measure is to capture as wide of a gamut of this space as possible.<br>

<p align="center"><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXeziXUX9L2dm_zF1Q0kj2x1rCnBzdkOBk3O8olGykIfCDrDsQsjwIogLvJHqI8IHFKYf2kPdTvQRwjqP9hfsdQthDUzm_vNZK-O9MtfNgRe42zq1I8u9ZQwb8how2UkMCNv8zBf?key=ZzJcxF6O2KnDiALQ7jAjHg" alt=""></p>

\
Marso Measure is capable of capturing quite a wide-gamut of this material space, to offer more photorealistic objects with unique properties. However, this makes the challenge of identifying materials much harder. This can sometimes lead to subtle inconsistencies in some of the material properties, notably roughness.

{% hint style="warning" %}
To mitigate this, and give our users more control, Marso Measure offers the option to select between two different material Gamuts : Wide and Narrow, depending on your scan and use case.
{% endhint %}

<p align="center"><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXeMtiRG_CYLDRID_5bvZH8ILsGOUWl2qg6B-7B_wPxGoKbvmPYCJvePzb4KMDDjdjqpdJSk7ayyr6QpkIVWvcuZaNHJ9c0fUY6EOC64Qatl6hVUpOvuVIlZpshFfC2GaGaj3G4L?key=ZzJcxF6O2KnDiALQ7jAjHg" alt=""></p>

### &#x20;Narrow vs Wide Gamuts

Whichever gamut you select, you can still use these in a metallic or specular workflow.

{% tabs %}
{% tab title="Narrow Gamut" %}
Capable of measuring all the materials very confidently within a slightly narrower gamut of this potential material space such as leathers, plastics, fabrics, woods, ceramics. What it cannot do is capture material outside of this range as they start to become metals.
{% endtab %}

{% tab title="Wide Gamut" %}
This is capable of capturing much further into this potential material space, which includes all of the narrow-gamut materials in addition to: silver metals, coppers, pearls and many more.
{% endtab %}

{% tab title="Combined Gamut" %}
Combined gamut of materials, including metals. Good ability to distinguish between metals and non-metals. Our most accurate model.
{% endtab %}
{% endtabs %}

### Tips & Tricks for suggested workflows

If you are unsure which Gamut to use, then it is best to just use both. Exporting for both wide and narrow doesn’t create a huge overhead for Marso, maybe an extra \_\_ minutes or \_\_% of additional processing time.

Often, when predicting on a Wide Gamut, our users will find that swapping the roughness and normals for the ones from the narrow gamut gives the best results.<br>


# Common Issues

Common Issues can be found below.

Find here a list of common issues people encounter and how to resolve them. Error messages are shown below, if your error message matches up to any below, please see the resolution. If the issue persists, reach out to <support@m-xr.com>.

***

#### Uninstall Process <a href="#issue-rc-or-agisoft-alembic-export-error" id="issue-rc-or-agisoft-alembic-export-error"></a>

There is a small problem with the uninstall/install process when a certain uninstall workflow is followed. The recommended workflow for uninstalling successfully is below:

1. Close down all Marso Measure related tasks in task manager.
2. Go to programs on your system, find Marso Measure click the three dots on the right hand side and click uninstall.
3. Wait for the uninstall process to finish.
4. Reinstall the new version.

{% hint style="warning" %}
If you are unable to uninstall, you can use a tool like Revo Uninstaller or CCleaner.
{% endhint %}

We hope to have this completely fixed in a coming release.

***

#### Issue - RC or Agisoft Alembic Export Error:  <a href="#issue-rc-or-agisoft-alembic-export-error" id="issue-rc-or-agisoft-alembic-export-error"></a>

```
[ERROR  ] module 2/5 process.pipeline.transform.gl_uv_reprojection failed: 
RESULT: 1
OUTPUT: 
Pinged your deployment! You successfully connected to MongoDB!
STDERR: 
[tid:  15252][W] Logging to '%LOCALAPPDATA%\M-XR\Maestro\Logging\gl-uv-reprojection\gl-uv-reprojection_20250205-025816.log', use argument --print to log to console
[tid:  15252][C] Cannot extract a number from: 00011.png
```

#### Resolution: <a href="#resolution" id="resolution"></a>

This is usually something to do with your export settings in your photogrammetry software, please follow our [export configuration](https://f005.backblazeb2.com/file/maestro-external-releases/confluence_files/reality_capture_1.4_alembic_export_settings.xml) if using Reality Capture or this [Agisoft](/marso-measure/resources/photogrammetry-tips/agisoft-metashape) page in our docs.

***

#### Issue: <a href="#issue-prepared-jpeg-data-for-photogrammetry-looks-high-contrast" id="issue-prepared-jpeg-data-for-photogrammetry-looks-high-contrast"></a>

Prepared JPEG Data for photogrammetry looks high contrast.

#### Resolution:  <a href="#resolution-.1" id="resolution-.1"></a>

Currently for the jpeg based workflow brightness control is the only setting offered.

You can use the EXR workflow and edit the contents of the EXR (brightness, contrast, LUT, color space, tone mapping). However it is extremely important the filename, resolution, aspect ratio and orientation are preserved exactly.&#x20;

We don't use the pixel values in the photogrammetry images so you are free to adjust them in any way to help your photogrammetry.

***

#### **I**ssue - Connection to database:  <a href="#issue-connection-to-database" id="issue-connection-to-database"></a>

```
STDERR: 
[tid: 6720][W] Logging to '%LOCALAPPDATA%\M-XR\Maestro\Logging\Gursky\Gursky_20250131-090325.log', use argument --print to log to console
[tid: 6720][C] DB Error: MongoDB connection error: Could not establish stream for node ac-tzeqt5t-lb.v93b8wz.mongodb.net:27017: [socket timeout calling hello on 'ac-tzeqt5t-lb.v93b8wz.mongodb.net:27017']: generic server error
```

#### Resolution: <a href="#resolution-.2" id="resolution-.2"></a>

This is quite likely an antivirus/security software blocking access. You may also see the Windows Security Smart Card pop up at this point. Please see this page and follow the necessary steps to solve the issue.

***

#### Issue:

&#x20;IIQ images not working for exposure calibration.

#### Resolution:&#x20;

We are working on a resolution for this.

***

#### Error:&#x20;

\[C] CheckGLR: No models in scene for contributing to memory calculation!

#### Resolution:&#x20;

This likely means there was no mesh exported in the alembic file, be sure to re-export with the [correct settings from your chosen photogrammetry software](/marso-measure/resources/photogrammetry-tips). You can find the export settings for Reality Capture under the [photogrammetry page](/marso-measure/resources/photogrammetry-tips/reality-capture#exporting-alembic) in our docs.

***

#### Error:&#x20;

\[W] Cannot find source photo in source directory

#### Resolution:&#x20;

This quite likely means that your RAW image dataset has been moved or deleted. In the Marso Measure process step, the software will look for your RAW files in the same path you configured in the develop step, so be sure to keep the folder in the same location and do not delete it.

***

#### Error:&#x20;

\[C] Fatal Error: Mesh polycount and size of textures exceeds available VRAM! Possible fix is reduce polycount by: 0

#### Resolution:&#x20;

This is quite likely to Marso Measure not fully utilising the GPU on your system, to fix this please do the following:

1. **Go to Settings → System → Display**
2. Scroll → **Graphics**
3. Add the Marso Measure app:
   * Desktop app → Browse → select the `.exe`
4. Click the app → **Options**
5. Set to:

   ```
   High performance (Your GPU)
   ```
6. Save and restart the app.

{% hint style="danger" %}
Please note, to run Marso Measures Gen 2.0 model, you need an Nvidia GPU.
{% endhint %}

***

#### Error:&#x20;

Fatal Error: There are more frames in the scene than frames in the scan: 195 > 5

#### Resolution:&#x20;

This means there is a mismatch between the camera count in your alembic file and the amount of images in your RAW image dataset **when the job was created**, these need to match up for Marso Measure to be able to process further.

***

#### Error:

The system cannot find the path specified.

#### Resolution:&#x20;

This quite likely means that your dataset has been moved or deleted. In the Marso Measure process step, the software will look for your files in the same path you configured in the develop step, so be sure to keep the folder in the same location and do not delete it.

***

#### Error:&#x20;

\[W] metadata key 'ExposureTime' values differ: 1/160 =/= 1/250

#### Resolution:&#x20;

This means that your shutter speeds do not match up, either in your RAW scan or between your calibration image you used when creating your exposure system and your RAW scan.

Marso Measure requires identical manual camera settings in your RAW scan and your calibration image.

***

#### Error:&#x20;

\[C] Cannot extract a number from: 00xxx.png

#### Resolution:&#x20;

This is usually something to do with your export settings in your photogrammetry software, please follow our [export configuration](https://docs.m-xr.com/marso-measure/resources/photogrammetry-tips/reality-capture) if using Reality Capture or this [Agisoft](https://docs.m-xr.com/marso-measure/resources/photogrammetry-tips/agisoft-metashape) page in our docs.

***

#### Error:&#x20;

\[ERROR ] Cannot start Marso Processing Server on port 18070, already in use.

#### Resolution:&#x20;

Check if a version of Marso Processing Server is is already running via Task Manager on your machine, if so terminate it. If the issue persists, please open a ticket via the button below.

***

#### Error:&#x20;

Fatal Error: Uncaught ImportError: Error importing numpy: you should not try to import numpy from its source directory; please exit the numpy source tree, and relaunch your python interpreter from there.

#### Resolution:&#x20;

There is a python virtual environment on your system interfering with Marso Measure, please clear it.

***

#### Error:&#x20;

EXR file(s) have dimensions that don't match the camera settings.

#### Resolution:&#x20;

This is quite likely an issue with your export of the ST maps from either Agisoft or Reality Capture, see the correct settings [here](/marso-measure/resources/photogrammetry-tips).

***

#### Error:&#x20;

Error invoking remote method 'alembic:open-file': IpcError: IPC\_MESSAGE\_START:Error opening alembic file: RangeError: Array buffer allocation failed

#### Resolution:&#x20;

Marso Measure is unable to preview the alembic information in the UI, you can still proceed.

***

<p align="center"><a href="https://app.m-xr.com/marso-measure/support" class="button primary">Get Support</a></p>


# Known Issues

See this page for known issues, please contact support\@m-xr.com if you cannot fix the issue.

***

### Current

* [Updater: No Authorisation method provided](#updater-no-authorisation-method-provided)
* [DLL Fault](#dll-fault)
* [Spaces in paths](#spaces-in-paths)
* [Run out of storage](#run-out-of-storage)
* [Windows Defender false positive](#windows-defender-false-positive)
* [Firewall blocked](#firewall-blocked)
* [VPN support](#vpn-support)
* [Generate Markers Crash](#generate-markers-crash)

***

#### Updater: No Authorisation method provided

<figure><img src="/files/ZJd5320DvUW95lhNaNak" alt=""><figcaption><p>Example of the Error</p></figcaption></figure>

The Marso Updater shipped with 25.1.0 had an authorisation issue that has been solved with 25.1.1

To resolve this issue, [download](https://app.m-xr.com) the latest version of the updater, copy it to your install folder, and run it directly. This should prompt you to login and install the latest version.

#### DLL Fault

Users may sometimes experience an application fault. This will not appear in the log and will look like the application has just closed without any further information. To confirm you can look in the event viewer and you should see an error like this:

```
Faulting application name: M-XR_Marso.exe, version: 0.0.0.0, time stamp: 0x67aa8eb2 
Faulting module name: tcl86t.dll, version: 8.6.2.13, time stamp: 0x6547c47c 
Exception code: 0x80000003 
```

#### Resolution

To resolve just relaunch the application and continue. If any job was running during the crash it will have to be restarted.

***

#### Spaces in paths

Currently having spaces in paths is not supported. So most steps will fail if a path includes a space. This covers calibration and processing. As a solution for the time being it is recommended to move the data to a location where there are no spaces in the path.

***

#### Run out of storage

If the scratch directory drive fills up (due to Marso or other programs) then windows will throw a Storage Warning, and jobs in Marso will fail.

If the scratch directory is on the `C:` drive and there is insufficient free space, Marso will fail to launch.

#### Resolution

To resolve you must clear space on the drive, usually we aim for 250GB of free space. Then the program can be relaunched and job can be restarted safely.

***

#### Windows Defender false positive&#x20;

Windows Defender has an AI based threat detection system that on some systems detects a portion of Marso as a threat. The threat should look like `Trojan:Script/Wacatac.B!ml`

<figure><img src="/files/cn2e6bfTdOkGVQTn61m1" alt="" width="250"><figcaption></figcaption></figure>

#### Resolution

To resolve, you will need to add an exception on this path `%LOCALAPPDATA%/M-XR/Maestro/Unpack`

If you are unable to add an exception due to security policy please contact <support@m-xr.com>

***

#### Firewall Blocked

If you have your firewall blocked and set not allow any connections then Marso will crash and will not provide a clear error. Marso requires external internet connection to run in order to connect to our DRM system.

To resolve, add a whitelist to your firewall for the Marso program and any program in this directory `%LOCALAPPDATA%/M-XR/Maestro/Unpack`

You may also need to add exclusions for the endpoints Marso needs to connect to:

1. <https://api.keygen.sh/\\>\* - HTTP/HTTPS (80/443) - License validation&#x20;
2. \*.mongodb.net - TCP ports 27015-27017 - Database&#x20;
3. \*.backblazeb2.com - HTTP/HTTPS (80/443) - Binary hosting

***

#### VPN Support

Currently based on our testing, Marso does not work with VPNs. They can tried at the user’s own risk but we do not expect them to work.

***

#### Generate Markers Crash

For Marso version 25.1.2, the Generate Markers button causes the application to crash. This, unfortunately, makes the markers inaccessible.

We have made the markers available here, whilst we work on a fix.

<figure><img src="/files/9IP6Gk9ePO3jIFmn8WuR" alt=""><figcaption></figcaption></figure>


# Contact Support

If the processing fails, check the log file listed in the details panel for an error message. Check if the error matches any of our [Common Issues](/marso-measure/help-and-support/common-issues). If you are unable to determine the cause of the failure, contact <support@m-xr.com>.

#### Collect your logs

1. Head to Settings in Marso Measure, this can be found in the bottom left corner of the application.
2. Click Support.
3. Click Create log archive, this will create a zip for you to send.
4. Email these logs to <support@m-xr.com> with full context about the errors you are seeing and what step of the process you are on.

<div align="left"><figure><img src="/files/cpZriEpw4IekFJDh1pKV" alt="" width="375"><figcaption></figcaption></figure></div>


# Processing Times

Example processing times are provided for reference. Actual times depend on many factors, so may vary.

### Processing Times

<table><thead><tr><th width="170">Export Resolution</th><th width="170">Input Images</th><th width="170">Camera Resolution</th><th width="120">Gen 2.0</th><th width="120">Gen 1.0</th></tr></thead><tbody><tr><td>1k</td><td>1273</td><td>12 MP</td><td>15mins</td><td>20mins</td></tr><tr><td>2k</td><td>725</td><td>32 MP</td><td>20mins</td><td>30mins</td></tr><tr><td>4k</td><td>1696</td><td>46 MP</td><td>1hr</td><td>1hr 30mins</td></tr><tr><td>8k</td><td>840</td><td>32 MP</td><td>3hr</td><td>6hr 30mins</td></tr></tbody></table>

***

### Benchmark system specifications:  <a href="#benchmark-system-specifications" id="benchmark-system-specifications"></a>

**OS:** Windows Server 2019

**RAM:** 128 GB (DDR4)

**CPU:** AMD EPYC 32 Core

**GPU:** 4 x RTX A5000 24 GB

**Storage bandwidth:** 3135 MB/s


# Changelog

See all version changelogs for Marso Measure below.

### Version Changelog

<details>

<summary>Version 26.1.7</summary>

* New features:
  * CSV ST Maps from Reality Scan - removes need for long EXR export and speed up processing by 20%-65% depending on scan and settings&#x20;
  * Queue management:
    * Jobs can be re-positioned in queue
    * Other queue management buttons are now all active
  * Default sort settings now let users specify which column to sort the job table by
  * Verbose logging toggle now changes log level without requiring processing sever to restart
* Performance:
  * Asset loading is improved with noticeable reduction in load times for assets over 1k

</details>

<details>

<summary>Version 26.1.6</summary>

* New features:
  * Added new model `l1-plus`&#x20;
  * Asset view:
    * Added new editing functionality for results with model `l1-plus`
    * Added new lighting options to viewer including point light and three point lighting
    * Added new histogram scope for texture display in viewer
  * Process modal:
    * Added new coverage heat map in the 3D viewer
    * Adjusted model selection table to simplify UX
    * Added ability to move divider in modal and resize elements
    * Reordered some of the details panel to improve UX

</details>

<details>

<summary>Version 26.1.5</summary>

* New features:
  * Added an experimental JPEG extraction for CR3 files to allow for preview in the develop and process modal
  * Added video tutorials on some modals, see the education button on the bottom left
  * Added learning centre with tutorials page to include in the application
* Bugfixes:
  * Fixed an issue with argument validation when creating basic exposures via CLI
  * Fixed an issue in the 3D viewer where data files would fail to parse, presenting as 'No Textures Available'
  * Fixed an issue during uninstall when users would leave the processing server running
  * Fixed an issue with the restart manager in windows failing to act

</details>

<details>

<summary>Version 26.1.4</summary>

* New features:
  * System toaster notifications on asset status change, with controllable setting
  * Support log collection button to generate a zip of your log files for support automatically
* Bugfixes:
  * Fixed an issue which would cause a process hang on systems with very high CPU core counts
  * Fixed an issue in the UI where clicking away from a modal would close the modal
* New Model:
  * Better metal/non-metal distinction
  * More consistent roughness values
  * Stronger normal map output
  * More accurate colour
  * Intended for use on all materials, but for black shiny non-metal objects it is recommended to still use the narrow model

</details>

<details>

<summary>Version 26.1.3</summary>

* Bugfixes:
  * Minor change with installer steps
  * Minor change with process completion

</details>

<details>

<summary>Version 26.1.2</summary>

* New features:
  * New PBR shader mapping in exports, works on old and new scans
  * New advanced PBR model for limited set of preview users

</details>

<details>

<summary>Version 26.1.1</summary>

* New features:
  * Login has now been moved to an external window
* Bugfixes:
  * Fixed an issue on AMD systems that would cause processing to always fail
  * Fixed an issue with processing where friendly error messaged would be replaced with error codes e.g. `[ERROR ] RESULT: 3221226505`
  * Fixed an issue with restarts on GUI triggering erroneous processing server starts, appearing as an `[ERROR ] Cannot start Marso Processing Server on port 18070, already in use`
  * Fixed an issue where logging for the GUI could not be enabled
  * Fixed an issue where certain checks in the process view would fail or not appear clearly to the user

</details>

<details>

<summary>Version 26.1.0</summary>

* New features:
  * New 3D Asset viewer with PBR display of results
  * Enhanced checking of inputs for processing
  * New welcome tour
* Minor bugfixes

</details>

<details>

<summary>Version 25.5.0</summary>

* New features:
  * New 3D viewer in UI
  * Alembic file verification check in UI before processing
  * Clearer error messages in UI reducing need to look in logs

</details>

<details>

<summary>Version 25.4.0</summary>

* New features:
  * New lights and exposure subcommands for the CLI
  * New ID options for the job subcommand for the CLI
  * Improved shader workflow mapping for export textures for both gamuts.&#x20;
* Fixes:
  * Fixed an issue where the exposure subcommand in the CLI required an unnecessary argument
  * Fixed an issue where a step in the installer would be blocked in certain IT environments

</details>

<details>

<summary>Version 25.3.0</summary>

* New features:
  * Advanced exposure creation system added to GUI and CLI
  * New navigational control for image previews in GUI
  * Filtering in tables added in GUI
  * Improved columns and added camera detail to exposure table in GUI
* Fixes:
  * Fixed an issue where automatic white balancing would occur on photography
  * Fixed an asset export error that would display even if export completed successfully in some instances
  * Fixed an issue with the loading of user's profile image
  * Fixed an issue with the Process selection dialog table filters behavior
  * Fixed an issue with the helptext in the CLI
  * Minor UI fixes

</details>

<details>

<summary>Version 25.2.0</summary>

* New, easier to navigate UI
* New Installer
* New processing options
* New generation of models available
* Introduced material gamuts

</details>

### Previous Versions

<details>

<summary>Version 25.1.2</summary>

* Bugfixes
  * Fixed Authentication issue when installing on multiple computers with the same account
  * Fixed module database connection issue affecting a small number of customers

</details>

<details>

<summary>Version 25.1.1</summary>

* Bugfixes
  * Fixed Critical authentication issue in installer

</details>

<details>

<summary>Version 25.1.0</summary>

* Bugfixes
  * In multi-light capture setups, photogrammetry images average all lighting conditions instead of using just the first
  * Pause returns jobs to the front of the queue instead of to the available pool
* Features
  * \[NEW] Transitioned from License Keys to M-XR Accounts
  * \[NEW] Configuration Presets are bound to your account, so can be shared between machines.
  * v0.1 Marso Command Line Interface
* Tweaks
  * Updated loading screen
  * Documentation overhaul

</details>

<details>

<summary>Version 25.0.1</summary>

* Features
  * \[NEW] Photogrammetry images brightness can be adjusted before they are generated, as well as their filetype and output directory.
  * \[NEW] Jobs that have already had photogrammetry images generated can regenerate them using the Develop tab in the configure dialog.
  * Added an ‘Export ZIP’ button to make it easier to collect data for support when jobs fail
* Bugfixes
  * Fixed jobs reporting Failed if the user directory contains non-ascii characters, now supports most latin languages.
  * Improved readability of some error messages

</details>

<details>

<summary>Version 24.5.4</summary>

* Workflow
  * Added a new check to processing to ensure all raw files in a job have consistent exposure settings (shutter speed, aperture, ISO), the process will error now if the values are not consistent
* Performance
  * Improved the GPU utilisation of one of the processing modules, resulting in a notable performance improvement
* Features
  * Marso and Updater are now signed with a self signed certificate (M-XR Ltd)
* Bugfixes
  * Fixed an issue where the default type filter for the ST Map explorer window would be not set correctly for RealityCapture
  * Fixed an issue where the `ESC` key would not work in the photography calibration rectangle selection window, now you can back out of the program back to the main GUI
  * Fixed an issue where the extension dropdown list would not refresh when creating a second job with the same raw images folder as the first job
  * Fixed an issue where during deletion of a job if a user very quickly selected another job during the deletion it would remove the newly selected job from the list but leave the original

</details>

<details>

<summary>Version 24.5.3</summary>

* Bugfixes
  * Fixed Marso being unable to start due to unnecessary dependency

</details>

<details>

<summary>Version 24.5.2</summary>

* Workflow
  * Photogrammetry images can be produced without creating an Exposure Params preset
  * Exposure Params Preset and Light System can be re-assigned in the configure dialog rather than being fixed after job creation
  * Jobs can now be sorted by most recent interaction
  * License key will be populated on start-up if installed with the updater
  * Marso logs will now roll-over daily instead of creating a single massive log file
* Bugfixes
  * Exposure Preset creation would hang if started while a job was running

N.B. Some Finished jobs may need to be re-configured before they can be queued again, if they were created on a previous version of Marso

</details>

<details>

<summary>Version 24.5.1</summary>

* Bugfixes
  * Fixed an issue where some RAW image files would fail to be read correctly

</details>

<details>

<summary>Version 24.5.0</summary>

* Results
  * Added new ***experimental*** Specular workflow as an optional output
  * Added new filtering to reduce artifacts from photogrammetry reconstruction
* Performance
  * Reduced storage utilisation by 40%-90% (depending on input data size)
  * Time to process scan reduced by 35%-75% (depending on input data size)
* Workflow
  * The prep stage is no longer required if the photogrammetry data is available
* Bugfixes
  * Fixed an issue where changes may be lost in settings window
  * Fixed an issue where parts of the GUI could not be resized

</details>

<details>

<summary>Version 24.4.2</summary>

* Bug Fixes
  * Fixed issue where new users could not activate their license keys
* Results
  * Improved Normals results when light offset from camera is large

</details>

<details>

<summary>Version 24.4.1</summary>

* GUI Changes
  * Added 3D viewer for previewing light positions
  * Added storage estimate for Preparation stage of Job
* Bugfixes
  * Addressed an issue with how backface were handled in the Alembic file that could cause a crash
  * Addressed an issue with how orientations of RAW files were handled
  * Addressed an issue where the row highlighting for a new light system was not working

</details>

<details>

<summary>Version 24.4.0</summary>

* GUI Changes
  * Added ability to deactivate license for moving to another machine
  * Enabled experimental 2D processing
  * Enabled option to process 3D scans at 16k on powerful enough systems
  * Added ability to specify mesh mask for 3D processing
  * Added option to choose between `JPG` and `EXR` for photogrammetry images
* Results Improvements
  * New algorithm for handling low UV resolution processing
* Bugfixes
  * Addressed a backend issue that would sometimes cause an error to hang indefinitely
  * Addressed a UI scaling issue with some Windows settings
  * Addressed an issue that would cause errors to not report correctly during the preparation stage
  * Addressed an issue where the colour space for normals in `PNG` and `JPG` was mistakingly `sRGB`

</details>

<details>

<summary>Version 24.3.2</summary>

* GUI changes
  * New queue system
    * Added ability to create multiple jobs and then run them in sequence
    * Queue supports pausing jobs and skipping job to then continue to next in queue
    * Added configuration button for handling user input after job creation
    * Added details panel to see more meta information for a job
  * Added ability to select multiple texture resolutions when configuring a job
  * Added button to see license information & details for Marso
  * Added ability to keep intermediary files in Application Settings
  * Added storage utilisation chart to Application Settings
* Results improvements
  * Added a filtering system to remove artefacts in scans with non optimal distributions
* Bugfixes:
  * Addressed crash when attempt to calibrate some Phase One RAW image files
  * Addressed issue where some submodules would hang at the end of execution rather than closing normally

</details>

<details>

<summary>Version 24.3.1</summary>

* GUI changes
  * Added progress bar to indicate sub-step progress for running job
  * Added ability to interrupt and resume from last checkpoint
  * Added scan mode indicator to job row
* Bugfixes
  * Fixed an issue where some errors would cause the program to hang and not report the error
  * Added clear error for when updater/installer is not present

</details>

<details>

<summary>Version 24.3.0</summary>

* Updates to backend
  * Improvement in processing speed (\~1.2-2.0 x)
  * Improvement in storage utilisation (\~2.0 x)
* GUI changes:
  * Added display for details of currently selected light system
  * Added display of reconstruction tool to job row alongisde resolution
* Bugfixes:
  * Fixed an issue with the results button not always opening the folder
  * Fixed an issue where the uv bleed was not applying to the normals output texture
  * Fixed an issue with the build system which would cause Marso to not run on some systems due to a non bundled dependency

</details>

<details>

<summary>Version 24.2.2</summary>

* Bugfixes:
  * Fixed camera ordering issue for some Reality Capture alembics
  * Fixed issue with UV margin algorithm for very dark textures
  * Fixed ST map loading for uncommon size combinations
* Added and improved UV margin algorithm

</details>

<details>

<summary>Version 24.2.1</summary>

* UX improvements
  * Step reporting during processing
  * Links to help pages for calibration
  * UV Resolution can be set by user
  * Enabled removing materials
  * Enabled resizing on UI windows
* Bugfixes
* Added UV margin to Output Textures
* Photogrammetry images output at default brightness
* Marso checks for new versions on launch

</details>

<details>

<summary>Version 24.2.0</summary>

* Reality Capture support
* UX improvements
  * Verbose logging from UI
  * Option to control display brightness during calibration process
* Improvements to crash handling
* Support for rotated cameras (i.e. portrait and landscape)
* Database Upgrade

</details>

<details>

<summary>Version 24.1.1</summary>

* Preprocessing accounts for rotation parameter in Raw data

</details>

<details>

<summary>Version 24.1.0</summary>

* Removed dependency on Agisoft Pro installation
* Several under the hood improvements to output textures
* Performance improvements to some modules
* Support for photogrammetry not solving all cameras in a scene
* Support for varying numbers of lights used in scanning light system
* Added ability for user to specify the grey value of their calibration target
* Added some security improvements
* Added support for mobile scans

</details>


# OSS License Page

Below is a list of open source components used in Marso Measure, along with the licenses under which they are distributed. You are encouraged to review the terms of these licenses as they may contain important conditions and permissions.

| **Component Name** | **License**                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| Conda              | <https://docs.conda.io/en/latest/license.html>                              |
| cryptography       | <https://github.com/pyca/cryptography>                                      |
| h5py               | <https://github.com/h5py/h5py>                                              |
| HDF5               | <https://github.com/HDFGroup/hdf5>                                          |
| Libraw             | <https://github.com/letmaik/rawpy/blob/main/LICENSE.LibRaw>                 |
| numpy              | <https://github.com/numpy/numpy>                                            |
| opencv             | <https://github.com/opencv/opencv>                                          |
| openssl            | <https://github.com/openssl/openssl>                                        |
| pillow             | <https://github.com/python-pillow/Pillow>                                   |
| pip                | <https://github.com/pypa/pip>                                               |
| psutil             | <https://github.com/giampaolo/psutil>                                       |
| py-machineid       | <https://github.com/keygen-sh/py-machineid>                                 |
| pyinstaller        | <https://github.com/pyinstaller/pyinstaller>                                |
| Python             | <https://github.com/python/cpython>                                         |
| rawpy              | <https://github.com/letmaik/rawpy>                                          |
| requests           | <https://github.com/psf/requests>                                           |
| scipy              | <https://github.com/scipy/scipy>                                            |
| sckikit-learn      | <https://github.com/scikit-learn/scikit-learn>                              |
| vs\_2015runtime    | <https://visualstudio.microsoft.com/license-terms/vs2022-cruntime/>         |
| xgboost            | <https://github.com/dmlc/xgboost>                                           |
| zlib               | <https://github.com/madler/zlib>                                            |
| boto3              | <https://github.com/boto/boto3/blob/develop/LICENSE>                        |
| bzip2              | <https://gitlab.com/bzip2/bzip2/-/blob/master/COPYING>                      |
| colorama           | <https://github.com/tartley/colorama/blob/master/LICENSE.txt>               |
| dnspython          | <https://github.com/rthalley/dnspython/blob/main/LICENSE>                   |
| exifread           | <https://github.com/ianare/exif-py/blob/master/LICENSE.txt>                 |
| pymongo            | <https://github.com/mongodb/mongo-python-driver/blob/master/LICENSE>        |
| pyyaml             | <https://github.com/yaml/pyyaml/blob/main/LICENSE>                          |
| pyzmq              | <https://github.com/zeromq/pyzmq/blob/main/LICENSE.md>                      |
| tabulate           | <https://github.com/astanin/python-tabulate/blob/master/LICENSE>            |
| toml               | <https://github.com/uiri/toml/blob/master/LICENSE>                          |
| tqdm               | <https://github.com/tqdm/tqdm/blob/master/LICENCE>                          |
| tk                 | <https://github.com/tcltk/tk/blob/main/license.terms>                       |
| portalocker        | <https://github.com/WoLpH/portalocker/blob/develop/LICENSE>                 |
| pygubu             | <https://github.com/alejandroautalan/pygubu/blob/master/LICENSE>            |
| jsonschema         | <https://github.com/python-jsonschema/jsonschema/blob/main/COPYING>         |
| reportlab          | <https://github.com/mattjmorrison/ReportLab/blob/master/LICENSE.txt>        |
| perlin-noise       | <https://github.com/caseman/noise/blob/master/LICENSE.txt>                  |
| cxxopts            | <https://github.com/jarro2783/cxxopts/blob/master/LICENSE>                  |
| gtest              | <https://github.com/google/googletest/blob/main/LICENSE>                    |
| libpng             | <https://github.com/pnggroup/libpng/blob/libpng16/LICENSE>                  |
| libjpeg-turbo      | <https://github.com/libjpeg-turbo/libjpeg-turbo/blob/main/LICENSE.md>       |
| highfive           | <https://github.com/BlueBrain/HighFive/blob/master/LICENSE>                 |
| nlohmann-json      | <https://github.com/nlohmann/json/blob/develop/LICENSE.MIT>                 |
| mongo-c-driver     | <https://github.com/mongodb/mongo-c-driver/blob/master/COPYING>             |
| mongo-cxx-driver   | <https://github.com/mongodb/mongo-cxx-driver/blob/master/LICENSE>           |
| openexr            | <https://github.com/AcademySoftwareFoundation/openexr/blob/main/LICENSE.md> |
| pkgconf            | <https://github.com/pkgconf/pkgconf/blob/master/COPYING>                    |
| spdlog             | <https://github.com/gabime/spdlog/blob/v1.x/LICENSE>                        |
| tiff               | <https://gitlab.com/libtiff/libtiff/-/blob/master/README.md>                |
| cppzmq             | <https://github.com/zeromq/cppzmq/blob/master/LICENSE>                      |
| cpr                | <https://github.com/libcpr/cpr/blob/master/LICENSE>                         |
| alembic            | <https://github.com/alembic/alembic/blob/master/LICENSE.txt>                |
| glad               | <https://github.com/Dav1dde/glad/blob/glad2/LICENSE>                        |
| glew               | <https://github.com/nigels-com/glew/blob/master/LICENSE.txt>                |
| glfw3              | <https://github.com/glfw/glfw/blob/master/LICENSE.md>                       |
| glm                | <https://github.com/g-truc/glm/blob/master/copying.txt>                     |
| shaderc            | <https://github.com/google/shaderc/blob/main/LICENSE>                       |
| pympler            | <https://github.com/pympler/pympler/blob/master/LICENSE>                    |


# Welcome to Marso Studio by M-XR

An introduction to Marso Studio.

Marso Studio is M-XR's node-based web app for building production-ready 3D assets and giving them physically-based materials grounded in real-world measurement.

Describe an environment and Marso Studio breaks it into its individual objects, builds each one as a separate 3D asset, and predicts a full PBR material stack for every one of them. Or bring a single mesh you already have and texture just that. Both routes run in the same node editor, in your browser.

### Scene generation

**Scene generation is the main route through Marso Studio.** A favela street, a teenage bedroom, a mechanic's workshop — you start from one scene image and finish with every object in it as a separate, textured, production-ready asset.

The scene isn't generated as one enormous mesh. It's **decomposed into objects**, and each object is reconstructed on its own — so an object half-hidden behind something else in the scene still comes out as a complete asset:

1. **Scene Generation** — describe the environment and get a scene image
2. **Detect Objects** breaks it into its individual objects
3. **You choose what to keep** — everything is selected by default, and nothing expensive runs until you confirm
4. **Reference images, 3D models and PBR** run across every object you selected
5. **Export** the whole scene, or any object on its own

Scene generation is the **Bulk** workflow — pick it when you create a project and the starting nodes are already there. Start with [Generate a scene](/marso-studio/scenes/generate-a-scene).

### The material model

At the heart of Studio is **I2M (Image-to-Material)** — M-XR's foundational material model. Give it a textured mesh and it predicts a complete PBR material stack in minutes: **albedo, metallic, roughness and IOR**.

I2M is trained on Marso Measure's measured material data rather than hand-authored guesswork, so its predictions are physically grounded and drop straight into a production pipeline. *(Normal map prediction is in active development.)*

### The node editor

Every route is built from nodes, and you can assemble your own pipeline from any of them:

* **Scene** — describe an environment with **Scene Generation**, break it into objects with **Detect Objects**, then build per-object references with **Generate Reference Images**
* **Images** — generate an image from a prompt, create a multi-view turntable, or edit an existing image
* **3D** — turn an image into a mesh with **Generate 3D Model**, or bring your own with **3D Model Upload** (GLB, USD or FBX)
* **Materials** — run **Generate PBR Textures** to predict and attach a full material set with I2M
* **Preview & export** — inspect the result in the 3D viewer, then download the textured asset and its individual maps

When you create a project you choose a **workflow**, and the starting nodes are placed for you:

* **Bulk** — Scene Generation → Detect Objects, for a whole environment
* **Individual** — 3D Model Upload → Generate PBR Textures, for a single asset

### Who it's for

Marso Studio is built for teams and creators who need realistic 3D assets at volume — AAA/AA game studios, VFX houses, fashion and product visualisation, cultural heritage, and solo artists. If you understand meshes, UVs and PBR workflows, you'll be productive in minutes.

### What you'll need

* An idea for a scene, an image, **or** a textured 3D asset — **GLB**, **USD** or **FBX**
* An M-XR account

If you're bringing your own mesh, it's worth a two-minute read of[ Preparing your assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets) so your file isn't rejected at the door.

### How it's charged

Marso Studio runs on **credits** — each generation step spends a set number, and your balance is always shown at the top of the screen. Scenes are charged per object, so what a scene costs depends on how many objects you choose to keep.

You get free credits to start with, and more on any day you open the app. See [Credits & billing](/marso-studio/reference/credits-and-billing) for the full breakdown.

### Early access

Marso Studio is in **early access** and improving quickly. You may hit rough edges — the web renderer is still being refined, and some predictions are stronger than others depending on your input. Your feedback directly shapes the product. See the [Early access brief](/marso-studio/getting-started/early-access-brief) for what to expect and how to report issues.

***

**New here?** Start with [How Marso Studio works](/marso-studio/getting-started/how-marso-studio-works), then run your first scene through the [Quickstart](/marso-studio/getting-started/quickstart).


# How Marso Studio Works

This page describes how Marso Studio works.

Marso Studio builds 3D assets and predicts a complete set of physically-based rendering (PBR) materials for them — in minutes, in your browser. It works at two scales: a whole scene decomposed into its objects, or a single asset on its own.

### The model: I2M

At the centre of Marso Studio is **I2M (Image-to-Material)**, M-XR's foundational material model. Given a mesh and its base-colour texture, I2M predicts a full PBR material stack:

| Map           | What it describes                                       |
| ------------- | ------------------------------------------------------- |
| **Albedo**    | The true surface colour, with lighting removed          |
| **Metallic**  | Which areas behave as metal vs non-metal                |
| **Roughness** | How sharp or diffuse surface reflections are            |
| **IOR**       | Index of refraction — how light reflects at the surface |

> **Normal map prediction is in active development** and is not yet part of the downloadable output.

I2M is trained on measured material data rather than artist interpretation, so its predictions are consistent and ready to drop into a production pipeline.

### What the model needs from you

* Clean mesh geometry
* A base-colour texture (see [3D file support](/marso-studio/preparing-your-assets/3d-file-support))

I2M **enhances** materials — it does not fix broken geometry, bad UVs or poor scans. The better your input, the better your result. This holds for generated meshes too: the quality of a scene object depends on the reference image it was built from.

### The scene pipeline

The main route through Studio starts from a whole environment rather than a single object.

A scene is **decomposed** before anything is generated. Detection breaks the scene image into individual objects and shows them to you; you confirm which ones are worth building; then each selected object is generated and textured independently.

1. **Scene Generation** — describe the environment and get a scene image
2. **Detect Objects** — the scene becomes a list of individual objects
3. **Confirm your selection** — everything is selected by default; you decide what gets built, and what it costs
4. **Generate Reference Images** — each object gets a reference image of its own
5. **Generate 3D Model** — each object is reconstructed as a mesh
6. **Generate PBR Textures** — I2M predicts materials for each one
7. **Export** — the whole scene, or any object individually

Each object is reconstructed from its own reference image, and 3D generation needs the object to fill most of that image. Objects that were small or distant in the scene are the ones that fail.

See [Generate a scene](/marso-studio/scenes/generate-a-scene).

### The node editor

Rather than a single upload box, Marso Studio gives you a **node editor**. Each node is one step in the process — detect objects, load or generate an asset, generate or edit an image, apply materials — and you connect a node's output to the next node's input to build a pipeline.

You don't have to start from an empty graph. When you create a project you choose a **workflow**, and the starting nodes are placed for you:

* **Bulk** — **Scene Generation → Detect Objects**, for a whole environment
* **Individual** — **3D Model Upload → Generate PBR Textures**, for a single asset

From there you add, remove and rewire nodes as you like. See the full [Nodes reference](/marso-studio/reference/nodes-reference) for what every node does.

### The single-asset routes

Scene generation is the main route, but for one hero prop the direct routes are faster:

* **You have the mesh** — upload it, run **Generate PBR Textures**. This is what an Individual project opens with.
* **You have an image, or an idea** — **Image Generation → Generate 3D Model → Generate PBR Textures**.

Both remain fully supported. See [Workflows](/marso-studio/workflows/apply-pbr-to-your-own-model).

### How work is charged

Every generation step spends **credits**, and the node tells you what a step will cost before you run it. Scenes are charged per object, so the size of your selection decides what a scene costs..

See [Credits & billing](/marso-studio/reference/credits-and-billing).

### From input to output, at a glance

1. **Start** — describe a scene, bring an image, or upload a model.
2. **Decompose** *(scenes only)* — break the scene into objects and choose what to keep.
3. **Build** — generate the mesh, or use the one you uploaded.
4. **Apply materials** — run **Generate PBR Textures** to predict the PBR stack with I2M.
5. **Preview** — inspect the result in the 3D viewer.
6. **Export** — download the textured assets and their individual maps.

Ready to try it? Head to the [Quickstart](/marso-studio/getting-started/quickstart).


# Quickstart

This guide takes you from a blank canvas to a fully textured asset. Pick the route that matches what you have.

When you create a new project you choose a **workflow**, and that choice decides your route:

| Workflow       | For           | You start with                                  |
| -------------- | ------------- | ----------------------------------------------- |
| **Bulk**       | A whole scene | **Scene Generation** → **Detect Objects**       |
| **Individual** | One asset     | **3D Model Upload** → **Generate PBR Textures** |

> **Bringing your own mesh?** Check that your asset meets the [file requirements](/marso-studio/preparing-your-assets/3d-file-support) first. Most early problems come from inputs that were never going to work.

### Route A — I want a whole scene

Create a new project and choose **Bulk**. This is the main route.

1. In **Scene Generation**, describe an environment — a place, not a single object: *"a cluttered mechanic's workshop, tools on the bench, oil drums in the corner"*.
2. Run **Detect Objects**. The scene is broken into its individual objects.
3. Open the object viewer. **Everything is selected by default** — deselect walls, floors, backdrop, duplicates, and anything small or distant. Every object you keep is charged for all three generation stages, so this is the step that controls your spend. Confirm the selection.
4. Run **Generate Reference Images.**
5. Run the group **Generate 3D Model.**
6. Run the group **Generate PBR Textures.**
7. **Preview** objects in the 3D viewer as they arrive, then **export** the scene or individual assets.

Full detail in [Generate a scene](/marso-studio/scenes/generate-a-scene).

### Route B — I already have a 3D model

Create a new project and choose **Individual**. You land on **3D Model Upload → Generate PBR Textures**.

1. In **3D Model Upload**, upload your `.glb`, `.usdz` or `.fbx`. Uploading is free.
2. Run **Generate PBR Textures**. The model predicts your materials — usually a few minutes.
3. Inspect the result in the **3D viewer**.
4. **Export** the textured asset and its individual maps.

### Route C — I want one asset from an idea or an image

Create a new project and choose **Individual**, then build the image → 3D route: **Image Generation → Generate 3D Model → Generate PBR Textures**.

1. In **Image Generation**, enter a prompt. Prefer your own image? Use an **Image Upload** node instead — it's free.
2. **Generate 3D Model** turns that image into a mesh. Need a specific face count? Set a custom polycount.
3. **Generate PBR Textures** applies materials.
4. **Preview** in the 3D viewer, then **export**.

### What you get

Every successful run gives you the textured asset plus its individual maps — **albedo, metallic, roughness and IOR**. Scene runs give you each object as its own asset with its own material set.

### Next steps

* Run a scene properly → [Generate a scene](/marso-studio/scenes/generate-a-scene)
* Understand the full pipeline → [Nodes reference](/marso-studio/reference/nodes-reference)
* Budget a big run → [Credits & billing](/marso-studio/reference/credits-and-billing)
* Get better results → [Sourcing & preparing assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets)
* Something not working? → [Troubleshooting](/marso-studio/help-and-support/troubleshooting)


# Early Access Brief

This guide covers everything you need to know to get good results and how to find ideal assets.

Marso Studio is in **early access**. The core pipeline works today — you can take a scene or a single asset from prompt to exported PBR maps — but you'll meet rough edges, and your feedback is what sharpens the product.

### What to expect

* **Generation in minutes** — most PBR runs complete in a few minutes.
* **Scenes take longer** — a scene runs every stage across every object you selected, so plan for a long run on a large scene rather than watching it.
* **Partial results are normal on scenes** — one object failing doesn't stop the rest, and doesn't invalidate the ones that worked. Retry individual objects rather than the whole scene.
* **Viewable results** — preview the textured asset in the 3D viewer before you download.
* **Downloadable maps** — every successful run gives you albedo, metallic, roughness and IOR.
* **A renderer still being refined** — the web viewer is improving. If something looks off *in the viewer*, check the exported maps before assuming the result is wrong.

### Getting the best results

* Start with clean inputs — see [Sourcing & preparing assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets).
* Check your UVs, and that the base colour reads correctly.
* Try several assets — some material types predict more reliably than others.
* Keep files under 100 MB.
* Run one generation at a time during early access.

### When something goes wrong

Tell us — with detail, it gets fixed faster. Include:

* The asset you used (and where it came from), or the scene prompt.
* What you expected vs what actually happened.
* A screenshot of the result, plus any error message.

Check [Troubleshooting](/marso-studio/help-and-support/troubleshooting) first for the common cases, then [Contact & support](/marso-studio/help-and-support/contact-support) to reach the team.

### Your credits&#x20;

You get free credits when you sign up, and more on any day you open Marso Studio. See [Credits & billing](/marso-studio/reference/credits-and-billing).

***

#### Example Assets

We provide 10 example assets, already loaded into any new projects. You can get started with these to understand how Marso Studio works.

The assets provided are all Gen3D models.

<div align="left"><figure><img src="/files/I8IlWz0X7yN8aieMMjjs" alt="" width="188"><figcaption></figcaption></figure></div>

{% hint style="success" %}
The quality of your output is directly tied to the quality of your input. Marso Studio enhances materials — it doesn't repair bad geometry or compensate for poor scans.
{% endhint %}

More information on supported file types can be found [here](/marso-studio/preparing-your-assets/3d-file-support).

#### What makes a good input?

A well-captured photogrammetry scan is ideal — clean geometry, well-defined surfaces, no mesh "boiling" or sloppy reconstruction artefacts. If you have your own scans, start there.

{% tabs %}
{% tab title="Good Mesh" %}

<figure><img src="/files/d4tmGS0be7BbgqzFd7gY" alt="" width="375"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Bad Mesh" %}

<figure><img src="/files/sFk9vvs411M2tZIWScl1" alt="" width="375"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

If you don't have a mesh at hand, you can browse Sketchfab for downloadable .glb assets. We've also put together a curated collection of objects that work well with Marso Studio — feel free to pick from those below, or find your own.

<details>

<summary>Our Sketchfab Collections</summary>

* [Auto PBR Results](https://sketchfab.com/m-xr/collections/auto-pbr-imagetomaterial-4137cee2eca94d4b9eb3376dbac359a0)
* [Test Data](https://sketchfab.com/m-xr/collections/img2mat-test-data-ed113062403d410f85138cffdac018fc)

</details>

#### Evaluating a Mesh

When evaluating a mesh on Sketchfab, switch to MatCap view mode — this strips the textures and lets you inspect the geometry directly. You want to see clean, well-defined surfaces without noise, holes, or overlapping faces.

<div><figure><img src="/files/QK1SspgfHkuChZjadbDL" alt=""><figcaption></figcaption></figure> <figure><img src="/files/XcD5F5GkSwt77kov5xbP" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Nvx5MCToVhn8pHm6ObSy" alt=""><figcaption></figcaption></figure></div>


# Organisations

An **organisation** groups your team together in Marso Studio, with a shared credit balance everyone can draw from. One person creates it, then invites colleagues by email.

You don't need an organisation to use Marso Studio — if you're working on your own, you can skip this page.

### Before you start

**Everyone needs an M-XR account before they can be invited.** So ask your colleagues to sign up first — an invitation can't create an account for them.

To create an account:

1. Open **Marso Studio** at [marso.app](https://marso.app) and create your account, once you account is created then go to your settings area.

### Creating an organisation

1. In Marso Studio, click your **profile** in the bottom-left corner, then click **Settings**.
2. Click **Organisation** in the left-hand menu.
3. Create your organisation and give it a name.

Whoever creates the organisation is its **owner**.

### Inviting people

In the same **Organisation** settings area:

1. Enter the email address of the person you want to add.
2. Click **Invite**.

Repeat for each person. Use the email address they signed up with — an invitation sent to an address without an M-XR account won't reach anyone.

### Accepting an invitation

If you've been invited:

1. Create your M-XR account at [app.m-xr.com](https://app.m-xr.com), if you don't have one already.
2. Open Marso Studio at [marso.app](https://marso.app).
3. Click your **profile** in the bottom-left corner → **Settings** → **Organisation**.
4. Accept your invitation.

### Roles

|                                        | Owner | Admin | Member |
| -------------------------------------- | ----- | ----- | ------ |
| Owns the account                       | ✅     | —     | —      |
| View the organisation's credit balance | ✅     | ✅     | —      |
| Spend the organisation's credits       | ✅     | ✅     | ✅      |

Every member can spend from the shared balance, whether or not they can see what's in it.

**Changing the owner** isn't something you can do yourself — the current owner needs to email **<support@m-xr.com>**.

### Using organisation credits

A new organisation starts with a balance of **0**. Organisation credits are held separately from your personal credits, so creating or joining an organisation doesn't move your own balance across.

To spend the organisation's credits instead of your own, open the **Credits** area and **toggle to your organisation**. Everything you generate from then on draws from the shared balance.

See [Credits & billing](/marso-studio/reference/credits-and-billing) for what each step costs.


# Sourcing & preparing assets

Marso Studio **enhances** materials — it doesn't repair geometry or compensate for a poor scan. The quality of your output is tied directly to the quality of your input. This page covers what makes a good input and where to find assets to try.

### If you're generating a scene

A scene starts from an image, not a mesh, so the rules below about textures and UVs don't apply — but the same principle does. **What you feed the scene determines what you get out of it.**

A good scene image:

* **Reads as a place, not an object.** Prompts that describe a set — what's on the bench, what's in the corner — decompose into more usable objects than prompts describing a single hero asset.
* **Has clearly separated objects.** Detection works on visual separation. A scene with distinct, individually visible props detects far better than one with a few large overlapping forms.
* **Gives each object room.** Every object is reconstructed from its own reference image, and 3D generation needs the object to fill most of that frame. Objects that are small, distant, cropped at the edge or mostly hidden behind something else tend to fail at the 3D stage.
* **Is clear rather than atmospheric.** Heavy fog, extreme lighting and motion blur all cost you objects.

If a detection comes back wrong, it's usually cheaper to fix the image than to keep re-running detection. See [Detecting & selecting objects](/marso-studio/scenes/detecting-and-selecting-objects).

### Two questions that decide how to prepare your file

**1. Does it have a texture?**

Your asset must carry an image-based base-colour texture.

* ✅ Has a texture
* ❌ Vertex colours only — these aren't textures and will be rejected

**2. Where did the mesh come from?**

| AI-generated mesh                                           | Your own mesh                                  |
| ----------------------------------------------------------- | ---------------------------------------------- |
| Created with a generative model — text-to-3D or image-to-3D | An artist-made model, or a photogrammetry scan |

The preparation rules differ slightly for each.

#### AI-generated assets

* ✅ Has a texture
* ✅ **Has shading** — the model works best with assets that carry shading and lighting cues in the base colour; this outperforms flat shading
* ❌ Flat shading, or a plain base colour with no lighting information
* ❌ Already has PBR materials

#### Your own mesh

* ✅ **Unique UVs** — parts of the asset don't share the same UV space
* ❌ **Tileable textures** — bake these down to a single UV map first
* ❌ **Procedural textures** — bake these to a single UV map first
* ❌ Already has PBR materials

> **Why "no existing PBR"?** The model's job is to *predict* the PBR stack. An asset that already carries PBR materials works against that prediction — bring a clean, base-colour asset and let Marso Studio do the rest.

### Keep files under 100 MB

Large files are slow to upload and more likely to fail. Decimate or optimise heavy meshes before uploading.

### Check before you generate

* Confirm the asset opens with its base-colour texture visible.
* Inspect the UVs — look for overlapping or shared UVs on parts that should be unique.
* Make sure there's no PBR already applied.

### Where to find assets to try

* **Example assets** — every new project comes preloaded with 10 example assets so you can see how Marso Studio works before bringing your own.
* **Generate a scene** — the fastest way to get a lot of assets at once. See [Generate a scene](/marso-studio/scenes/generate-a-scene).
* **Generate a single asset** — use the image → 3D nodes to create one asset from scratch. See [From image to textured 3D](/marso-studio/workflows/from-image-to-textured-3d).

***

Next: check the exact format rules in [3D file support](/marso-studio/preparing-your-assets/3d-file-support).


# 3D file support

Marso Studio accepts **GLB**, **USD** and **FBX** uploads. GLB and USD are the most mature paths today. **FBX is the newest format we accept and carries the highest risk of import or generation errors.**

> **Every format needs an image-based base-colour texture mapped to the geometry.** Vertex colours are *not* textures, and assets coloured with vertex data alone will be rejected.

### Requirements by format

#### GLB *(recommended)*

| GLB upload                                        | Accepted? |
| ------------------------------------------------- | :-------: |
| Textures embedded in the file                     |     ✅     |
| A base-colour texture on every material           |     ✅     |
| Textures referenced externally (URI or file path) |     ❌     |
| A material with no texture                        |     ❌     |

GLB has the strictest texture rules — see What gets a GLB rejected for the detail.

#### USD

Package as **`.usdz`** with geometry and a base-colour texture.

| USD upload                                                                | Accepted? |
| ------------------------------------------------------------------------- | :-------: |
| Textures embedded *or* referenced inside the package — we re-resolve them |     ✅     |
| Geometry with no base-colour texture                                      |     ❌     |

#### FBX

Either embed the textures inside the `.fbx`, **or** zip the `.fbx` together with its texture files.

| FBX upload                                              | Accepted? |
| ------------------------------------------------------- | :-------: |
| Textures embedded in the `.fbx`, or zipped alongside it |     ✅     |
| Base-colour map named by convention (see below)         |     ✅     |
| A zip that doesn't follow the naming convention         |     ❌     |
| External textures not bundled in the zip                |     ❌     |

**Base-colour naming convention:** name the map `game.color.png`, `color.png`, `albedo.png`, `basecolor.png`, or `base_color.png`.

### Supported model features

These all work, across your uploads:

| Feature                 | Supported? | What it means                                                                                                          |
| ----------------------- | :--------: | ---------------------------------------------------------------------------------------------------------------------- |
| **Multi-mesh**          |      ✅     | Multiple separate objects in one file (e.g. a table and a chair).                                                      |
| **Multi-material**      |      ✅     | Different parts of your model can use different materials (e.g. one shiny, one matte).                                 |
| **Texture atlasing**    |      ✅     | Pack multiple materials' textures into one image — as long as each material's UVs occupy a distinct region of it.      |
| **Adjacent UV regions** |      ✅     | Two materials' UV regions can touch along a shared edge (e.g. left half and right half) — touching is not overlapping. |

### What gets a GLB rejected

GLB uploads must be fully self-contained. We reject:

| Issue                                         | Why we reject it                                                                                                |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **External textures**                         | The GLB must embed every texture. GLBs that reference textures by external URL or filename are rejected.        |
| **Untextured materials**                      | Every material must have at least one texture (base colour, normal, metallic-roughness, occlusion or emissive). |
| **Broken texture references**                 | Texture slots pointing to a missing texture, missing image, or empty image data are rejected.                   |
| **A separate texture file alongside the GLB** | Embedded textures are the source of truth — sending a GLB plus a loose texture file is rejected.                |

### Good to know

Allowed by the validator today, but worth watching:

* **Tiled / out-of-`[0,1]` UVs.** UVs are read as raw values, not wrapped into the `[0,1]` square. A material whose UVs run `0`–`5` (to tile a texture) is treated as occupying that whole `0–5` range and will very likely collide with another material — so tiling-style UVs are effectively unsupported.

***

File requirements are only half the story — getting a *good* result also depends on the kind of asset you bring. See [Sourcing & preparing assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets).


# Generate a scene

Take a whole environment and come out with every object in it as a separate, textured, production-ready 3D asset.

This is the main route through Marso Studio. Everything else in the AI mesh space works one asset at a time; here you describe a scene once and get back a set of individual assets you can place, swap and reuse.

### Start a bulk project

When you create a new project you choose between two workflows:

* **Bulk** — for scenes. You land on a graph with a **Scene Generation** node and a **Detect Objects** node already in place.
* **Individual** — for a single asset. You land on **3D Model Upload** and **Generate PBR Textures**.

Scene generation is the **Bulk** workflow. There's nothing to assemble — the starting nodes are there when the project opens.

### How it works

A scene isn't generated as one enormous mesh. It's broken into objects, and each object is then built on its own:

1. **Scene Generation** — describe the environment you want, and get a scene image.
2. **Detect Objects** — the scene is broken into its individual objects and shown to you as a list.
3. **Choose what to keep** — everything is selected by default; deselect what you don't need. This is where you control the cost.
4. **Reference images** — each selected object gets a clean reference image of its own.
5. **3D models** — each object is reconstructed as a mesh.
6. **PBR** — I2M predicts the material stack for every object.
7. **Export** — download the whole scene, or any object on its own.

### Steps

1. Create a **new project** and choose the **Bulk** workflow.
2. In **Scene Generation**, describe the environment. A place, not a single object: *"a cluttered mechanic's workshop, tools on the bench, oil drums in the corner"*.
3. Run **Detect Objects**. Optionally tell it which categories to look for first.
4. Open the object viewer and review what was found. **Everything is selected by default** — deselect anything you don't need, then confirm. See [Detecting & selecting objects](/marso-studio/scenes/detecting-and-selecting-objects).
5. Run **Generate Reference Images**.
6. Run the group **Generate 3D Model**.
7. Run the group **Generate PBR Textures**.
8. **Preview** any object in the 3D viewer, then **export** the scene or individual assets — see [Working with scene results](/marso-studio/scenes/working-with-scene-results).

### What it costs

**Every object you keep is charged for all three generation stages** — its reference image, its mesh, and its PBR. So the size of your selection at step 4 is what decides the cost of the scene.

Generating the scene image and detecting objects are charged once, and both are cheap relative to the generation that follows. That's deliberate: you can look at what was found, and cut it down, before anything expensive runs.

See [Credits & billing](/marso-studio/reference/credits-and-billing) for what each step costs and how to budget a run.

### Tips

* **Describe a place, not an object.** Prompts that read like a set dressing brief decompose better than prompts that read like a single hero asset.
* **Clutter is good.** A scene with clearly separated, distinct objects detects far better than one with a few large overlapping forms.
* **Objects need to be big in frame.** 3D generation works from each object's reference image, and it needs the object to fill most of that image. Anything small, distant or mostly hidden in the original scene tends to fail at the 3D stage — deselect it rather than paying for it.
* **Cut hard at selection.** Keep the objects you'd actually place in a level.
* **Run one scene at a time** while you're learning what your prompts produce — a large scene is a long run, and it's cheaper to learn on a small one.

### Single-asset routes

Scene generation doesn't replace the single-asset flows, and for one hero prop they're still the faster path. Choose the **Individual** workflow when you create the project:

* [Apply PBR to your own model](/marso-studio/workflows/apply-pbr-to-your-own-model) — you already have the mesh.
* [From image to textured 3D](/marso-studio/workflows/from-image-to-textured-3d) — one image, one asset.


# Detecting & selecting objects

Detection is the step that turns a scene image into a list of separate objects — and the step where you decide what the scene is going to cost.

### Running detection

In a **Bulk** project, **Detect Objects** is already wired to the **Scene Generation** node. Connect your scene image to it and run it.

You can optionally give it **categories** — the kinds of object to look for. Leave it empty and it will find whatever it can; supply categories and it will focus on those. Categories are worth using when a scene has one class of object you actually care about, for example furniture in a room full of props.

Detection returns a set of objects with a preview. **Nothing else runs yet, and nothing else is charged yet.**

### Reviewing the selection

Open the object viewer to see what was found. **Everything is selected by default**, so this step is about removing what you don't want.

Every object you keep is charged for all three generation stages that follow, so the selection screen is the cheapest place to control your spend. Work through the list and deselect:

* **Structure** — walls, floors, ceilings, ground planes. These are usually better built in your DCC than generated.
* **Anything small or distant.** 3D generation needs each object to fill most of its reference image. An object that was tiny or heavily occluded in the scene won't produce a usable reference, and will usually fail at the 3D stage.
* **Backdrop** — anything blurred or only partly visible that you wouldn't place in a level.
* **Duplicates** — if the scene contains six near-identical crates, keep one and instance it yourself.
* **Fragments** — a detection that's caught part of an object rather than the whole thing.

Confirm the selection when you're happy with it. The count you confirm is the count you're billed for at each downstream stage.

### Running detection again

If the detection isn't right — it missed objects you wanted, split one object into several, or merged several into one — you can run **Detect Objects** again. Each run is charged the same as the first.

This is worth doing before you generate. Re-running detection is cheap relative to what follows, so fixing a bad decomposition costs far less than generating an object that was never a whole object in the first place.

| What you see                    | What to try                                    |
| ------------------------------- | ---------------------------------------------- |
| Objects missing entirely        | Name them explicitly in categories             |
| One object split into pieces    | Re-run with a broader category for that object |
| Several objects merged into one | Re-run with the individual categories named    |
| Too much scenery detected       | Just deselect the extras — that's free         |

If two runs don't improve things, the scene image is usually the problem rather than the detection. A clearer image with better-separated objects, each one reasonably large in frame, will detect better than any category list. See [Sourcing & preparing assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets).

### What happens next

Once you confirm a selection, the generation stages run **per object**, as a group:

1. **Generate Reference Images**
2. **Generate 3D Model**
3. **Generate PBR Textures**

Each stage runs across every object in the selection. See [Working with scene results](/marso-studio/scenes/working-with-scene-results) for what to do when some objects succeed and others don't.


# Working with scene results

Once you've confirmed a selection, each generation stage runs across the whole group. This page covers what to expect while it runs, and what to do when part of a scene doesn't come back.

**Group runs**

The three generation stages — **Generate Reference Images**, **Generate 3D Model** and **Generate PBR Textures** — each run as a group across your whole selection, and each is charged per object. See [Credits & billing](/marso-studio/reference/credits-and-billing).

Objects are processed in parallel, so a scene takes considerably longer than a single asset but not the sum of its parts. Larger selections take proportionally longer — plan for a long run on a big scene rather than watching it.

You can review objects as they arrive. You don't have to wait for the whole group to finish before opening the 3D viewer on the ones that are already done.

### Partial completion

A group can finish with some objects succeeded and some failed. This is normal on larger scenes — one object failing does not stop the rest, and does not invalidate the ones that worked.

When a stage completes, check the group for anything that didn't come through. Failures are usually specific to one object rather than to the scene, and the most common cause is the reference image:

* **The object doesn't fill enough of its reference image.** 3D generation needs the object to take up the majority of the frame. Objects that were small, distant or heavily occluded in the original scene produce references that are too sparse to reconstruct from. This is the failure to expect.
* **A geometry the reconstruction can't resolve** — very thin, wiry or transparent objects are the common cases.
* **A mesh without usable base colour** — PBR prediction needs a base-colour texture to work from.

### Retrying an object

You can re-run individual objects rather than the whole scene. **Retrying charges only for that object and that stage** — you don't pay for the whole pipeline again.

If a retry fails the same way twice, the problem is upstream. Go back a stage: a bad mesh is usually a bad reference image, and a bad reference image is usually an object that was too small in the scene to begin with. Running detection again and re-selecting is often faster than retrying the same object repeatedly — see [Detecting & selecting objects](/marso-studio/scenes/detecting-and-selecting-objects).

### Running out of credits mid-scene

**Objects that already completed are kept.** They're yours, and you won't be charged for them again. But the run doesn't pause and pick up where it left off — **the remaining objects in that run won't complete**. Top up, then re-run the objects that didn't finish.

To avoid it, work out the cost before you start — every object you keep is charged for all three stages. See [Credits & billing](/marso-studio/reference/credits-and-billing).

### Exporting a scene

You can download:

* **The whole scene** — every completed object in one download.
* **A single object** — any individual asset on its own.
* **Textures only** — the individual PBR maps for the objects you select.

Objects that didn't complete are skipped rather than exported empty. Full format details are in [Previewing & exporting](/marso-studio/reference/previewing-and-exporting).

Each object exports as its own asset with its own material set, so you can place, swap and reuse them independently once they're in your DCC.


# Apply PBR to your own model

The fastest way to add PBR materials to an asset you already have. This is what an **Individual** project opens with.

This is a **single-asset route**. If you want a whole environment rather than one object, see [Generate a scene](/marso-studio/scenes/generate-a-scene).

**Nodes:** 3D Model Upload → Generate PBR Textures

### When to use this

You already have a textured mesh — a scan, a purchased asset, something out of your own pipeline — and you want I2M to predict its material stack.

### Steps

1. Create a **new project** and choose the **Individual** workflow. You land on 3D Model Upload → Generate PBR Textures.
2. In **3D Model Upload**, upload your `.glb`, `.usdz` or `.fbx`. Uploading is free — you're only charged when you generate.
3. Run **Generate PBR Textures**. Usually a few minutes.
4. **Preview** in the 3D viewer — switch HDRIs and compare against the original to check the prediction.
5. **Export** the textured asset and its individual maps.

### What you get

**Albedo, metallic, roughness and IOR**, as individual maps and as a textured mesh. *(Normal map prediction is in active development.)*

### Tips

* **Bring a clean, base-colour asset.** Assets that already carry PBR work against the prediction — strip existing material data first.
* **Check your UVs before you spend the credits.** I2M enhances materials; it can't fix overlapping UVs or broken geometry.
* **Keep files under 100 MB.**

See [3D file support](/marso-studio/preparing-your-assets/3d-file-support) for the full input rules, the [Nodes reference](/marso-studio/reference/nodes-reference), and [Credits & billing](/marso-studio/reference/credits-and-billing).


# From image to textured 3D

Generate a single 3D asset from scratch and texture it — all in one pipeline, built in an **Individual** project.

This is a **single-asset route**. If you want a whole environment decomposed into many assets, see [Generate a scene](/marso-studio/scenes/generate-a-scene).

Generating geometry is only half the job — an untextured or flat-shaded mesh isn't production-ready. Running it through I2M grounds the asset in measured PBR materials, so what you export drops straight into a render or game pipeline.

### When to use this

You're starting from an idea, a prompt, or a single reference image and want a fully textured 3D asset at the end.

### Steps

1. Create a **new project**, choose the **Individual** workflow, and build the image → 3D route: **Image Generation → Generate 3D Model → Generate PBR Textures.**
2. In **Image Generation**, enter a prompt. *(Prefer your own image? Swap in an **Image** node and upload it instead.)*
3. **Generate 3D Model** turns that image into a mesh.
4. **Generate PBR Textures** applies the material stack.
5. **Preview** in the 3D viewer, then **export** the textured asset and its maps.

### Variations

* **Upload your own image** — replace **Image Generation** with an **Image** node.
* **Refine the image first** — add an **Image Edit** node before generating the 3D model.
* **Improve the 3D reconstruction** — use a **Multiview** node to produce multiple views of the object before **Generate 3D Model.**
* **Set a specific face count** — pick a custom polycount on **Generate 3D Model**. Only available on single-image generation, not multi-view.

### Tips

* **The object must fill most of the image.** This is the single biggest cause of a failed 3D generation — a subject that's small, distant or lost in a busy frame won't reconstruct.
* A clean, well-lit source image with clear shading produces a better mesh and better materials.
* Flat-shaded generative images predict poorly. Shading and lighting cues baked into the base colour give I2M something to work from.

See the full [Nodes reference](/marso-studio/reference/nodes-reference) and [Credits & billing](/marso-studio/reference/credits-and-billing).


# Nodes reference

Marso Studio is built around **nodes**. Each node is one step — generate a scene, break it into objects, generate or load an asset, generate or edit an image, apply materials. Connect a node's output to the next node's input to build a pipeline.

When you create a project you pick a **workflow**, and the starting nodes are placed for you:

| Workflow       | You start with                                  |
| -------------- | ----------------------------------------------- |
| **Bulk**       | **Scene Generation** → **Detect Objects**       |
| **Individual** | **3D Model Upload** → **Generate PBR Textures** |

Nodes are grouped into **Scene**, **Image**, **3D** and **Utility**.

### Scene

#### Scene Generation

Generate a scene image from a text prompt — a whole environment rather than a single object. This is the starting node in a Bulk project.

* **Input:** text prompt
* **Output:** scene image
* **Cost:** 10 credits

#### Detect Objects

Break a scene image into its individual objects. Returns a list of detected objects with a preview, which you then review and confirm before any generation runs. Everything is selected by default.

* **Input:** an image of a scene, and optionally the object categories to look for
* **Output:** a set of detected objects
* **Cost:** 20 credits per run

You can run it again with different categories if the decomposition isn't right — each run costs the same 20 credits. See [Detecting & selecting objects](/marso-studio/scenes/detecting-and-selecting-objects).

#### Generate Reference Images

Generate a clean reference image for each object you selected, ready for 3D reconstruction.

* **Input:** the confirmed object selection
* **Output:** one reference image per object
* **Cost:** 10 credits per object

> Each object needs to fill most of its reference image for 3D generation to succeed. Objects that were small or heavily occluded in the scene are the usual failures.

### Image

#### Image Upload

Upload an image to use as a starting point in your pipeline.

* **Input:** image file
* **Output:** image
* **Cost:** no credits

#### Image Generation

Generate an image from a text prompt.

* **Input:** text prompt
* **Output:** image
* **Cost:** 10 credits

#### Multiview

Generate a multi-view set of an object from a single image — useful for a stronger 3D reconstruction.

* **Input:** image
* **Output:** multiple views of the object
* **Cost:** 2 credits

#### Image Edit

Edit or refine an existing image with a prompt.

* **Input:** image + prompt
* **Output:** edited image
* **Cost:** 10 credits

### 3D

#### 3D Model Upload

Upload your own 3D asset (`.glb`, `.usdz` or `.fbx`). See [3D file support](/marso-studio/preparing-your-assets/3d-file-support). This is the starting node in an Individual project.

* **Input:** 3D file
* **Output:** 3D model
* **Cost:** no credits

#### Generate 3D Model

Turn an image into a 3D mesh. The object should fill most of the image — sparse or distant subjects often fail.

* **Input:** an image, or a multi-view set
* **Output:** 3D model
* **Cost:** 40 credits (single image) · 60 credits (multi-view input)

**Custom polycount** — you can set a target face count instead of taking the default. This adds **15 credits** on top of the base cost, so a single-image generation with a custom polycount is **55 credits**. Custom polycount is only available on single-image generation, not on multi-view.

### Utility

#### Generate PBR Textures

Run I2M to predict a full PBR material stack — **albedo, metallic, roughness and IOR** — for a textured mesh.

* **Input:** textured 3D model
* **Output:** textured 3D model + individual PBR maps
* **Cost:** 30 credits

Generated meshes are compressed automatically before texturing. Compression is free and needs no node.

### Credit costs at a glance

| Node                                 | Credits       |
| ------------------------------------ | ------------- |
| Scene Generation                     | 10            |
| Detect Objects                       | 20 per run    |
| Generate Reference Images            | 10 per object |
| Image Upload                         | —             |
| Image Generation                     | 10            |
| Image Edit                           | 10            |
| Multiview                            | 2             |
| 3D Model Upload                      | —             |
| Generate 3D Model (single image)     | 40            |
| Generate 3D Model (multi-view)       | 60            |
| Generate 3D Model — custom polycount | +15           |
| Generate PBR Textures                | 30            |

See [Credits & billing](/marso-studio/reference/credits-and-billing) for how credits work and how to budget a scene.


# Credits & billing

Marso Studio runs on **credits**. Every generation step spends a set number, and your balance is shown at the top of the screen at all times.

Costs scale with the work involved — generating an image is cheap, generating and texturing a 3D object costs more, and a scene costs the sum of its objects.

### What each step costs

| What you do                        | Node                      | Credits           |
| ---------------------------------- | ------------------------- | ----------------- |
| Apply PBR materials                | Generate PBR Textures     | **30**            |
| Image → 3D model (single image)    | Generate 3D Model         | **40**            |
| Images → 3D model (multi-view)     | Generate 3D Model         | **60**            |
| Custom polycount *(add-on)*        | Generate 3D Model         | **+15**           |
| Generate a scene image             | Scene Generation          | **10**            |
| Break a scene into objects         | Detect Objects            | **20**            |
| Reference images for scene objects | Generate Reference Images | **10** per object |
| Generate an image                  | Image Generation          | **10**            |
| Edit an image                      | Image Edit                | **10**            |
| Generate a multi-view image set    | Multiview                 | **2**             |
| Upload an image                    | Image Upload              | Free              |
| Upload a 3D model                  | 3D Model Upload           | Free              |
| Mesh compression                   | —                         | Free, automatic   |

See the [Nodes reference](/marso-studio/reference/nodes-reference) for what each step does.

> **Custom polycount is an add-on, not a separate step.** When you pick a custom face count on **Generate 3D Model**, the 15 credits are added to the base cost — so a single-image generation with a custom polycount is **55 credits**, not 15. It is only available on single-image generation.

### Budgeting a run

The easiest way to plan is per object, not per pipeline.

**One object, generated from scratch and textured — 80 credits:**

| Step                  | Credits |
| --------------------- | ------- |
| Image Generation      | 10      |
| Generate 3D Model     | 40      |
| Generate PBR Textures | 30      |
| **Total**             | **80**  |

**One object you already have — 30 credits.** Upload it and run Generate PBR Textures. Uploading is free.

**A scene — 30 credits up front, plus 80 per object.** The scene image and the detection are charged once; then every object you keep runs its own reference image, 3D model and PBR:

| Stage            | Calc                | Credits       |
| ---------------- | ------------------- | ------------- |
| Scene Generation | once                | 10            |
| Detect Objects   | once                | 20            |
| Reference images | 10 × objects        | 10 per object |
| 3D models        | 40 × objects        | 40 per object |
| PBR              | 30 × objects        | 30 per object |
| **Scene total**  | 30 + (80 × objects) |               |

So a ten-object scene is **830 credits**, and a twenty-object scene is **1,630**. Running detection again, if the first decomposition isn't right, is another 20. You choose how many objects to keep after detection, which is where you control the cost — see [Detecting & selecting objects](/marso-studio/scenes/detecting-and-selecting-objects).

### Free credits

You get a starting balance of free credits when you sign up, and a further allowance on any day you open Marso Studio. The daily allowance **doesn't roll over** — a day you don't log in isn't banked.

Your current balance is always shown at the top of the screen.

### Buying credits

1. Click **Credits** at the top of the screen.
2. Choose a pack:

| Pack              | Price | Roughly            |
| ----------------- | ----- | ------------------ |
| **2,000 credits** | $20   | A few scenes       |
| **5,000 credits** | $50   | Five to six scenes |

Purchased credits **don't expire**.

### Checking your balance and usage

* Your credit balance is shown at the **top of the UI at all times**.
* Node inputs show what the next step will cost before you run it.
* For a full breakdown, open your **account → Usage & billing**, where you can review both your balance and your usage.

> Scene generation is the most expensive thing you can run, because it multiplies across every object you keep. Check your balance and your selected object count before you start a large scene — see [Working with scene results](/marso-studio/scenes/working-with-scene-results) if a run stops partway.


# Previewing & exporting

When a generation finishes, inspect the result in the 3D viewer and then download it in the format you need.

### The 3D viewer

Before you export, use the viewer to check the result:

* **Multiple HDRIs** — switch between lighting environments to see how the materials respond.
* **Rotate the lighting** — spin the environment to catch reflections and highlights from different angles.
* **Show albedo** — view the base colour with the materials stripped back.
* **Compare PBR vs non-PBR** — toggle between the original asset and the textured result.

On a scene, you can open any object in the viewer as soon as it finishes — you don't have to wait for the whole group.

> The web viewer is still being refined during early access. If something looks off in the viewer, download the maps and check them before assuming the result is wrong.

### Export options

You can download either:

* **Textures only** — the individual PBR maps as **PNG** files (albedo, metallic, roughness, IOR).
* **3D mesh with embedded textures** — the full asset with its materials packed in, ready to drop into your pipeline. Files will be output as a USD file.

### Exporting a scene

A scene exports as a set of individual assets, not as one merged mesh. Each object keeps its own material set, so you can place, swap and reuse them independently once they're in your DCC.

You can download:

* **The whole scene** — every completed object in one download.
* **A single object** — any individual asset on its own.
* **Textures only** — the PBR maps for the objects you select, without the meshes.

Objects that didn't complete are skipped rather than exported empty. If part of a scene is missing from the download, check the group for failed objects and retry them — see [Working with scene results](/marso-studio/scenes/working-with-scene-results).

> Scene downloads can be large. A scene with many objects packages every mesh and every map, so give it time and check you have the disk space before you start.


# API access

Marso Studio exposes an API so you can call its generation capabilities from your own tools. Endpoints are available to authenticated users — you authenticate with an **API key** that you create in the app.

### Creating an API key

1. Log in to Marso Studio.
2. Open the **API Key** section in the left sidebar.
3. Give your key a **name** and click **Create key**.
4. **Copy the key straight away and store it somewhere safe — it is shown only once.**

> **Keep your key secret.** Treat it like a password: never commit it to source control, share it, or expose it in client-side code. If a key is ever exposed, revoke it immediately.

### Managing keys

* **Revoke** a key to stop it working immediately.
* **Delete** keys you no longer need.

You can create multiple keys — for example, one per integration — and revoke them independently.

Once authenticated, the available endpoints can be accessed from within Marso Studio.

### Credits

API generations spend credits from the same balance as the app, at the same rates. See [Credits & billing](/marso-studio/reference/credits-and-billing).


# Troubleshooting

Most issues fall into one of the categories below. If none of these solve it, see [Contact & support](/marso-studio/help-and-support/contact-support).

### My scene didn't detect the right objects

| What you see                         | Fix                                                                 |
| ------------------------------------ | ------------------------------------------------------------------- |
| Objects missing entirely             | Run **Detect Objects** again and name them explicitly in categories |
| One object split into several pieces | Re-run with a broader category for that object                      |
| Several objects merged into one      | Re-run with the individual categories named                         |
| Too much scenery detected            | Just deselect the extras — that's free                              |

If two runs don't improve things, the scene image is the problem rather than the detection. A clearer image with better-separated objects, each reasonably large in frame, detects better than any category list. See [Detecting & selecting objects.](/marso-studio/scenes/detecting-and-selecting-objects)

### Some objects in my scene failed

This is normal on larger scenes. One object failing doesn't stop the rest and doesn't invalidate the ones that worked.

* **The object probably didn't fill enough of its reference image.** This is the most common cause. 3D generation needs the object to take up the majority of the frame, so anything small, distant or heavily occluded in the original scene tends to fail. Deselect those at detection rather than paying for them.
* **Retry the individual object**, not the whole scene. You're only charged for the object and stage you re-run.
* **If a retry fails the same way twice, go back a stage.** A bad mesh is usually a bad reference image, and a bad reference image is usually an object that was too small in the scene to begin with.
* **Thin, wiry or transparent objects** are the other common failures at the 3D stage. Chains, wire fencing, glassware.

See [Working with scene results](/marso-studio/scenes/working-with-scene-results).

### I ran out of credits partway through a scene

**Objects that already completed are kept** — they're yours, and you won't be charged for them again. But the run doesn't resume on its own: **the remaining objects in that run won't complete.** Top up, then re-run the ones that didn't finish.

To avoid it next time, check the arithmetic before you start. See [Credits & billing](/marso-studio/reference/credits-and-billing).

### My scene is taking a long time

A scene runs every stage across every object you selected, so a large scene is a long run. Objects are processed in parallel, so it won't take the sum of its parts, but it will take considerably longer than a single asset. Objects appear as they finish — you can review the early ones while the rest are still running.

### My file was rejected

| Cause                                          | Fix                                                                                                       |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| No base-colour texture                         | Add an image-based base-colour texture before uploading                                                   |
| Coloured with vertex data only                 | Vertex colours aren't textures — bake to a texture map                                                    |
| Textures referenced externally (URI/file path) | Embed textures in the file, or bundle them (see below)                                                    |
| FBX zip not following the naming convention    | Name the base-colour map `game.color.png`, `color.png`, `albedo.png`, `basecolor.png` or `base_color.png` |
| A material with no texture                     | Make sure every material has a base-colour texture                                                        |

Full rules: [3D file support](/marso-studio/preparing-your-assets/3d-file-support).

### My results don't look right

* **Check the input first.** Marso Studio enhances materials but can't fix bad geometry, overlapping UVs, or a poor scan.
* **Remove any existing PBR.** Bring a clean, base-colour asset — assets that already carry PBR work against the prediction.
* **Flat-shaded AI assets predict poorly.** Generative meshes work best when shading and lighting cues are baked into the base colour.
* **Complex geometry** can produce coverage artefacts on some surfaces — try a cleaner or simpler asset to compare.

See [Sourcing & preparing assets](/marso-studio/preparing-your-assets/sourcing-and-preparing-assets).

### It looks wrong in the viewer

The web viewer is still being refined during early access. If a result looks off **in the viewer**, download and check the exported maps before assuming the generation failed.

### Generation failed or timed out

* Keep files **under 100 MB**.
* Run **one generation at a time** during early access.
* Retry once — if it fails again, grab a screenshot of any error and contact us.

***

Still stuck? → [Contact & support](/marso-studio/help-and-support/contact-support)


# Contact Support

Before reaching out, check [Troubleshooting](/marso-studio/help-and-support/troubleshooting) — it covers the most common file and generation issues.

### Discord *(fastest)*

Accept your Discord invite and post in the **#marso-studio** channel. To get help quickly, include:

* A **screenshot** of the result or error
* The **asset** you used, and where it came from
* What you **expected** vs what happened

### Email

You can also reach us at **<support@m-xr.com>**.

### Reporting an issue in early access

Marso Studio is in active development and your reports directly shape it. See the [Early access brief ](/marso-studio/getting-started/early-access-brief)for what to report.