Skip to main content

Custom Metadata Integration Example

This DICOM workflow demonstrates how to extract domain-specific metadata and upload it as Visual Layer custom fields, enabling powerful search and filtering capabilities. This pattern can be adapted for any specialized data type.
The DICOM converter script extracts medical imaging metadata (patient info, study details, equipment parameters) from DICOM files and converts them to searchable custom metadata fields in Visual Layer. Once uploaded, you can search and filter your dataset by any DICOM field.
This example shows how custom metadata transforms basic image browsing into domain-specific dataset analysis. The same pattern applies to e-commerce, manufacturing, research, or any field with structured metadata.

Complete Script Code

All scripts referenced in this guide (DICOM Converter, DICOM Metadata Upload, and Caption Extraction) are available with complete code and usage instructions in Useful Scripts.

​
Complete DICOM-to-Visual Layer Workflow

This section shows the complete end-to-end process for converting DICOM files and creating a fully searchable Visual Layer dataset with comprehensive medical imaging metadata.
1

Extract images and metadata from DICOM files

Use the DICOM converter script to convert DICOM files to JPG images and extract comprehensive metadata to CSV format.
2

Create Visual Layer dataset

Upload the converted JPG images to Visual Layer to create a new dataset for analysis and exploration.
3

Export dataset for media_id mapping

Export your Visual Layer dataset to obtain the critical mapping between filenames and Visual Layer’s internal media_id values.
4

Upload DICOM metadata as custom fields

Use the DICOM metadata upload script to automatically process and upload the extracted metadata as searchable custom fields.
5

Search and filter by DICOM metadata

Use Visual Layer to search and filter your medical imaging dataset by patient demographics, equipment parameters, study details, and technical settings.

​
Step 1: Convert DICOM Files

Run the DICOM converter script to extract images and metadata. See Basic Usage section below for command examples and output details.

​
Step 2: Create Visual Layer Dataset

Upload the converted JPG images from converted_images/ to Visual Layer using the web interface or API.

​
Step 3: Export Dataset Metadata

Export your dataset to get metadata.json containing the filename-to-media_id mapping required for the next step.

​
Step 4: Upload DICOM Metadata

Use the DICOM upload script to process and upload your extracted metadata: For Cloud: 
python upload_csv_with_json_mapping.py dicom_metadata.csv metadata.json \
  --dataset-id=your-dataset-id \
  --base-url=https://app.visual-layer.com \
  --api-key=your-api-key \
  --api-secret=your-api-secret
For On-premises: 
python upload_csv_with_json_mapping.py dicom_metadata.csv metadata.json \
  --dataset-id=your-dataset-id \
  --base-url=http://localhost:2080 \
  --api-key=your-api-key

​
Step 5: Search and Filter by DICOM Metadata

DICOM custom metadata displayed in Visual Layer showing patient age, manufacturer, modality, and other medical imaging fields

​
Why Custom Metadata Matters

This DICOM example shows how custom metadata transforms your Visual Layer dataset: Before custom metadata:
  • Browse images visually.
  • Basic filename-based search.
After custom metadata:
  • Filter by patient demographics (age, sex).
  • Search by equipment manufacturer and modality.
  • Query by technical parameters (slice thickness, kVp).
  • Group by study dates or series descriptions.
Apply this pattern to your domain:
  • E-commerce: Product SKU, price, category metadata for inventory analysis.
  • Manufacturing: Quality metrics, batch numbers, inspection data for QA workflows.
  • Research: Experiment conditions, sample IDs, measurements for dataset curation.

​
DICOM Converter Script

​
Prerequisites

  1. Python environment with required packages.
  2. DICOM files organized in series directories or as individual files.
  3. Sufficient disk space for converted images.

​
Installation

pip install pandas pydicom dicom2jpg opencv-python numpy

​
Script Code

View Complete Script Code

Access the full DICOM converter Python script with complete implementation in the Useful Scripts guide.

​
Basic Usage

# Convert DICOM files
python dicom_converter.py /path/to/dicom/files

# Custom output directory
python dicom_converter.py /path/to/dicom/files --output /custom/output
The script creates converted_images/ and metadata/dicom_metadata.csv with comprehensive DICOM metadata including file info, patient data, study details, equipment parameters, and acquisition settings.

​
DICOM Metadata Upload Script

Visual Layer provides a customizable script for uploading DICOM metadata extracted by the converter. This script handles DICOM-specific field types and can be modified for your specific use case.
Similar to the general custom metadata upload script in the Useful Scripts guide but includes DICOM-specific field handling (date/time formats, multi-value fields).

​
Script Features

  • Auto-detects DICOM date/time formats (YYYYMMDD, HHMMSS).
  • Handles multi-value fields and complex data types.
  • Supports cloud and on-premises installations.
  • Customizable for vendor-specific DICOM tags.

​
Script Code

View Complete Script Code

Access the full DICOM metadata upload Python script with complete implementation in the Useful Scripts guide.
 The script automatically analyzes DICOM fields and assigns appropriate types (string, datetime, float, enum, multi-enum) based on DICOM standards.

​
Troubleshooting

No DICOM files found:
  • Verify input directory contains .dcm files and check file permissions.
Conversion failures:
  • Check verbose output for specific errors.
  • Verify DICOM files can be opened with standard viewers.
Upload issues:
  • Ensure dataset ID is correct and dataset is in READY state.
  • Use --resume flag to continue interrupted uploads.

​
Adapting This Pattern

The DICOM scripts can be customized for your specific use case:
  • Modify field extraction to capture vendor-specific tags.
  • Add preprocessing for specialized protocols.
  • Extend to other formats by adapting the extraction logic.

Custom Metadata API Guide

Manual API workflow for custom metadata

Useful Scripts

Complete script implementations and examples

Creating Datasets

Dataset creation guide