Tutorial: Importing Data

Objective

Create a dataset, upload data to it using the method that fits your files, and check the result in the Editor.

Prerequisites

• A project and study exist. See Creating Your First Project. The Set up an analysis guide on Home can also create all three for you.
• You own the project. Collaborators can view its files but not upload.
• The files are on your computer.

Estimated Time

20 minutes.

How PhenoWorks stores data

Every file belongs to one dataset. The Editor's Data explorer shows Project › Study › Dataset › folders › files; projects and studies organize datasets but hold no files themselves.

Each file is classified when you upload it:

Label	Meaning	Examples
Modality	The sensor that captured the data. Choose Not applicable (none) for documents and other files without a sensor.	RGB, Thermal, Multispectral, Hyperspectral, LiDAR, GPR
Data product	What the file is. It decides the accepted file extensions, the viewer, and which analysis modules can read it.	Image, Orthomosaic, Point cloud, CSV, Document, GeoPackage, Shapefile, ZIP archive

Files can also carry metadata, such as plot_id, treatment, or a capture date. A plot_id groups files into one plot when an analysis runs, so modules can read a plot's RGB, NIR, and thermal files together. Files without a plot_id are analyzed one at a time.

Administrators manage the available modalities and data products, and each product's accepted extensions, under Data types.

Choose an upload method

You have	Use	Result
One file: an orthomosaic, a point cloud, a CSV of measurements, a document	Single file	The file at the dataset's top level.
Files already split by plot, such as captures from a ground robot or phenotyping platform	ZIP import	One folder per plot, each file labelled with its plot.
One field-wide orthomosaic or point cloud plus plot polygons	Plot boundaries import	One clipped file per plot, with plot and survey records.
Raw drone flight images	Drone products	Orthomosaics, elevation models, and point clouds generated by OpenDroneMap.
Many files to upload from a script or notebook	Python, R, or the CLI	Any of the first three results.

In the Editor, select Which should I use? in the upload dialog for examples of each type.

Create a dataset

1. Open Editor.
2. Right-click the study in the Data explorer and select Create dataset, or select New dataset in the explorer header and choose the study.
3. Enter a Dataset name and, optionally, a description.
4. Set the Collection date (UTC) and, optionally, search for the field's location. When a location is given, PhenoWorks fetches that day's weather in the background; Jobs shows when it finishes.
5. Select Create dataset.

The dataset appears under the study with No files yet. Right-click it and select Upload files to open the Upload dataset files dialog, which starts by asking for the Upload type.

Method 1: Single file

Use this for one file that covers the whole field or study, or to add one more file to a dataset, such as a new survey's orthomosaic.

1. In Upload type, choose Single file.

2. Under Classification, choose the Modality first, then the Data product. Only products that accept the chosen sensor are offered.

3. Under File, drop or browse for the file. The dialog lists the formats the chosen product accepts; for example, an Orthomosaic accepts GeoTIFF (.tif).

4. Optionally, open Metadata (optional) and enter a JSON object, such as:

   {"plot_id": "P001", "collected_at": "2026-06-10T10:00:00Z", "treatment": "dry"}

5. Select Upload file.

Examples:

File	Modality	Data product
field_rgb_2026-06-10.tif, a drone orthomosaic	RGB	Orthomosaic
field_scan.laz, a LiDAR scan	LiDAR	Point cloud
plots.gpkg, or plots.zip holding shapefile parts	Not applicable	GeoPackage or Shapefile
weather_station.csv, protocol.pdf	Not applicable	CSV or Document
raw_capture.zip, kept without extracting it	Not applicable	ZIP archive

The file appears at the dataset's top level. Large uploads resume after a network interruption. Orthomosaics, point clouds, and shapefiles are prepared for the map in the background; the file shows Preparing preview… until then.

Method 2: ZIP import

Use this when each plot already has its own files, for example RGB, NIR, and thermal captures. A JSON sidecar describes each plot's files, so the archive's folder names do not have to follow a fixed layout.

Prepare the archive

Each plot needs a sidecar, either inside the plot's folder (metadata.json) or beside its files at the archive root, named after the plot (1691.json):

field_captures_2026-04-14.zip
├── 9035-07/
│   ├── metadata.json            <- sidecar for plot 9035-07
│   ├── R11_C4_9035-07_RGB_Capture.png
│   ├── R11_C4_9035-07_Thermal_RawData.csv
│   └── R11_C4_9035-07_NIR_Capture.png
├── 9035-08/
│   ├── metadata.json            <- sidecar for plot 9035-08
│   └── ...
├── 1691.json                    <- sidecar at the root, beside its image
└── 1691.JPG

A sidecar lists the plot's files and their classification:

{
  "plot_id": "9035-07",
  "date_taken": "2026-04-14T12:28:07-05:00",
  "lat": null,
  "lon": null,
  "treatment": "dry",
  "soil_moisture_pct": 32.1,
  "files": [
    {"path": "R11_C4_9035-07_RGB_Capture.png", "data_product": "image", "modality": "rgb"},
    {"path": "R11_C4_9035-07_Thermal_RawData.csv", "data_product": "csv", "modality": "thermal"},
    {"path": "R11_C4_9035-07_NIR_Capture.png", "data_product": "image", "modality": "multispectral", "bands": ["nir"]}
  ]
}

Field	Required	Meaning
plot_id	Yes	The plot the files belong to. Files sharing a plot_id are analyzed together.
files[].path	Yes	The file, relative to the sidecar's folder or the archive root.
files[].data_product	Yes	Catalog key such as image, orthomosaic, point_cloud, or csv.
files[].modality	Yes	Catalog key such as rgb, thermal, or multispectral; none for files without a sensor.
date_taken	No	Capture time in ISO 8601. Include the time-zone offset; a time without one is read as UTC. Can also be set per file.
lat, lon, rep	No	Plot location and replicate number.
files[].bands, files[].sensor_name, files[].processing_method	No	Named spectral bands, the camera or scanner model, and how a derived product was made.
Any other key	No	Kept as metadata on every file of the plot, such as treatment.

Follow these rules:

• Use catalog keys (rgb, image), not display labels (RGB, Image).
• Every .json file in the archive is read as a sidecar, so do not include other JSON files.
• A file's extension must be one its data product accepts.
• Instead of one sidecar per plot, you can put a single metadata.json at the archive root whose files list gives each entry its own plot_id in a metadata object.

The Python SDK CLI can write sidecars for you: phenoworks create-metadata writes one per file in a folder, using the file name as the plot ID, and phenoworks translate-metadata converts plot folders that contain a *_metadata.csv.

Upload it

1. In Upload type, choose ZIP import. Select Show example to see a sample archive and the sidecar fields.
2. Under Archive, add the ZIP.
3. Select Upload and import.

The dialog closes once the archive is uploaded and its import is queued; extraction continues in the background, and files appear as they are imported. Each plot's files land in a folder named after the plot. A plot folder that already contains the plot ID, such as 9035-07/ or R1_C1_9035-07/, is kept rather than nested again.

The import commits all files or none. It rejects unsafe paths, symbolic links, missing files, unknown classifications, and paths already present in the dataset. If it fails, the ZIP stays in the dataset with the error; fix the cause and right-click the ZIP to select Import ZIP contents without uploading it again.

Method 3: Plot boundaries import

Use this to split one georeferenced map of the field into a file per plot, so per-plot analyses can run on data captured for the whole field at once.

You need:

• An orthomosaic (GeoTIFF) or a point cloud (LAS/LAZ), from a drone, LiDAR scanner, or photogrammetry.
• Plot polygons in a GeoPackage or a zipped shapefile (including its projection and attribute files), one polygon per plot, with an attribute holding each plot's ID.

Both files must declare their coordinate reference systems; the boundaries are reprojected to match the map.

1. In Upload type, choose Plot boundaries import.
2. Under Files, add the map under Orthomosaic or point cloud and the polygons under Plot boundaries. The data product is detected from the file extension.
3. Choose the Sensor that captured the map.
4. Select Upload and continue. Both files upload and are processed.
5. The Plot boundaries import dialog opens. Check the Plot boundaries file and choose the Plot ID field, the attribute holding each plot's ID. PhenoWorks preselects a field named like plot_id, plot, or plot_code.
6. Leave Survey (optional) at By capture date, or choose a survey.
7. Select Import plots.

Both source files are kept. When the background import finishes, a new folder named after the source holds one folder per plot with its clipped raster or point cloud. Unlike the other methods, this import also creates the dataset's plot records and a survey for the capture date.

If the map and boundaries are already in the dataset, right-click the orthomosaic or point cloud and select Plot boundaries import… instead.

Method 4: Drone products from flight images

Administrators who own the project can turn a ZIP of raw flight images into maps with OpenDroneMap. Upload the images as a Single file with the ZIP archive data product, then right-click the dataset and select Drone products. Choose the ZIP, the products to generate, and a processing preset, then select Schedule job. The generated orthomosaics, elevation models, and point clouds appear at the dataset's top level, ready for a plot boundaries import. This requires the optional NodeODM service; see the repository's NodeODM guide.

Upload from code

The Python SDK, its CLI, and the R client use the same upload methods. Create an API key under API Keys in the user menu first.

from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    # Single file, with an optional processing method.
    client.upload_dataset_file(
        dataset_id=42,
        path="orthomosaic.tif",
        data_product="orthomosaic",
        modality="multispectral",
        processing_method="photogrammetry",
    )
    # ZIP import with per-plot sidecars.
    client.files.import_zip(42, "field_captures_2026-04-14.zip")

phenoworks uploads dataset 42 ./orthomosaic.tif --data-product orthomosaic --modality multispectral

phenoworks files import-zip 42 ./field_captures_2026-04-14.zip

client$upload_dataset_file(42, "measurements.csv", data_product = "csv", modality = "none")
client$files$import_zip(42, "field_captures_2026-04-14.zip")

client.datasets.create_dataset_from_orthomosaic(...) and create_dataset_from_point_cloud(...) run a plot boundaries import on files already in a dataset. An Agent or MCP client can explain the methods and the sidecar format with the get_data_import_guide tool.

Surveys

A survey is one data collection, such as a drone flight on 10 June. To list, add, or rename a dataset's surveys, right-click the dataset and select Manage Surveys. A plot boundaries import joins the survey for its capture date, or the survey you pick. For other uploads, add a survey_id to the file's metadata. Keeping several surveys in one dataset lets an analysis compare the same plots across the season.

Check the result

1. Expand the dataset in the Data explorer. Each file shows its modality and data product, such as rgb · image.
2. Select a file to open it in the viewer. Maps open with Map, 2D (orthomosaics), and 3D (point clouds) tabs.
3. Use the layout buttons in the viewer toolbar (Single column, Two rows, Two columns, Four grid) and drag tabs between views to compare files.
4. Right-click a map-ready file and select Add to viewer to overlay it, such as plot boundaries on an orthomosaic. In Map layers, drag layers to reorder them, hide them, change their opacity, or select Zoom to layer. Add external layer adds an XYZ or WMS tile layer, such as satellite imagery, for the current tab.
5. The inspector shows the selected file's Properties: its modality, data product, and every metadata field. See Metadata in a file's menu also shows its processing method, survey, capture time, sensor, and bands.
6. Select Filters in the explorer to show files by modality, data product, or an exact metadata value, such as plot_id equals 9035-07. Quote a numeric-looking ID to match it as text.

Common Mistakes

• Choosing a data product that does not accept the file's extension. The dialog lists the allowed extensions.
• Using display labels (RGB) instead of catalog keys (rgb) in a sidecar.
• Including JSON files other than sidecars in a ZIP import.
• Leaving the time-zone offset out of date_taken, which shifts capture times to UTC.
• Plot boundaries without a coordinate reference system, or with duplicate or empty plot IDs.
• Uploading a field-wide map when per-plot analyses need plot files: run a plot boundaries import first.

Prepare for analysis

Before processing, confirm that plot IDs and classifications match the files. For NDVI, verify that the multispectral files include red and near-infrared bands and record their order. For RGB processing, inspect a few images for lighting and contrast issues.

Continue with Running a Workflow or ask the Agent to help select a suitable method.