> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/data/data-upload.md). # Data upload Upload local files and folders to Unitlab projects or the Asset library. Learn supported formats, video and CSV settings, annotation imports, and processing. Upload files from your computer into a project to start annotation, or into the Asset library to organize and reuse them across datasets and projects. The same local picker accepts individual files and folders. In a project, you can also include supported annotation JSON with its media. | What you want to do | Available workflow | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Upload local media files or folders | Use the browser steps below, [CLI project uploads](https://docs.unitlab.ai/api-sdk-cli/clis/cli-projects-and-data-units), or [CLI Asset uploads](https://docs.unitlab.ai/api-sdk-cli/clis/cli-assets-and-folders). [Python SDK uploads](https://docs.unitlab.ai/api-sdk-cli/sdks/project-uploads) are also available. | | Import labels for the media | Use the browser's [local annotation import](/documentation/data/import-local-annotations.md) or [Python SDK annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports). | You can upload media through the CLI first, then import its labels through the browser or Python SDK. The CLI media-upload command does not import annotation JSON. ## Before you start Choose an existing project or an Assets folder where you can manage data. For a first upload, use two small, valid images with distinct filenames: ``` road-scenes/ └── images/ ├── road.jpg └── crossing.jpg ``` The project walkthrough below uploads the `images` folder. If both files are valid, you should see two image items in the destination. Selecting a folder keeps related uploads together for transfer; it does not automatically combine the images into one annotation task. ## Choose where the data should go | Destination | Use it when | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Project > Data > Upload** | You want to add new data directly to that project's workflow. | | **Data Space > Assets** | You want reusable source files that you can organize into folders, group, curate, and publish in datasets. | | **Attach** in a project | The data already exists in a dataset version and should be brought into the project without uploading the source files again. | A project upload adds to the project's own data. Attached dataset versions remain snapshots and are not destinations for new uploads. ## Upload to the Asset library ![Data Space Assets page with the New Folder menu open](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FkaZggvW6dujbqKfqeO9r%2Fdata-space-create-menu.png?alt=media\&token=f486bf59-dc3b-4e26-8758-7b82c4ccd03d) *Open Data Space > Assets. In the Folders view or inside a folder, open New Folder and select Upload Data. The Assets view also provides an Upload Data button.* In the upload dialog, set **Target Folder**. At the library root, enter the folder name. Inside an existing folder, leave the optional new-folder field empty to upload there, or enter a name to create a child folder. ## Upload inside a project ![Project Data upload modal with Local, CLI, SDK, and Storage options](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FYIMKhOzBn8nrF0VZAPxY%2Fproject-upload-modal.png?alt=media\&token=3d793031-28d6-4529-bf7f-bfe87b2e98b8) *Open the project's Data view and select Upload. The Upload data dialog offers Local, CLI, SDK, and Storage. Choose Local for files on your computer.* {% stepper %} {% step %} ### Select Local Open **Upload data** from your project or Asset library and select **Local**. {% endstep %} {% step %} ### Add files or a folder For the example, select **Upload folder** and choose `road-scenes/images`. To upload only `road.jpg`, choose **Upload files** instead. You can also drag files or folders into **Drop files to upload**. The folder picker includes supported files in subfolders. For an ordinary media folder, each file is uploaded as its own resource; selecting a folder does not automatically create a multimodal Data Group. {% endstep %} {% step %} ### Review the selection Check that the selection contains `road.jpg` and `crossing.jpg`. Use **Add more** to include more files, remove unwanted files individually, or choose **Clear all** to clear the pending selection. Add upload tags if needed. For videos, complete **Video frame settings**. A recognized LiDAR folder instead opens **3D scenes found**, where you select the scenes to include. {% endstep %} {% step %} ### Select Upload The footer **Upload** action starts the transfer. Keep the page open while files upload and watch the progress on each tile. If the selection contains annotation JSON, Unitlab uploads the media first and then imports the labels. {% endstep %} {% step %} ### Complete configuration and processing CSV files may ask how they should be annotated. Other media can require processing after the transfer reaches 100%. Wait for that work to finish before opening the resource. {% endstep %} {% step %} ### Check the result Open the destination and confirm that both example images appear with the image data family and successful processing. Open each to check the content. Resolve failed or incomplete items before importing labels or starting annotation. {% endstep %} {% endstepper %} ## Prepare files for grouped views When several files should appear together in one annotation task, use descriptive, unique filenames. For a related image set, a shared identifier and view suffix make the files easy to group later: ``` inspection-images/ ├── case_001_front.jpg ├── case_001_side.jpg ├── case_002_front.jpg └── case_002_side.jpg ``` This is a separate grouping example. Upload `inspection-images/` through **Assets** if you want to create grouped tasks afterward. Then follow [Data Groups and layouts](/documentation/data/data-groups-and-layouts.md) to match the files by `case_001`, `case_002`, and their view suffixes. {% hint style="info" %} **Folder, group, and JSON are different inputs.** Upload folder selects local media. Auto-Groups combines files already in the Asset library. Supported annotation JSON adds labels to media; it is not a general list of URLs to download or a task-group manifest. See [Import local annotations](/documentation/data/import-local-annotations.md). {% endhint %} Do not ZIP an ordinary image folder for this upload flow. The supported ZIP route is specifically for LiDAR scenes. Hidden files and operating-system metadata are skipped during folder selection. ## Video frame settings When adding videos to a project, **Video frame settings** controls how frequently frames are extracted for annotation. * Set **Annotation frequency** from **0.25 to 60 fps**. The default is 30 fps. * Enable **Use native frame rate** to use the video's original FPS, up to 60 fps. * For a batch, select **Apply to all uploaded videos** if the same setting should apply to every video. * Select **Apply**. Before upload starts, the settings icon on a video tile lets you revisit its frame rate. This frame-setting dialog applies to project video uploads. Library uploads retain the source asset for later use. ## CSV: time series or rows After uploading a CSV, Unitlab can ask **How should this file be annotated?** | Mode | Result | Configuration | | --------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Time series** | A chart for annotating ranges and points across channels | Choose one **X axis** and at least one numeric **Channel**. Mark unused columns **Ignored**, then select **Import time series**. | | **Tabular** | One annotation work item per row | Review the row preview, then select **Import as tabular**. | Available modes depend on the file's content and limits. If Tabular is the only valid mode, Unitlab can select it automatically. **Finish later** leaves the item marked **Needs configuration**; select **Configure** on its card to resume. Save CSV as UTF-8; UTF-8 with a byte-order mark is also accepted. ## Import existing annotations In a project, the Local picker can accept media, supported `.json` or `.geojson` annotations, or both in one selection. For annotations on files already in the project, select only the annotation files. This requires **Manage data** and **Create labels** permissions. Use [Import local annotations](/documentation/data/import-local-annotations.md) for accepted formats, media matching, folder examples, and troubleshooting. ## Supported source files The following table describes source media. Annotation import and export formats are separate. | Data family | Source formats and extensions | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Image | JPEG (`.jpg`, `.jpeg`), PNG (`.png`), GIF (`.gif`), WebP (`.webp`), BMP (`.bmp`), ICO (`.ico`) | | Video | `.mp4`, `.avi`, `.mov`, `.webm`, `.mkv`, `.m4v`, `.wmv`, `.flv` | | Audio | `.mp3`, `.wav`, `.ogg`, `.aac`, `.flac`, `.m4a` | | Text | Plain text (`.txt`) | | HTML | `.html`, `.htm` | | Medical | DICOM (`.dcm`), NIfTI (`.nii`, `.nii.gz`), single-file NRRD (`.nrrd`) | | Document | PDF (`.pdf`) | | Time series | CSV (`.csv`), configured as a chart with an X axis and numeric channels | | Tabular | CSV (`.csv`), configured as rows, with one annotation item per row | | Geospatial | GeoTIFF and COG (`.tif`, `.tiff`, `.cog`, `.geotiff`, `.gtif`, `.gtiff`), georeferenced JPEG 2000 (`.jp2`), ERDAS IMG (`.img`), NITF (`.ntf`, `.nitf`) | | Pathology | `.svs`, `.avs`, `.ndpi`, `.scn`, `.bif`, `.svslide`, tiled or pyramidal TIFF (`.tif`, `.tiff`), and single-file OME-BigTIFF including `.tf2`, `.tf8`, `.btf` | | LiDAR / point cloud | `.pcd`, `.bin`, `.ply`, or a folder/`.zip` containing a scene | TIFF files are classified by their content: a regular image, geospatial raster, or pathology slide. Geospatial rasters need a coordinate reference system and affine geotransform. Pathology upload supports a single slide file; MRXS sidecar datasets and multi-file OME datasets are not supported. DICOM files without a conventional extension can also be recognized from their content. Upload related DICOM files together so they can be grouped into the appropriate medical volume. NIfTI and NRRD are single-file volumes. Project medical uploads include finalization when related files need to be assembled into volumes. The upload picker also recognizes `.svg`, but successful image processing is not assured. Convert SVG artwork to PNG or JPEG before uploading it for annotation. ### LiDAR scenes and camera files PCD supports ASCII, binary and compressed binary encodings. PLY supports ASCII and both little-endian and big-endian binary point data. BIN uses headerless float32 points, including KITTI-style `x y z intensity` data. A scene folder or ZIP can contain multiple point-cloud frames, optional JPEG/PNG camera images (`.jpg`, `.jpeg`, `.png`), and an optional `scene.json` describing sensors, frames, calibration and poses. A ZIP must contain scene data; a ZIP of unrelated files is not treated as a scene. The folder uploader recognizes supported nuScenes dataset layouts and prepares one scene per recording from their metadata. It imports keyframes rather than intermediate sweeps. In **3D scenes found**, review the detected scenes and any missing files before selecting **Upload N scenes**. Follow [LiDAR Annotation](/documentation/annotations/lidar-annotation.md#prepare-lidar-data) for folder trees, complete scene manifests, camera calibration, point-cloud encodings, upload limits, and downloadable examples. See [Export formats and source inclusion](/documentation/releases/export-formats-and-source-inclusion.md) for annotation outputs. ## Processing, limits, and failures ![Data Space folders after ingestion](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F2KQcwfm4EbhGeUaipbJa%2Fassets-folders.png?alt=media\&token=3685bc54-6204-4a4e-a918-84c798aac689) *The example upload should add `road.jpg` and `crossing.jpg` to the destination. Check their processing states before opening them; transfer completion does not guarantee that an item is ready.* File-size limits depend on the data family and deployment. Workspace usage quotas still apply. The uploader reports unsupported extensions, unreadable files, and exceeded limits. A file accepted by the picker still has to pass content validation and processing. | What you see | What to do | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Processing N/M** while choosing files | Wait for the browser to inspect the selection and prepare previews. | | A transfer percentage on a file tile | Keep the page open while the file uploads. | | **Finalizing medical session…** | Wait while related medical files are assembled. | | **Processing** in the data grid | Server ingestion is still running. Wait before opening the item. | | **Needs configuration** | Select **Configure** to finish the CSV setup. | | A failed-ingestion retry badge | Inspect its tooltip. For supported families, click the badge to retry after resolving the cause. | | Annotation matching or format error | Correct the JSON or media reference, remove the invalid selection, and add the corrected file. See [Import local annotations](/documentation/data/import-local-annotations.md). | Upload sessions and processing summaries help you inspect a batch. A batch with no items still processing can still contain failed items, so check failures as well as completion counts. ## Continue the operating flow * Organize reusable files in Assets folders and add metadata or tags. * Combine related files with [Data Groups and layouts](/documentation/data/data-groups-and-layouts.md). * Publish validated Asset library data as a dataset version. * Review imported labels in the project before creating an annotation release. *** > **Continue with Unitlab:** [training-data curation workflows](https://unitlab.ai/en/data-curation)