> For the complete documentation index, see [llms.txt](https://docs.saas.haut.ai/haut.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saas.haut.ai/haut.ai/haut.ai-features/upload-photos/smart-uploader-beta.md).

# Smart Uploader (beta)

How Smart Uploader parses metadata from filenames during a bulk upload, and the notation rules and pattern syntax it accepts.

{% hint style="warning" %}
**Beta Notice**

Smart Uploader feature is currently in beta. Functionality, parsing patterns, and metadata handling may change as we continue to improve the system. We recommend validating uploads on a small sample before applying them at scale. Please report any issues to our support team.
{% endhint %}

## Overview

The **Smart Uploader** allows users to upload large sets of images while automatically parsing metadata from filenames. By applying **custom parsing patterns**, the system groups images by subjects and associates metadata fields such as **subject ID, side (left/front/right), and additional study attributes**.

This feature is designed to save time, reduce manual work, and ensure consistent image organization for datasets.

## Key Capabilities

* **Dataset selection**: Upload images into an existing dataset.
* **Filename parsing**: Extract metadata from filenames using standard or custom parsing rules.
* **Automatic grouping**: Images are grouped by **subject** and **side** for analysis.
* **Custom metadata fields**: Define additional fields (e.g., `timeCode`, `productCode`, `light`, `studyNumber`, etc.) that are stored automatically in metadata.
* **Flexible upload**: Supports drag & drop or file browsing for PNG, JPEG, and WebP images (max 30MB per file).

## Filename Notation Rules

### Standard Fields

* `subject` (required): Unique subject identifier.
* `side` (optional): Defines the camera angle or view. Possible values: **Left**, **Front** (default if not set), or **Right**. If the `side` parameter is used, the order must follow: **Left → Front → Right**.

### Custom Fields

Any other field can be included as a metadata field:

* `timeCode`: Defines the order of photos. Use this field to specify the sequence in which photos should be processed or displayed.
* `productCode`
* `light`
* `studyNumber`
* `areaCode`
* …and more. These will be stored as custom metadata.

### Pattern Syntax

Use **angle brackets `< >`** to define a parsing rule.

Examples:

* **Field length**: `<4=subject>` → First 4 characters as subject ID.
* **Field name**: `<subject>`, `<side>`, `<timeCode>`
* **Value mapping** (for side images):
  * `('L'|'F'|'R')` → Left, Front, Right
  * `('LeftView'|'FrontView'|'RightView')`

### Basic Format

```regex
<length=fieldName>_<side('L'|'F'|'R')>
```

* Combine multiple segments with **separators**: `_`, `-`, space.
* camelCase and PascalCase are also supported.

#### **Examples**

* `001_F.jpg` : `<3=subject>_<side('L'|'F'|'R')>`
* `P123-Front-001.png` : `<productCode>-<side('Left'|'Front'|'Right')>-<3=subject>`

### Notes & Best Practices

* Always include **subject** and **side** in your pattern.
* Use **fixed lengths** for subject IDs when possible (e.g., `<3=subject>`).
* Use **value lists** for fields with known options (`side`, `light`).
* Test your patterns on a few filenames before batch uploads.
* Use consistent separators (`_`, `-`, space) across filenames.

## Supported Formats

* **Image types**: PNG, JPEG, WebP
* **Max size**: 30MB per image

## Photo Statuses

* **Match**: The photo name matches the required pattern/regular expression and is parsed successfully.
* **Ready**: The photo has (identified via pattern matching or manually) the required field **`subject`**. You won't be able to upload images until all images will be in status "**Ready**."

## How to upload photos

### Choose Dataset

Select an existing dataset where images will be uploaded.

### Select Filename Notation

1. Define a **parsing pattern** to extract metadata fields from filenames. Use predefined patterns or define your own.
2. Patterns tell the uploader how to split and interpret parts of the filename (e.g., subject ID, side, timecode).

In our example the filenames are

* t1\_standard\_right (2).png
* t1\_standard\_right (1).png
* t1\_standard\_left (2).png
* t1\_standard\_left (1).png
* etc.

So the pattern is:

```regex
<2=timeCode>_<light>_<side> (<subject>)
```

<figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FUnsko470aI3fXTpUJDAm%2FSmart%20Uploader.png?alt=media&amp;token=6433a487-1430-4da9-88f8-a935772fd383" alt=""><figcaption></figcaption></figure>

### Select images to upload

* Drag and drop images/folders or browse files manually.
* The system validates and applies parsing rules automatically and set status for each image.
* All images that matched the pattern will be marked as "Matched" and "Ready."<br>

  <figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FbYyZKbnoR6CzrrDGqxqP%2Fimage.png?alt=media&amp;token=4b73d093-4dd1-412c-aaba-18f21d71f815" alt=""><figcaption></figcaption></figure>
* All images that don't matched the pattern will be marked as "Not matched" and "Not ready." In this case check the pattern and filenames.

  <figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FaXwUqtCJDmvQQb1ikHYq%2Fimage.png?alt=media&amp;token=9e2b6cad-021a-442f-b389-999fd26edb1e" alt=""><figcaption></figcaption></figure>
* Check the detected data: `subject`, `side` and additional metadata

  <figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2Fw9Q9VtozKSxRC3vrV6Mg%2Fimage.png?alt=media&amp;token=6f30ffc9-b4bd-4ef2-b55a-ccb5c4722766" alt=""><figcaption></figcaption></figure>

### Sort timecodes as needed

Sort detected timecode in right order

<figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FSFRw4PxU3HFzjg0WAXCV%2FSmart%20Uploader%20-%20Sort%20timecodes.png?alt=media&amp;token=0b06644d-dc45-4016-a9f1-6c312f09470a" alt=""><figcaption></figcaption></figure>

### Upload images

Once all images are in status "Ready", you can upload them. Click on the "Upload" button to do so.

<figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FsHyyOjviRGFxG5pDXt9a%2Fimage.png?alt=media&amp;token=5edb443e-9c06-4030-bcd4-d166ec92532e" alt=""><figcaption></figcaption></figure>

## Set fields manually

If needed, you can set field values manually. To do so:

* Select images in the table using checkboxes.
* Click "Edit" in the top-right corner of the table.
* Set field values manually and click "Save."

  <figure><img src="https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FrGPGg7EgwBRsK1GulFAv%2Fimage.png?alt=media&amp;token=a1bc1827-51c0-4e09-a023-f83ceca37817" alt=""><figcaption></figcaption></figure>

***

{% hint style="warning" %}
Not a Haut.AI client yet?
{% endhint %}

<a href="https://haut.ai/book-a-demo?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button primary" data-icon="user-vneck">Book a demo</a> <a href="https://haut.ai/product/ai-skin-analysis?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button secondary" data-icon="external-link">Platform overview on haut.ai</a>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.saas.haut.ai/haut.ai/haut.ai-features/upload-photos/smart-uploader-beta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.