Package: kheops-client
kheops-clientUtility for querying data from aKheops DICOMdatabase via theDICOMWeb API.SetupInstall the Python package and command line utility using pip:python-mpipinstallkheops-clientAlternatively, the package can be built and installed from source:gitclonehttps://github.com/hirsch-lab/kheops-client.gitcdkheops-client
pythonsetup.pysdist
python-mpipinstalldist/kheops-client*.tar.gzUsageTo access a Kheops database, one requires a URL to the DICOMWeb API and anaccess token. The examples below make use of the following variables:URL="https://demo.kheops.online/api"ACCESS_TOKEN="B18jTXCzTrQzj1ZednqHUY"OUT_DIR="./downloads"The tool offers two commands:listanddownload.kheops-client--help
kheops-clientlist--help
kheops-clientdownload--helpQuery available studies and seriesQuery a list of available DICOMstudies. A table with some information about the studies will be saved in the output directory.kheops-clientliststudies\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"Query a list of available DICOMseries. Again, a table with some information about the series will be saved in the output directory.kheops-clientlistseries\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"List the available series for a particular study by providing the--study-uidargument.kheops-clientlistseries\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--study-uid"2.16.840.1.113669.632.20.1211.10000098591"It is possible to constrain the query by specifying search filters. The following query requests a list of all available series with modality CT.kheops-clientlistseries\--url"$URL"\--token"$ACCESS_TOKEN"\--search-filter"Modality""CT"\--out-dir"$OUT_DIR"Note that the search filters can be combined.kheops-clientlistseries\--url"$URL"\--token"$ACCESS_TOKEN"\--search-filter"Modality""CT"\--search-filter"PatientID""FrxHK8"\--out-dir"$OUT_DIR"On some DICOMWeb servers, the retrieved lists may be truncated due to resource limitations (a warning will be issued in that case). In that case, arguments--limitand--offsetcan be of help.kheops-clientlistseries\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--limit5\--offset10Download DICOM dataIt is possible to download single or multiple studies/series by using the download command.For example, download a specific series by providing the arguments--study-uidand--series-uid. Use option--forcedto override the data if it already exists in the output folder.kheops-clientdownloadseries\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--study-uid"2.16.840.1.113669.632.20.1211.10000098591"\--series-uid"1.2.840.113704.1.111.5692.1127829280.6"\--forcedTo download all series in a study, just omit the argument--series-uid.kheops-clientdownloadseries\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--study-uid"2.16.840.1.113669.632.20.1211.10000098591"\--forcedDetail: This is pretty much equivalent tokheops-clientdownloadstudies\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--study-uid"2.16.840.1.113669.632.20.1211.10000098591"\--forcedIt is possible to download a list of previously selected studies/series by passing a .csv file. The table must contain a named column "StudyInstanceUID" for the "studies" mode, and additionally a column "SeriesInstanceUID" for the "series" mode.kheops-clientdownloadstudies\--url"$URL"\--token"$ACCESS_TOKEN"\--out-dir"$OUT_DIR"\--in-file"path/to/file/patients_oldest_cta.csv"Further arguments/optionsFor testing, it may be useful to limit the maximum number of studies and to specify an offset:--limitand--offsetOption--dry-runruns the commands without writing any output dataOption--meta-onlypermits to download only the DICOM data structure without any bulk data.Control the verbosity level by using the flag--verbositymultiple times. Or by using the short form:-v,-vv,-vvv.Python APIThe above functionality is implemented inKheopsClient.fromkheops_clientimportKheopsClientclient=KheopsClient(url="URL",access_token="ACCESS_TOKEN")client.list_studies(...)client.list_series(...)client.download_study(...)client.download_series(...)client.search_and_download_studies(...)client.search_and_download_series(...)Further readingDICOM standardDICOM dictionary browserDICOMWeb standardPydicom(docs,api docs,github)DICOMWeb client for python(github)