Importing data

The eyened platform provides multiple ways to import ophthalmic images into the database. Choose the method that best fits your needs and technical expertise.

Importing via API (basic) 🔌

This method is the simplest way to import individual images using the REST API. It’s ideal for smaller imports or when building integrations with other systems.

The Eyened database follows a hierarchical structure where images are categorized into projects, patients, studies, and series, from top to bottom. When importing an image, you can specify identifiers for each level of this hierarchy. The API will either use existing database objects or create new ones based on the configuration options you provide.

Note

For a complete example of using the import API with real images, check out our example notebook.

Note

For detailed information about entity fields available for each level (Patient, Study, Series, Image), see the Metadata Fields documentation.

Single Image Import

The API provides an endpoint for importing individual images and their associated metadata for project, patient, study, series and the image itself:

POST /api/import/image

This endpoint accepts a JSON payload with the following structure:

{
  "data": {
    "project_name": "Project Name",    # Required: name of the project
    "patient_identifier": "Patient_1",  # Patient identifier
    "patient_props": {},                # Optional key-value properties for patient
    "study_date": "2023-05-15",        # Date of the study
    "study_props": {},                  # Optional key-value properties for study
    "series_id": "series123",           # Optional series identifier
    "series_props": {},                 # Optional key-value properties for series
    "image": "/path/to/image.jpg",     # Relative path to image
    "image_props": {                    # Optional image properties
      "Laterality": "R",               # Optional: eye laterality (R/L)
      "Modality": "ColorFundus",       # Required: image modality
      # Any other image properties (see Data Objects)
    }
  },
  "options": {
    "create_patients": true,           # Create patient if not exists
    "create_studies": true,            # Create study if not exists
    "create_series": true,             # Create series if not exists
    "create_project": true,            # Create project if not exists
    "include_stack_trace": true        # Include stack trace in error responses
  }
}

The props dictionaries at each level can include any of the fields documented in the Metadata Fields documentation. These properties are used to populate the corresponding database objects.

Caution

When importing make sure that the image path is relative to IMAGES_BASEPATH as specified in the Eyened platform setup. This could mean that files need to be relocated within this folder.