src/README.md

# `gradio_niivueviewer`
<img alt="Static Badge" src="https://img.shields.io/badge/version%20-%200.0.1%20-%20orange">  

Python library for easily interacting with trained machine learning models

## Installation

```bash
pip install gradio_niivueviewer
```

## Usage

```python
import os
import gradio as gr
from gradio_niivueviewer import NiiVueViewer

ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
nii_path = os.path.join(ROOT, "input/FLARE_02510_0000.nii.gz")
seg_path = os.path.join(ROOT, "output/FLARE_02510.nii.gz")

# FLARE22 standard organ labels
FLARE_LABELS = {
    1: "Liver",
    2: "Right Kidney",
    3: "Spleen",
    4: "Pancreas",
    5: "Aorta",
    6: "IVC",
    7: "Right Adrenal",
    8: "Left Adrenal",
    9: "Gallbladder",
    10: "Esophagus",
    11: "Stomach",
    12: "Duodenum",
    13: "Left Kidney",
}

with gr.Blocks(title="NiiVue Medical Image Viewer") as demo:
    gr.Markdown("## NiiVue — FLARE_02510")
    NiiVueViewer(value=[nii_path, seg_path], seg_labels=FLARE_LABELS)

if __name__ == "__main__":
    demo.launch(
        server_port=7870,
        allowed_paths=[os.path.dirname(nii_path), os.path.dirname(seg_path)],
    )

```

## `NiiVueViewer`

### Initialization

<table>
<thead>
<tr>
<th align="left">name</th>
<th align="left" style="width: 25%;">type</th>
<th align="left">default</th>
<th align="left">description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>value</code></td>
<td align="left" style="width: 25%;">

```python
list[str] | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">List of NIfTI file paths. First path = main volume; second path</td>
</tr>

<tr>
<td align="left"><code>seg_labels</code></td>
<td align="left" style="width: 25%;">

```python
dict[int, str] | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Mapping of integer label value → display name for the</td>
</tr>

<tr>
<td align="left"><code>label</code></td>
<td align="left" style="width: 25%;">

```python
str | I18nData | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Label displayed above the component.</td>
</tr>

<tr>
<td align="left"><code>every</code></td>
<td align="left" style="width: 25%;">

```python
'Timer | float | None'
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Timer or interval (seconds) to periodically refresh a dynamic value.</td>
</tr>

<tr>
<td align="left"><code>inputs</code></td>
<td align="left" style="width: 25%;">

```python
'Component | Sequence[Component] | set[Component] | None'
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Components whose changes trigger a value recalculation.</td>
</tr>

<tr>
<td align="left"><code>show_label</code></td>
<td align="left" style="width: 25%;">

```python
bool | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Whether to display the label.</td>
</tr>

<tr>
<td align="left"><code>container</code></td>
<td align="left" style="width: 25%;">

```python
bool
```

</td>
<td align="left"><code>value = True</code></td>
<td align="left">Wrap in a padded container.</td>
</tr>

<tr>
<td align="left"><code>scale</code></td>
<td align="left" style="width: 25%;">

```python
int | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Relative width when placed in a Row.</td>
</tr>

<tr>
<td align="left"><code>min_width</code></td>
<td align="left" style="width: 25%;">

```python
int
```

</td>
<td align="left"><code>value = 160</code></td>
<td align="left">Minimum pixel width.</td>
</tr>

<tr>
<td align="left"><code>visible</code></td>
<td align="left" style="width: 25%;">

```python
bool | Literal['hidden']
```

</td>
<td align="left"><code>value = True</code></td>
<td align="left">Visibility of the component.</td>
</tr>

<tr>
<td align="left"><code>elem_id</code></td>
<td align="left" style="width: 25%;">

```python
str | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">HTML id attribute for the component's root element.</td>
</tr>

<tr>
<td align="left"><code>elem_classes</code></td>
<td align="left" style="width: 25%;">

```python
list[str] | str | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">HTML class(es) for the component's root element.</td>
</tr>

<tr>
<td align="left"><code>render</code></td>
<td align="left" style="width: 25%;">

```python
bool
```

</td>
<td align="left"><code>value = True</code></td>
<td align="left">If False, defer rendering until later.</td>
</tr>

<tr>
<td align="left"><code>key</code></td>
<td align="left" style="width: 25%;">

```python
int | str | tuple[int | str, ...] | None
```

</td>
<td align="left"><code>value = None</code></td>
<td align="left">Stable key for gr.render() re-render identity.</td>
</tr>

<tr>
<td align="left"><code>preserved_by_key</code></td>
<td align="left" style="width: 25%;">

```python
list[str] | str | None
```

</td>
<td align="left"><code>value = "value"</code></td>
<td align="left">Constructor parameters preserved across re-renders.</td>
</tr>
</tbody></table>


### Events

| name | description |
|:-----|:------------|
| `change` | Triggered when the value of the NiiVueViewer changes either because of user input (e.g. a user types in a textbox) OR because of a function update (e.g. an image receives a value from the output of an event trigger). See `.input()` for a listener that is only triggered by user input. |



### User function

The impact on the users predict function varies depending on whether the component is used as an input or output for an event (or both).

- When used as an Input, the component only impacts the input signature of the user function.
- When used as an output, the component only impacts the return signature of the user function.

The code snippet below is accurate in cases where the component is used as both an input and an output.

- **As output:** Is passed, list of local file paths, or None.
- **As input:** Should return, list of NIfTI file paths (absolute or relative to cwd).

 ```python
 def predict(
     value: list[str]| None
 ) -> list[str]| None:
     return value
 ```