{"id":21980171,"url":"https://github.com/innolitics/mdai-utils","last_synced_at":"2025-10-28T19:32:24.742Z","repository":{"id":203964613,"uuid":"709406450","full_name":"innolitics/mdai-utils","owner":"innolitics","description":"Utility functions for MD.ai. Download and upload 2D and 3D segmentation images.","archived":false,"fork":false,"pushed_at":"2024-04-20T13:05:17.000Z","size":1347,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-28T04:25:35.135Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/innolitics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-24T16:48:16.000Z","updated_at":"2024-04-20T13:05:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"4bb74d85-9763-46e7-b79b-3abc2ebaeca6","html_url":"https://github.com/innolitics/mdai-utils","commit_stats":null,"previous_names":["innolitics/mdai-utils"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innolitics%2Fmdai-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innolitics%2Fmdai-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innolitics%2Fmdai-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innolitics%2Fmdai-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/innolitics","download_url":"https://codeload.github.com/innolitics/mdai-utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245040698,"owners_count":20551308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T17:09:50.040Z","updated_at":"2025-10-28T19:32:19.696Z","avatar_url":"https://github.com/innolitics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdai-utils\n\nUtility functions for MD.ai. Download and upload 2D and 3D segmentation images.\n\n## Download data\n\n- Download all data: dicoms and annotations.\n\n```bash\npython -m mdai_utils.download_annotations \\\n--parameters myparameters.json \\\n-o ./data \\\n--download_dicoms\n```\n\nDicoms will be downloaded with the default md.ai structure:\n\n```md\n- data/mdai_uab_project_L1NprBvP_images_dataset_D_odXMLm_2023-12-13-152228/\n    - 1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421/\n      - 1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453/\n            1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414630768.dcm\n            1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414645741.dcm\n            1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414662833.dcm\n            1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414677861.dcm\n            1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414694890.dcm\n```\n\nIf the dataset is big, it will be split in parts. To merge all of them into one single folder:\n\n```bash\npython -m mdai_utils.merge_downloaded_parts \\\n  --part_folder /path/mdai_uab_project_7YNdkRbz_images_dataset_D_vbqBVJ_2023-12-05-204930_part3of3 \\\n  --remove_zip_files\n```\n\nIf the option `--create_volumes` is added (to cli or the parameters file), a 3D\nimage will be generated in parallel to the `.dcm` files:\n\n```md\n            image.nii.gz\n            volume_metadata.json\n```\n\nThe annotations/segmentations from md.ai are stored in json file.\n\n```md\n./data/mdai_uab_project_L1NprBvP_annotations_dataset_D_odXMLm_labelgroup_G_2Jy2yZ_2023-12-13-152213.json\n```\nand the masks/images are stored in a folder:\n\n```md\n./data/mdai_uab_project_L1NprBvP_annotations_dataset_D_odXMLm_labelgroup_G_2Jy2yZ_2023-12-13-152213_segmentations_2023-12-14-114011/\n```\n\nwith structure:\n\n```md\nmylabel__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414630768.nii.gz\nmylabel__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414645741.nii.gz\nmylabel__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414662833.nii.gz\nmylabel__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414677861.nii.gz\nmylabel__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286421__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610384286453__1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414694890.nii.gz\npair_data.json\nvolumes/ # Only generated with --create_volumes option\n```\n\n---\n\nOnce dicoms are downloaded locally, and they are not changed in md.ai, do not\npass the --download_dicoms option to avoid re-downloading them.\n\n## Upload 2D segmentations\n\nTo upload a single image or slice, we need its sop_instance_uid.\n\n```bash\npython -m mdai_utils.upload_annotation_slice \\\n --parameters ./tests/test_local_parameters.json \\\n --sop_instance_uid \"1.2.826.0.1.3680043.2.1125.1.75064541463040.2005072610414630768\" \\\n --label_name mylabel \\\n -i ./tests/fixtures/humanct_0002_1000_seg.nii.gz\n```\n\n## Upload 3D segmentations\n\nMD.ai works with dicoms, and use the SOPInstanceUID as the key to match slices.\nYour algorithm might work with 3D volumes, (.nrrd, .nii.gz, etc). You can convert\nan input dicom_folder to a 3D volume, and also store the mapping between the new\nvolume indices and the original dicom file, with its SOPInstanceUID.\n\n```bash\npython -m mdai_utils.dicom_to_volume -i ./tests/fixtures/humanct_0002_1000_1004 -o /tmp/humanct_0002_1000_1004.nrrd\n```\n\nParallel to the output image location, a `{image_filename}_SOPInstanceUIDs.json`\nwill be saved with the slice mappings.\n\nThis json will be used in `upload_annotation_volume`:\n\n```bash\npython -m mdai_utils.upload_annotation_volume \\\n --parameters ./tests/test_local_parameters.json \\\n --sop_instance_uids_file ./tests/fixtures/humanct_0002_1000_1004_SOPInstanceUIDs.json \\\n --label_name mylabel \\\n -i ./tests/fixtures/humanct_0002_1000_1004_seg.nii.gz\n```\n\n## Development\n\nFor information about building, running, and contributing to this code base,\nplease read the [CONTRIBUTING](CONTRIBUTING.md) page.\n\n## Data\n\nSample data for testing acquired from:\n[PROJECT: HumanCT  \u003e  SUBJECT: VHFCT1mm-Pelvis  \u003e  000-000-002](https://central.xnat.org/app/action/DisplayItemAction/search_element/xnat%3ActSessionData/search_field/xnat%3ActSessionData.ID/search_value/CENTRAL04_E04384/popup/false/project/HumanCT)\nand manually segmented using [Slicer3D](https://www.slicer.org/).\n\n## Tests\n\nCreate a copy of the test_parameters where you will provide the mdai ids needed\nto upload and download the test data.\n\n`cp tests/test_parameters.json tests/test_local_parameters.json`\n\nWe provide a tiny dataset that you can upload to a test dataset in your md.ai\ninstance. Only needed to run once: `pytest tests -rP --upload-only`.\n\n\n## Contact\n\n![innolitis_logo_primaryw400](https://github.com/innolitics/mdai-utils/assets/3021667/6f9e269f-f96e-4b27-90c5-8fb48da70901)\n\nYou can contact us directly through our [website][contact_link].\n\nIf you find a bug or have suggestions for improvement, please open a\n[GitHub issue][issue_link] or make a [pull request][pr_link].\n\n[contact_link]: https://innolitics.com/about/contact/\n[issue_link]: https://github.com/innolitics/mdai_utils/issues/new/choose\n[pr_link]: https://github.com/innolitics/mdai_utils/pulls\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnolitics%2Fmdai-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finnolitics%2Fmdai-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnolitics%2Fmdai-utils/lists"}