Guide · Importing

Importing films and clinical data

Point SpineContour at a folder of radiographs, and optionally at a CSV of clinical data. The CSV attaches to films by file name, so naming your files well does most of the work.

Two ways to bring in films

Workspace · a whole folder

Choose folder on the Workspace screen. Subfolders are included, and this is the only path that takes a clinical CSV.

Studies · one film

Choose radiograph, or drag a file onto the Studies screen. One film at a time, and no CSV is read at that moment.

A film dropped on the Studies screen can still pick up its clinical row later, using Import from CSV in the study drawer, provided a workspace CSV has already been loaded.

What the folder scan accepts

File types: .dcm .dicom .png .jpg .jpeg .tif .tiff .bmp .webp. Case does not matter. Files are recognised by extension, so a DICOM saved without one is skipped.
Subfolders are searched, however deep. Shortcuts, symlinks and junctions are never followed.
Everything else is skipped silently and reported only as a count: unsupported files, links and unreadable subfolders share one number. If the count looks high, something is being missed.
Single films are capped at 50 MB when dropped or picked individually. A folder load has no such cap.

The clinical CSV

One row per study. The only column SpineContour requires is study_id, and its value must be the film's file name without the extension.

study_id	age	sex	diagnosis
`sub225_pre-op_10-23-2023`	61	F	Degenerative scoliosis
`sub225_post-op_3-22-2024`	62	F	Degenerative scoliosis

Those rows match sub225_pre-op_10-23-2023.jpg and sub225_post-op_3-22-2024.jpg. Matching ignores case and surrounding spaces. The header itself is forgiving: study_id, Study ID and studyId are all understood.

Commas only, saved as UTF-8. Quoted fields and Windows or Mac line endings are all fine. Excel's Save as CSV UTF-8 works.
The first row is always the header. There is no headerless mode.
50 MB limit on the CSV file.

Which columns are read

Study fields

`subject_id`, `subject`	Subject
`timepoint`, `visit`	Timepoint
`study_date`, `film_date`	Film date
`view`, `position`	View

A column called just date is not recognised. Name it film_date.

Clinical fields

Age, Sex, BMI, Diagnosis, ODI, Treatment plan, Surgical history, Follow-up and Notes are matched automatically from your column names.

Anything else appears as Unmapped. Map it to one of those nine by hand, or keep it under its own name, as described below. Columns left unmapped are not imported.

Check the mapping before you load

Column names are matched loosely, by prefix, so a column named agent will be offered as Age. Glance at the mapping screen before loading rather than after.

Keeping columns SpineContour does not know

Any other column in your CSV, such as smoker, pain_vas or levels_fused, can be imported as a custom clinical field named after its header. In the column-mapping card, open that column's dropdown and choose Keep column name (the header). The name is trimmed of surrounding spaces.

A kept column behaves like any mapped one. Load workspace attaches its values to the matched studies, the Parameters table lists it after the nine known fields, and both CSV exports include it.

To keep everything at once, use Keep N unmapped columns at the top of the card. It appears only while there are unmapped columns left. A column whose header names a known field that is still free maps to that field instead (diagnosis_text becomes Diagnosis). Columns with an empty name, reserved columns, and names already used by another column are left unmapped.
To start over, choose Unmapped in the Set all… dropdown. This clears every mapping, kept and known alike.
Some columns cannot be kept. The option is not offered when the header names a known field (map it to that field instead) or is already another column's destination. The study_id column and the four study fields have no dropdown and are never kept.

Check names before keeping everything

An unknown column can be an identifier, such as a medical record number or a patient name. Keeping all columns imports it into the study and into every CSV export. Remove those columns from the CSV, or leave them unmapped.

Loading fills blanks. It never overwrites.

This is the rule most worth knowing. A folder load only fills fields that are currently empty. Anything you have already typed, or imported before, is left alone, even if the CSV disagrees.

To replace a value, use Import from CSV in that study's drawer. That is the explicit overwrite path, one study at a time.
Blank cells never erase anything. An empty value in the CSV is skipped, not written.
If a load matches rows but changes nothing, you will see "CSV matched N row(s); no blank clinical fields to fill". That means the data was already there, not that the match failed.

When rows do not match

Situation	What SpineContour does
No `study_id` column	Refuses the file: "This CSV has no study_id column — rows cannot be linked to films."
Row matches no film	Counted as unmatched and skipped.
Two rows share a `study_id`	The first row wins. Later ones are ignored.
Two films share a name	The row attaches to neither, since it cannot tell which you meant.
Blank `study_id`	Row is skipped.
Duplicate or blank column names	Refuses the file, because those columns cannot be mapped reliably.

Rows with too many or too few cells are quietly padded or truncated rather than rejected, so a stray comma inside an unquoted field can shift a row's values without warning. Quote any field that contains a comma.

A workable order

Name the films first, following the naming pattern. Everything downstream keys off those names.
Build the CSV from the file names. Copy the file names, strip the extensions, and use them as study_id.
Load the folder and the CSV together on the Workspace screen, and read the counts it reports before moving on.