1# Copyright 2024 Adam McArthur
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7#     http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""
 16# The first Open, Collaborative Framework for Infant Hip Health using AI
 17
 18
 19Retuve (from the scottish gaelic `Ri taobh` meaning `beside`) is a framework for analysing infant hips. It is designed to be a flexible and extensible framework that can be used by developers, AI researchers and clinicians.
 20
 21It takes in raw hip Ultrasound and X-Ray images, and outputs a report with the labelled images, and the results, exactly as a clinician would.
 22
 23<img src="https://raw.githubusercontent.com/radoss-org/radoss-creative-commons/main/other/224_ddh_115_%26_172535_0_diagram.jpg" alt="drawing" width="500"/>
 24
 25Attribution of the above Ultrasound Images: Case courtesy of Ryan Thibodeau from https://radiopaedia.org 172535 (https://radiopaedia.org/cases/172535)
 26
 27Attribution of the above X-Ray Images: Fraiwan, Mohammad; Al-Kofahi, Noran; Hanatleh, Omar; ibnian, ali (2022), “A dataset of DDH x-ray images”, Mendeley Data, V2, doi: 10.17632/jf3pv98m9g.2
 28
 29# Docs
 30
 31See our docs online at [https://radoss-org.github.io/retuve/retuve.html](https://radoss-org.github.io/retuve/retuve.html)
 32
 33# License
 34
 35Retuve is licensed under the Apache 2.0 License. This means that you can use it for commercial purposes, and modify it as you see fit. The only requirement is that you must provide the license with any distribution of the software.
 36
 37# Quickstart
 38
 39**Please Note that the 2D Sweep and 3D DICOMs are sythetically stitched together from 2D Graf Hips, so do not expect accurate results. We are working on getting a 3DUS Case on a Creative Commons License to have as an example.**
 40
 41To get started with Retuve, you can install it via pip:
 42
 43```bash
 44pip install git+https://github.com/radoss-org/retuve.git
 45```
 46
 47You can then run the following code to get a basic report:
 48
 49**WARNING: Before running this script, please make sure you have read the data disclaimer at `DATA_DISCLAIMER.md`.**
 50
 51
 52```python
 53import pydicom
 54from radstract.data.dicom import convert_dicom_to_images
 55from retuve.defaults.hip_configs import default_US
 56from retuve.defaults.manual_seg import manual_predict_us
 57from retuve.testdata import Cases, download_case
 58from retuve.funcs import analyse_hip_2DUS
 59
 60# Example usage
 61dcm_file, seg_file = download_case(Cases.ULTRASOUND_DICOM)
 62
 63dcm = pydicom.dcmread(dcm_file)
 64images = convert_dicom_to_images(dcm)
 65
 66hip_data, img, dev_metrics = analyse_hip_2DUS(
 67    images[0],
 68    keyphrase=default_US,
 69    modes_func=manual_predict_us,
 70    modes_func_kwargs_dict={"seg": seg_file},
 71)
 72
 73img.save("2dus.png")
 74```
 75<img src="https://raw.githubusercontent.com/radoss-org/radoss-creative-commons/main/other/ultrasound/172535_0_processed.png" alt="drawing" width="500"/>
 76
 77Attribution of the above Ultrasound Images: Case courtesy of Ryan Thibodeau from https://radiopaedia.org 172535 (https://radiopaedia.org/cases/172535)
 78
 79# Features
 80
 81- pip installable (easy to intergrate with you existing systems)
 82- Apache 2.0 Licensed
 83- AI is fully pluggable/modular
 84- Basic Web Interface bundled (through Retuve Trak)
 85- CLI Interface
 86- Swagger API Provided (through Retuve Trak)
 87
 88# Examples
 89
 90Examples can be found at https://github.com/radoss-org/retuve/tree/main/examples
 91
 92# Docs
 93
 94We have separate documentation for different use cases. Please see them all here: `retuve.docs.usecases`
 95
 96We provide high level overviews for different types of users. This includes a tailored description of Retuve, and some highlighted features:
 97
 98- For Developers: `retuve.docs.overviews.developers`
 99- For AI Researchers: `retuve.docs.overviews.ai_researchers`
100- For Clinicians: `retuve.docs.overviews.clinicians`
101
102# Modalities
103
104Retuve can analyse Hips for:
105
106- Ultrasound: `retuve.docs.modalities.ultrasound`
107- X-Ray: `retuve.docs.modalities.xray`
108
109
110# Developer Guide
111
112You can clone the repository and install the dependencies with the following command:
113
114```bash
115git clone https://github.com/radoss-org/retuve.git
116```
117
118You can then install retuve with uv, and then run the tests:
119
120**NOTE: These tests are about testing consistency between changes, and not directly testing the accuracy of the AI. See `changenotes` for tracking.**
121
122```bash
123cd retuve
124
125# Install uv if you haven't already
126curl -LsSf https://astral.sh/uv/install.sh | sh
127
128# Install dependencies
129uv sync
130
131# Generate the test data
132uv run poe testgen
133
134# Run all tests, including examples.
135uv run poe test_all
136
137# Get info on all other dev scripts
138uv run poe help
139```
140"""
141
142from importlib.metadata import version
143
144__version__ = version("retuve")
145
146
147def _print_disclaimer():
148    message = """
149**Disclaimer:**
150
151This software is an experimental tool for **Research Use Only**.
152It is intended solely for research purposes related to the diagnosis of
153Developmental Dysplasia of the Hip (DDH).
154
155This software has **NOT** been approved as a medical device by any
156regulatory agency in any country. It is not intended for clinical use,
157diagnosis, or treatment.
158
159The software is provided "as is" without any warranty, express or implied.
160Use of this software is at your own risk. The developers and contributors are
161not responsible for any consequences resulting from the use or misuse of this
162software.
163
164Please consult with qualified healthcare professionals for any medical advice
165or diagnosis.
166"""
167    print(message)
168
169
170_print_disclaimer()