Skip to content

old stuff

Jump to bottom Edit New page
David Sarrut edited this page May 14, 2015 · 2 revisions

Main concepts

This library is a toolkit, it means that you will need to code your own application (C++). Some (hopefully) convenient tools are given to facilitate the development.

Key points:

  • The core of every study is a database.
  • One study = one database.
  • In syd, a database is a simple sqlite file, plus an additional folder that contains images. a database = 1 file + 1 folder
  • A database is composed of several tables such as Patient (with name, date of birth etc), Injection (date, radionuclide, activity etc), Dicom images, etc. The structure of a database, i.e. the list of tables and the structure of the tables is defined in a schema or a database 'type'. An initial example of database schema, is given, but the user can extend it or create from scratch his own schema.
  • A set of basic command line tools allow to perform basic operations such as creating a database, inserting/removing an element etc. Those basics tools a usually more used at the beginning of a study. We also recommand third party tools to navigate in the database with a GUI (sqlitestudio, sqlitbrowser etc).
  • Other tools are specific to a database type and allow to perform some more advanced operation such as: extracting time-activity curves in a ROI, compute time-integrated activity etc.
  • Syd contains some specific links to and from other dedicated software, for example for image registration (Elastix) or dose computation (Gate).

Three main steps:

  • define a database schema (list of tables) ; at compile time only
  • populate the database (insert patient, images etc)
  • perform computation on images

Modules

  • core: table and database definition
    • generic
    • bulk insertion
  • std_db: tables specific to patient, injection, dicom, tp
    • File management
    • Tag management
    • Patient
    • Injection (need Patient)
    • DicomSerie, DicomFile, Timepoint (need injection, patient)
  • cmd lines tools
  • logging
  • exception/error handling

List of command line tools

Use -h to know how to use those tools. Verbose can be set with -v x, x being a number. Here is a list of tools common to all database type:

  1. Create a database with sydCreateDatabase
  2. Insert patients information with sydInsert
  3. Insert injection information with sydInsert
  4. Insert dicom in the database with sydInsertDicom
  5. Select some dicom to insert timepoint with sydInsertTimepoint
  6. Convert dicom image of timepoints to mhd image with sydInsertImage
  7. Perform image registration with elastix and insert resulting deformed image with XXXX
  8. Insert ROIs (masks) into the database with XXX
  9. Perform various computation and stored results in the db

At any step, you can print some database information with sydDump.

sydCreateDatabase

sydCreateDatabase StudyDB mydb.db mydb/

Create a database of type StudyDB named mydb.db with images in the folder mydb. All the tables will be created (empty). Use sydCreateDatabase -l to get the list of available database type. Warning this command will erase all content of the file mydb.db if already exist.

sydInsert

sydInsert mydb.db Patient JohnFoo 1 82

This example insert a new patient named JohnFoo. First number '1' indicate the number (id) of the patient in the study. It is of course unique (two patients cannot have the same id). The next number '82' is the weight of the patient. To know what list of parameters, just type sydInsert mydb.db Patient without additional arguments, it will display the help. More generally replace 'Patient' by the name of a table to display help.

sydDump

sydDump mydb.db
sydDump mydb.db Patient
sydDump mydb.db DicomSerie

Display basic information about a database or a table.

sydInsertDicom

sydInsertDicom -v1 mydb.db JohnFoo folder\_with\_dicom/ -i Indium111 -f

This tool search for dicom files into the given folder. Sort according to dicom series and copy the file to the database. Dicom must be associated with a patient and an injection.

Patient identification. We try to identify the patient with the dicom tag "PatientID". However, it is not rare that the same patient is associated with several PatientID, so this check is optional with the flag -f.

sydDumpDicom

TODO. option to print all tags.

sydInsertTimepoint

Use to create Timepoint. You need to provide: the patient, the injection, a tag and a list of DicomSerie ids.

  • The patient can be the name or the study_id.

  • The injection can be the id or the radionuclide name (there is an error if several injection match the name).

  • The tag is used to group together all timepoints of all patients. It is useful for example to group timepoints by type of - reconstruction parameters.

  • The list of DicomSerie ids will be parsed and group to

      sydInsert bidon.db Tag "study1" "Timepoint list with reconstruction 10 subsets"
  sydDumpDicom bidon.db jm IRACSCRR -r
  sydInsertTimepoint -v5 bidon.db jm Indium study1 156 85 105 118 128 132 144 156

Development

Main classes

  • syd::DatabaseManager
  • syd::Database
  • syd::Table
  • syd::TableBase

Database CRUD (Create Read Update Delete)

The schema of a database is defined at compile time by C++ classes, thanks to odb. Database types can be known at runtime via plugins. Schema can be modified (under some conditions). Main classes are: syd::PluginManager and syd::DatabaseManager.

  • Create

      syd::PluginManager::GetInstance()->Load();
  syd::DatabaseManager * m = syd::DatabaseManager::GetInstance();
  syd::CreateDirectory("test");
  syd::Database * db = m->Create("StudyDB", "test.db", "test");

    "StudyDB" is the name of the database schema.

      syd::StudyDatabase * db = m->Create<syd::StudyDatabase>("test.db", "test");

  • Read

      // Without specifiyng the db type (pointer to a generic database)
  syd::Database * dbref = m->Read("test.db");
  // or if the db type is known
  syd::StudyDatabase * dbref = m->Read<syd::StudyDatabase>("test.db");

  • Update

      // TODO

  • Delete

      // Just delete the file+folder

Table CRUD (Create Read Update Delete)

The example is given with the table syd::Patient, but it is similar for other table type

  • Create

      syd::Patient p; // create an element of the table Patient
  p.name = "toto";
  db->Insert(p);

    The patient p is inserted and saved in the db after. The id of the patient is automatically chosen after the insertion.

  • Read

      syd::Patient p = db->QueryOne(odb::query<syd::Patient>::name == "toto");

    or

      std::vector<syd::Patient> patients;
  db->Query(patients); // all patients;

    or

      db->Query(odb::query<syd::Patient>::weight_in_kg > 40, patients); // all patients with weight > 40 kg

  • Update

      // Let p be a patient (from a previous query)
  p.weight_in_kg = 100; // change the weight (not yet save in the db)
  db->Update(p); // now it is save in the db

  • Delete

      db->Delete(p);

File storage strategy

A database does not store the files directly but only URL to files stored in the regular filesystem. Management of files is performed with the syd::File table. All file paths are relative to a common unique entry point (that can be a simple folder on a disk). Hash (or checksum) value of a file can be stored/used.

TODO: mhd-img ?

DICOM strategy

The database can store dicom files, thanks to sydInsertDicom tool. Dicom files are stored in two tables named syd::DicomSerie and syd::DicomFile. The basic organization of dicom is with Patient/Study/Series/SOP UID. Every dicom file can be uniquely identified with the SOP_UID (UID stands for unique identifier), stored in the syd::DicomFile table.

WARNING: the table syd::DicomSerie can contain several elements with the same dicom_series_uid because this uid is not sufficient to unambiguously identify an image: for example for some manufacturers (i.e. GE), a two table-steps SPECT acquisition share the same Series_UID and each file has its unique SOP_UID. In this case we will consider two syd::DicomSerie elements in the database. However, when an image is composed of slices provided in several files we group all the slices under the same syd::DicomSerie.

Note that every syd::DicomSerie only contains a subset of dicom information that ease the work, but not all the dicom tags (that could always be retrieved thanks to sydDumpDicom). A syd::DicomSerie element contains information about the dicom, in particular:

  • the UIDS
  • the acquisition and reconstruction date. Those dates are retrieved from the dicom tag "AcquisitionDate", "AcquisitionTime", and either

This is done with the sydDicomSerieBuilder class. See sydInsertDicom.cxx as example.

Standards tables and database schemas

The following classes are mapped to SQL tables in the sqlite databases.

A syd::ClinicDatabase manages the following tables:

  • syd::Patient: contains patient's info such as name (initials), weight, etc. A patient has several identifier: 'id' is the db one, 'name' is usually two letters initials, 'study_id' is the number of the patient in the current study (a patient could belong to a single study, just duplicate db for several study), 'dicom_id' is the id in the dicom file.

  • syd::Injection: contains information about injection (quantity in MBq, date, type of radionuclide, etc). A patient may be linked to several injections.

  • syd::DicomSerie: contains link to dicom files about an image (CT or SPECT).

  • syd::DicomSerieBuilder: to build a syd::DicomSerie object in the database by reading dicom files. Important note: dicom are identifying by the SeriesInstanceUID (unique id) for the CT images and by SOPInstanceUID for all other images.

Notion of Timepoints

Table syd::Timepoint Tag

Helpers classes

  • syd::PrintTable: to help dumping 2D table style information on screen
  • syd::Log
  • sydCommon.h
Add a custom footer
Add a custom sidebar
Clone this wiki locally