TPTBox

https://tptbox.readthedocs.io/en/latest/
Admin
The Torso Processing Toolbox (TPTBox) is a multi-functional Python package for processing...
Tokens:495,926
Snippets:2,413
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install TPTBox from Source

Source: https://tptbox.readthedocs.io/en/latest/getting-started

Clone the repository and install TPTBox with development dependencies.

```bash
git clone https://github.com/Hendrik-code/TPTBox.git
cd TPTBox
pip install poetry
poetry install --with dev

```

--------------------------------

### Install TPTBox from PyPI

Source: https://tptbox.readthedocs.io/en/latest/getting-started

Use this command to install the latest stable version of TPTBox.

```bash
pip install TPTBox

```

--------------------------------

### Install Optional Dependencies for 3D Mesh Visualization

Source: https://tptbox.readthedocs.io/en/latest/getting-started

Install pyvista and vtk for 3D mesh visualization.

```bash
# 3D mesh visualisation
pip install pyvista vtk

```

--------------------------------

### Install Optional Dependencies for Deep Learning Registration

Source: https://tptbox.readthedocs.io/en/latest/getting-started

Install hf-deepali for deep learning registration capabilities.

```bash
# Deep learning registration (DeepALI)
pip install hf-deepali

```

--------------------------------

### Build Documentation Locally

Source: https://tptbox.readthedocs.io/en/latest/getting-started

Install necessary packages and serve the documentation locally for live preview or build static files.

```bash
pip install mkdocs mkdocs-material "mkdocstrings[python]"
mkdocs serve   # live-reload preview at http://127.0.0.1:8000
mkdocs build   # static build into site/

```

--------------------------------

### Install mesh3D Dependencies

Source: https://tptbox.readthedocs.io/en/latest/modules/mesh3d

Installs the necessary pyvista and vtk libraries for the mesh3D module, either directly or via the TPTBox development extras.

```bash
pip install pyvista vtk
# or via the dev extras:
poetry install --with dev


```

--------------------------------

### POI Copy Method Example

Source: https://tptbox.readthedocs.io/en/latest/api/poi

Demonstrates how to create a copy of a POI object with optional attribute overrides for zoom and rotation.

```python
>>> POI_obj = POI(...)
>>> POI_obj_copy = POI_obj.copy(zoom=(2.0, 2.0, 2.0), rotation=rotation_matrix)
```

--------------------------------

### Install Optional DeepALI Dependency

Source: https://tptbox.readthedocs.io/en/latest/modules/registration

Installs the hf-deepali package, which is required for using General_Registration and Rigid_Elements_Registration.

```bash
pip install hf-deepali   # only needed for General_Registration / Rigid_Elements_Registration

```

--------------------------------

### Load and Initialize NII Image

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Demonstrates how to create an instance of the NII class by loading a NIfTI file. This is the initial step for any image manipulation operations.

```python
nii = NII(nib.load('image.nii.gz'),seg=False)
```

--------------------------------

### Run SPINEPS Segmentation Example

Source: https://tptbox.readthedocs.io/en/latest/modules/segmentation

Demonstrates how to load a NIfTI image and run the SPINEPS segmentation pipeline. The output includes separate segmentations for vertebrae and subregions.

```python
from TPTBox import NII
from TPTBox.segmentation import run_spineps

ct = NII.load("ct.nii.gz", seg=False)
vert_seg, subreg_seg = run_spineps(ct, model="small")
vert_seg.save("vertebrae.nii.gz")
```

--------------------------------

### Example Usage of compute_max_cobb_angle

Source: https://tptbox.readthedocs.io/en/latest/api/spine

Demonstrates how to call the `compute_max_cobb_angle` function and print the results. This example assumes a pre-computed POI object.

```python
max_angle, from_vert, to_vert, apex = compute_max_cobb_angle(poi, project_2d=True)
print(f"Max Angle: {max_angle}, From: {from_vert}, To: {to_vert}, Apex: {apex}")
```

--------------------------------

### NII Class Initialization and Basic Operations

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Demonstrates how to create an instance of the NII class and perform basic operations like getting the image shape, rescaling, and reorienting the image.

```APIDOC
## NII Class Initialization and Basic Operations

### Description
This section shows how to instantiate the `NII` class and perform fundamental image manipulations such as retrieving the image shape, adjusting voxel spacing (rescaling), and changing the image orientation.

### Methods
- **`NII(nibabel_image, seg=False)`**: Constructor for the `NII` class.
  - `nibabel_image`: A nibabel `Nifti1Image` object.
  - `seg` (bool, optional): Indicates if the image is a segmentation mask. Defaults to `False`.
- **`shape`**: Property to get the dimensions of the NIfTI image.
- **`rescale(voxel_spacing)`**: Rescales the image to the specified voxel spacing.
  - `voxel_spacing` (tuple): A tuple representing the desired voxel spacing (e.g., (1, 1, 1)).
- **`reorient(axcodes_to)`**: Reorients the image to the specified anatomical axes codes.
  - `axcodes_to` (tuple): A tuple of characters representing the target orientation (e.g., ('P', 'I', 'R') for Posterior, Inferior, Right).

### Example Usage
```python
# Create an instance of NII class
nii = NII(nib.load('image.nii.gz'), seg=False)

# Get the shape of the image
shape = nii.shape

# Rescale the image to a new voxel spacing
rescaled = nii.rescale(voxel_spacing=(1, 1, 1))

# Reorient the image to a new orientation
reoriented = nii.reorient(axcodes_to=("P", "I", "R"))
```
```

--------------------------------

### Initialize BIDS_Global_info

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Instantiate the BIDS_Global_info object to create a data structure reflecting BIDS folders. Specify dataset paths, parent directories to search within, and optional keys for file naming conventions. The constructor handles validation and recursively searches specified directories for BIDS-compliant files.

```python
class BIDS_Global_info:
    """Global index of a BIDS dataset, mapping subjects to their files across multiple dataset roots."""

    def __init__(
        self,
        datasets: Sequence[Path | str] | Sequence[Path] | Sequence[str] | str | Path,
        parents: Sequence[str] | str = ["rawdata", "derivatives"],
        additional_key: Sequence[str] = ["sequ", "seg", "ovl"],
        verbose: bool = True,
        file_name_manipulation: typing.Callable[[str], str] | None = None,
        sequence_splitting_keys: list[str] | None = None,
        filter_folder: typing.Callable[[Path, int], bool] | None = None,
        additional_file_list: dict[str | Path, list[Path]] | None = None,
    ):
        """This Objects creates a datastructures reflecting BIDS-folders.

        Args:
            datasets (typing.List[str]): List of dataset paths
            parents (typing.List[str]): List of parents (like ["rawdata","sourcedata","derivatives"])
            additional_key (list, optional): Additional keys that are not in the default BIDS but should not raise a warning. Defaults to ["sequ", "seg", "ovl"].
            filter_folder: Filter function, input is the path of the folder and the level of the folder structure. Return True if we should continue searching
                        Example:
                        filter_folder = lambda p, lvl: True if (lvl != 2 or p.name in ["sub-123","sub-456"]) else False
        """
        self.count_file = 0
        if sequence_splitting_keys is None:
            from TPTBox.core.bids_constants import sequence_splitting_keys

            self.sequence_splitting_keys = sequence_splitting_keys

        self.sequence_splitting_keys = sequence_splitting_keys
        if isinstance(datasets, (Path, str)):
            datasets = [datasets]  # type: ignore
        if isinstance(parents, str):
            parents = [parents]
        assert isinstance(datasets, Sequence), "datasets is not a list"
        assert isinstance(parents, Sequence), "parents is not a list"
        self.__bids_list: dict = {}

        self.file_name_manipulation = file_name_manipulation
        # Validate
        for ds in datasets:
            ds_path = Path(ds) if isinstance(ds, str) else ds
            if not ds_path.name.startswith("dataset-"):
                print(f"[!] Dataset {ds_path.name} does not start with 'dataset-'")
        for ps in parents:
            if not any(ps.startswith(lp) for lp in parents):
                print(f"[!] Parentfolder {ps} is not a legal name")

        self.datasets = datasets
        self.parents = parents
        self.subjects: dict[str, Subject_Container] = {}
        self.verbose = verbose

        for k in additional_key:
            if k not in entities:
                entities[k] = k
            if k not in entities_keys:
                entities_keys[k] = k

        # Search and add files
        for ds in datasets:
            if not Path(ds).exists():
                raise FileNotFoundError(ds)
            for ps in parents:
                path = Path(ds, ps)
                if path.exists():
                    self.search_folder(path, ds, filter_folder)
        if additional_file_list is not None:
            for ds, file_list in additional_file_list.items():
                for f in file_list:
                    # if Path(f).is_file():
                    self.add_file_2_subject(f, ds)

        self.entities_keys = entities_keys

```

--------------------------------

### Get Index to Name Mapping

Source: https://tptbox.readthedocs.io/en/latest/api/vert_constants

Class method to get a cached dictionary mapping integer labels back to vertebra or structure names. This is the inverse of the name2idx mapping.

```python
idx2name() -> dict[int, str]
```

```python
@classmethod
def idx2name(cls) -> dict[int, str]:
    """Return a cached mapping from integer label to vertebra/structure name."""
    global _vidx2name  # noqa: PLW0603
    if _vidx2name is not None:
        return _vidx2name
    _vidx2name = {value: key for key, value in Vertebra_Instance.name2idx().items()}
    return _vidx2name
```

--------------------------------

### Initialize File-Backed Logger

Source: https://tptbox.readthedocs.io/en/latest/api/logger

Initializes a file-backed logger, automatically creating the log directory and file. Use this to set up logging for a project path.

```python
def __init__(
    self,
    path: Path | str,
    log_filename: str | dict[str, str],
    default_verbose: bool = False,
    log_arguments=None,
    prefix: str | None = None,
):
    """Initialise a file-backed logger, creating the log directory and file automatically.

    Args:
        path: Path to the folder that needs logging (usual dataset with raw/der in it).
        log_filename: The filename or the bids-conform key-value pairs as dict.
        default_verbose: Default verbose behavior when not specified in calls.
        log_arguments: If set, will print the contents in a "run with arguments" section.
        prefix: If set, will use this string as prefix instead of the automatically chosen one.
    """
    path = Path(path)  # ensure pathlib object
    # Get Start time
    self.start_time = get_time()
    start_time_short = format_time_short(self.start_time)

    self.prefix = prefix

    # Processes log_filename
    log_filename_processed = ""
    if isinstance(log_filename, dict):
        for k, v in log_filename.items():
            log_filename_processed += k + "-" + v + "_"
    else:
        log_filename_processed = log_filename + "_"
    log_filename_full = start_time_short + "_" + log_filename_processed + "log.log"

    # Creates logs folder if not existent
    log_path = Path(path).joinpath("logs")
    if not Path.exists(log_path):
        Path.mkdir(log_path)
    # Open log file
    self.f = open(log_path.joinpath(log_filename_full), "w")  # noqa: SIM115
    # calls close() if program terminates
    self._finalizer = weakref.finalize(self.f, self.close)
    self.default_verbose = default_verbose
    # Log file always start with their name and start log time
    self.print(log_filename_processed[:-1], verbose=False, ltype=Log_Type.LOG)
    self.print(f"Log started at: {start_time_short}\n", ltype=Log_Type.LOG)

    if log_arguments is not None:
        if not isinstance(log_arguments, dict):
            self.print("Run with arguments", log_arguments, "\n", ltype=Log_Type.LOG)
        else:
            self.print("Run with arguments:", ltype=Log_Type.LOG)
            for k, v in log_arguments.items():
                self.print("-", k, "=", v, Log_Type.LOG, ignore_prefix=True)
            self.print(ignore_prefix=True)

    self.sub_loggers: list[String_Logger] = []
```

--------------------------------

### Shift Point by Normal Vector

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Calculates a new point by shifting a starting point along a normal vector. Handles conversion of the start point if it's a Location object.

```python
start_point_np = to_local_np(start_point, bb, poi, vert_id, log) if isinstance(start_point, Location) else start_point
if start_point_np is None:
    return None
return start_point_np + normal_vector * shift
```

--------------------------------

### Create and Manipulate NII Image Instance

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Demonstrates creating a NII image instance from a NIfTI file, accessing its shape, and performing rescaling and reorientation operations. Requires the nibabel library to be installed.

```python
import nibabel as nib
from TPTBox.core.nii_wrapper import NII

# Create an instance of NII class
nii = NII(nib.load('image.nii.gz'),seg=False)

# Get the shape of the image
shape = nii.shape

# Rescale the image to a new voxel spacing
rescaled = nii.rescale(voxel_spacing=(1, 1, 1))

# Reorient the image to a new orientation
reoriented = nii.reorient(axcodes_to=("P", "I", "R"))

```

--------------------------------

### Get Name to Index Mapping

Source: https://tptbox.readthedocs.io/en/latest/api/vert_constants

Class method to get a cached dictionary mapping vertebra and associated structure names (ribs, IVDs, endplates) to their integer labels. This is useful for quick lookups.

```python
name2idx() -> dict[str, int]
```

```python
@classmethod
def name2idx(cls) -> dict[str, int]:
    """Return a cached mapping from vertebra/structure name to integer label.

    Names include plain vertebra names (e.g. ``"L1"``) as well as derived names
    for ribs, IVDs, and endplates (e.g. ``"L1_rib"``, ``"L1_ivd"``).
    """
    global _vname2idx  # noqa: PLW0603
    if _vname2idx is not None:
        return _vname2idx
    name2idx = {}
    for instance in Vertebra_Instance:
        name2idx[instance.name] = instance.value
        for structure in ["rib", "ivd", "endplate"]:
            attrname = f"_{structure}"
            assert hasattr(instance, attrname)
            attr = getattr(instance, attrname)
            if attr is not None:
                name2idx[instance.name + attrname] = attr
    _vname2idx = name2idx
    return name2idx
```

--------------------------------

### __init__

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Initializes the BIDS object, creating a data structure that reflects BIDS folders. It accepts a list of dataset paths, parent directory names, and additional keys to include. Optional parameters allow for custom file name manipulation and folder filtering.

```APIDOC
## __init__ BIDS Object

### Description
Initializes the BIDS object, which creates a data structure that reflects BIDS folders. It accepts a list of dataset paths, parent directory names, and additional keys to include. Optional parameters allow for custom file name manipulation and folder filtering.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **datasets** (Sequence[Path | str] | Sequence[Path] | Sequence[str] | str | Path) - Required - List of dataset paths.
* **parents** (Sequence[str] | str) - Optional - List of parents (like ["rawdata","sourcedata","derivatives"]). Defaults to `['rawdata', 'derivatives']`.
* **additional_key** (Sequence[str]) - Optional - Additional keys that are not in the default BIDS but should not raise a warning. Defaults to `['sequ', 'seg', 'ovl']`.
* **verbose** (bool) - Optional - Verbosity flag. Defaults to `True`.
* **file_name_manipulation** (Callable[[str], str] | None) - Optional - Function to manipulate file names.
* **sequence_splitting_keys** (list[str] | None) - Optional - List of keys for splitting sequences.
* **filter_folder** (Callable[[Path, int], bool] | None) - Optional - Filter function, input is the path of the folder and the level of the folder structure. Return True if we should continue searching. Example: `filter_folder = lambda p, lvl: True if (lvl != 2 or p.name in ["sub-123","sub-456"]) else False`.
* **additional_file_list** (dict[str | Path, list[Path]] | None) - Optional - Dictionary of additional files to include.

### Request Example
```python
from pathlib import Path

# Example usage:
# bids_obj = BIDS(
#     datasets=["path/to/dataset1", "path/to/dataset2"],
#     parents=["rawdata", "derivatives"],
#     additional_key=["eeg", "ieeg"],
#     filter_folder=lambda p, lvl: lvl < 3
# )
```

### Response
#### Success Response (200)
This method initializes the BIDS object and does not return a value directly. The object itself is populated with the BIDS data structure.

#### Response Example
None
```

--------------------------------

### strategy_shifted_line_cast

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Performs a lateral shift on a starting point and then uses ray casting to find a boundary on the subregion surface. This strategy is useful for identifying POI landmarks by displacing the start point and then casting a ray.

```APIDOC
## strategy_shifted_line_cast

### Description
This function implements a strategy to find a landmark by first laterally shifting a starting point and then performing a ray cast to the subregion surface. It optionally displaces the `start_point` and then delegates to `strategy_line_cast`.

### Method
```python
def strategy_shifted_line_cast(
    poi: POI,
    current_subreg: NII,
    location: Location,
    vert_id: int,
    bb: tuple[slice, slice, slice] | None,
    regions_loc: list[Location] | Location,
    normal_vector_points: tuple[Location, Location] | DIRECTIONS,
    start_point: Location = Location.Vertebra_Corpus,
    log: Logger_Interface = _log,
    direction: DIRECTIONS = 'R',
    do_shift: bool = True
) -> None
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Name | Type | Description | Default |
|---|---|---|---|
| `poi` | `POI` | `POI` object that will receive the new landmark at `(vert_id, location.value)`. | _required_ |
| `current_subreg` | `NII` | Cropped subregion `NII` aligned to the vertebra bounding box. | _required_ |
| `location` | `Location` | Target `Location` enum member identifying the landmark slot. | _required_ |
| `vert_id` | `int` | Vertebra identifier (integer label). | _required_ |
| `bb` | `tuple[slice, slice, slice] | None` | Bounding-box slices mapping local to global voxel coordinates. | _required_ |
| `regions_loc` | `list[Location] | Location` | Label(s) to extract from `current_subreg` as the target region for the ray cast. | _required_ |
| `normal_vector_points` | `tuple[Location, Location] | DIRECTIONS` | Ray direction — a `DIRECTIONS` string or a pair of `Location` members. | _required_ |
| `start_point` | `Location` | Ray origin before shifting. | `Vertebra_Corpus` |
| `log` | `Logger_Interface` | Logger for warning and error messages. | `_log` |
| `direction` | `DIRECTIONS` | Lateral direction for the shift (`"R"` or `"L"`). | `'R'` |
| `do_shift` | `bool` | When `False`, skip the lateral shift and use `start_point` directly. | `True` |

### Request Example
None

### Response
#### Success Response (200)
None (This function returns `None`)

#### Response Example
None
```

--------------------------------

### shift_point

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Shifts a POI start point laterally by a fraction of the vertebra width. It estimates the vertebra width using anatomical landmarks and returns a new coordinate displaced from the start point along a specified direction.

```APIDOC
## shift_point

### Description
Shifts a POI start point laterally by a fraction of the vertebra width. Estimates the vertebra width from articular-process or costal-process POIs and returns a new coordinate displaced from `start_point` along `direction` by a scaled fraction of that width. Sacrum vertebrae without arcus are skipped.

### Function Signature
```python
shift_point(poi: POI, vert_id: int, bb: tuple[slice, slice, slice] | None, start_point: Location = Location.Vertebra_Corpus, direction: DIRECTIONS | None = 'R', log: Logger_Interface = _log) -> np.ndarray | None
```

### Parameters
#### Required Parameters
- **poi** (`POI`): POI object with pre-computed anatomical landmarks.
- **vert_id** (`int`): Vertebra identifier (integer label).
- **bb** (`tuple[slice, slice, slice] | None`): Bounding-box slices used to convert global POI coordinates to local coordinates within the cropped sub-volume.

#### Optional Parameters
- **start_point** (`Location`): Location enum member or already-resolved numpy coordinate from which the shift originates. Defaults to `Location.Vertebra_Corpus`.
- **direction** (`DIRECTIONS | None`): Anatomical direction letter (`"R"`, `"L"`, etc.) for the shift, or `None` to return the raw local start point without shifting. Defaults to `'R'`.
- **log** (`Logger_Interface`): Logger used for warning and error messages. Defaults to `_log`.

### Returns
- **`np.ndarray | None`**: Shifted voxel coordinate as a 3-element numpy array, or `None` when required POIs are missing or the vertebra is excluded.
```

--------------------------------

### __init__

Source: https://tptbox.readthedocs.io/en/latest/api/registration

Initializes a multi-stage registration pipeline from an atlas to a target image. This is the primary constructor for setting up the registration process.

```APIDOC
## __init__

### Description
Initializes a multi-stage registration pipeline from an atlas to a target image.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **target_seg** (`NII`) - Required - Target image segmentation (e.g., from a subject).
- **atlas_seg** (`NII`) - Required - Atlas image segmentation (e.g., a reference or template).
- **target_img** (`NII | None`) - Optional - Target image if None the segmentation is used as an image.
- **atlas_img** (`NII | None`) - Optional - Atlas image if None the segmentation is used as an image.
- **poi_cms** (`POI | None`) - Optional - POI centroids of the atlas, used for initial point registration.
- **same_side** (`bool`) - Optional - Whether atlas and target represent the same body side. Default: `True`.
- **verbose** (`int`) - Optional - Verbosity level for logging. Default: `99`.
- **gpu** (`int`) - Optional - GPU device ID (only relevant if using GPU). Default: `0`.
- **ddevice** (`DEVICES`) - Optional - Device type ('cuda' or 'cpu'). Default: `'cuda'`.
- **loss_terms** (`dict`) - Optional - Dictionary of loss terms for deformable registration.
- **weights** (`dict`) - Optional - Weights for the loss terms.
- **lr** (`float`) - Optional - Learning rate for deformable registration optimizer. Default: `0.01`.
- **lr_end_factor** (`float | None`) - Optional - Learning rate end factor.
- **max_steps** (`int`) - Optional - Maximum optimization steps. Default: `1500`.
- **min_delta** (`float | list[float]`) - Optional - Minimum delta for convergence. Default: `1e-06`.
- **pyramid_levels** (`int`) - Optional - Number of resolution levels in multi-scale deformable registration. Default: `4`.
- **coarsest_level** (`int`) - Optional - Coarsest level index. Default: `3`.
- **finest_level** (`int`) - Optional - Finest level index. Default: `0`.
- **crop** (`bool`) - Optional - Whether to crop the images. Default: `True`.
- **cms_ids** (`list | None`) - Optional - List of segmentation labels used to extract POI centroids.
- **poi_target_cms** (`POI | None`) - Optional - Optional precomputed centroids for the target image.
- **max_history** (`int`) - Optional - Maximum history for optimization. Default: `100`.
- **change_after_point_reg** (`lambda`) - Optional - Function to modify registration after point registration.
- **
**args** - Additional keyword arguments passed to Deformable_Registration.

### Raises
- **ValueError**: If an invalid axis is detected during flipping.

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### max_distance_ray_cast_convex_np

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Calculates the exit point of a ray cast into a convex region defined by a binary numpy array. It handles cases where the start coordinate is outside the region and returns the start coordinate unchanged. The function uses `RegularGridInterpolator` and bisection to find the boundary.

```APIDOC
## max_distance_ray_cast_convex_np

### Description
Finds the exit point of a ray cast into a convex region (numpy array input). It uses `RegularGridInterpolator` and bisection to locate the boundary of a convex binary region along the given direction vector.

### Method Signature
`max_distance_ray_cast_convex_np(region: ndarray, start_coord: COORDINATE | ndarray, direction_vector: ndarray, acc_delta: float = 5e-05, max_v: int | None = None) -> np.ndarray | None`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **region** (ndarray) - Required - Binary 3D numpy array where values > 0.5 are considered inside.
- **start_coord** (COORDINATE | ndarray) - Required - Starting coordinate `(x, y, z)` of the ray. If already outside the region the start coordinate is returned unchanged.
- **direction_vector** (ndarray) - Required - Direction of the ray; will be normalised internally.
- **acc_delta** (float) - Optional - Bisection convergence threshold in voxel units. Defaults to 0.00005.
- **max_v** (int | None) - Optional - Upper bound for the bisection search (in voxels along the ray). Defaults to `sum(region.shape)` when `None`.

### Request Example
None

### Response
#### Success Response (200)
- **ndarray | None** - 3-element numpy array with the approximate exit coordinate, or the start coordinate if it lies outside the region. Returns `None` when `start_coord` is `None`.

#### Response Example
None
```

--------------------------------

### open_nii

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Loads the NIfTI file into a TPTBox.NII object. Raises an error if no NIfTI file is present.

```APIDOC
## open_nii

### Description
Loads the NIfTI file into a :class:`~TPTBox.NII` object.

### Method
`open_nii()`

### Parameters
None

### Returns
- **NII** - The loaded :class:`~TPTBox.NII` volume.

### Raises
- **ValueError** - If no NIfTI file (`nii.gz` / `nii`) is present.
```

--------------------------------

### header property

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Gets the NIfTI-1 header associated with this image.

```APIDOC
## header property

### Description
NIfTI-1 header associated with this image.

### Returns
- **header** (Nifti1Header) - The NIfTI-1 header.
```

--------------------------------

### Get Vertebra Direction Unit Vector

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Use this function to get the unit vector for an anatomical direction of a specific vertebra. It requires a POI object with pre-computed landmarks and the vertebra ID. The function handles the special case for C1 by falling back to C2's direction.

```python
def get_direction(d: DIRECTIONS, poi: POI, vert_id: int, verbose: bool = True) -> np.ndarray:
    """Return the unit vector for an anatomical direction of a vertebra.

    Retrieves the pre-computed PIR orientation vectors for vertebra ``vert_id``
    from ``poi`` and returns the one corresponding to direction ``d``.  C1 has
    no independent direction and falls back to C2.

    Args:
        d: Anatomical direction letter (``"P"``, ``"A"``, ``"I"``, ``"S"``,
            ``"R"``, or ``"L"``).
        poi: ``POI`` object with pre-computed ``Vertebra_Direction_*`` landmarks.
        vert_id: Vertebra identifier.  If 1 (C1), direction is taken from C2.
        verbose: Emit a warning when C1 falls back to C2.  Defaults to ``True``.

    Returns:
        Unit vector (3-element numpy array) pointing in direction ``d`` in the
        image coordinate frame.

    Raises:
        KeyError: If orientation data for the requested vertebra is absent.
    """
    if vert_id == 1:
        _log.on_warning("C1 has no direction computation use C2 as direction", verbose=verbose)
        vert_id = 2
    P, I, R = get_vert_direction_PIR(poi, vert_id, to_pir=False)  # noqa: N806
    if d == "P":
        return P
    elif d == "A":
        return -P
    elif d == "I":
        return I
    elif d == "S":
        return -I
    elif d == "R":
        return R
    elif d == "L":
        return -R
    else:
        never_called(d)
```

--------------------------------

### General_Registration.load

Source: https://tptbox.readthedocs.io/en/latest/api/registration

Loads a previously saved General_Registration instance from a pickle file. It takes the file path and optional device placement arguments.

```APIDOC
## General_Registration.load

### Description
Loads a previously saved `General_Registration` instance from a pickle file. It takes the file path and optional device placement arguments.

### Method
classmethod

### Parameters
#### Path Parameters
- **path** (str | Path) - Required - Path to the pickle file written by :meth:`save`.
- **gpu** (int) - Optional - GPU index to map the transform to. Default: `0`.
- **ddevice** (DEVICES) - Optional - Device type (e.g. "cuda" or "cpu"). Default: `'cuda'`.

### Returns
#### Success Response
- **Self** - Reconstructed `General_Registration` instance.

### Source Code
```python
@classmethod
def load(cls, path: str | Path, gpu: int = 0, ddevice: DEVICES = "cuda") -> Self:
    """Load a previously saved ``General_Registration`` from a pickle file.

    Args:
        path: Path to the pickle file written by :meth:`save`.
        gpu: GPU index to map the transform to.
        ddevice: Device type (e.g. ``"cuda"`` or ``"cpu"``).

    Returns:
        Reconstructed ``General_Registration`` instance.
    """
    with open(path, "rb") as w:
        return cls.load_(pickle.load(w), gpu, ddevice)
```
```

--------------------------------

### Load General_Registration from File

Source: https://tptbox.readthedocs.io/en/latest/api/registration

Use this method to load a previously saved General_Registration instance from a pickle file. Specify the file path and optionally the GPU and device.

```python
@classmethod
def load(cls, path: str | Path, gpu: int = 0, ddevice: DEVICES = "cuda") -> Self:
    """Load a previously saved ``General_Registration`` from a pickle file.

    Args:
        path: Path to the pickle file written by :meth:`save`.
        gpu: GPU index to map the transform to.
        ddevice: Device type (e.g. ``"cuda"`` or ``"cpu"``).

    Returns:
        Reconstructed ``General_Registration`` instance.
    """
    with open(path, "rb") as w:
        return cls.load_(pickle.load(w), gpu, ddevice)

```

--------------------------------

### Shift POI Start Point Laterally

Source: https://tptbox.readthedocs.io/en/latest/api/poi_fun

Use this function to estimate vertebra width and displace a POI start point along a specified direction. It handles sacrum vertebrae and different landmark POIs for width estimation. Ensure the POI object contains pre-computed anatomical landmarks.

```python
def shift_point(
    poi: POI,
    vert_id: int,
    bb: tuple[slice, slice, slice] | None,
    start_point: Location = Location.Vertebra_Corpus,
    direction: DIRECTIONS | None = "R",
    log: Logger_Interface = _log,
) -> np.ndarray | None:
    """Shift a POI start point laterally by a fraction of the vertebra width.

    Estimates the vertebra width from articular-process or costal-process POIs
    and returns a new coordinate displaced from ``start_point`` along
    ``direction`` by a scaled fraction of that width.  Sacrum vertebrae without
    arcus are skipped.

    Args:
        poi: ``POI`` object with pre-computed anatomical landmarks.
        vert_id: Vertebra identifier (integer label).
        bb: Bounding-box slices used to convert global POI coordinates to local
            coordinates within the cropped sub-volume.
        start_point: Location enum member or already-resolved numpy coordinate
            from which the shift originates.  Defaults to
            ``Location.Vertebra_Corpus``.
        direction: Anatomical direction letter (``"R"``, ``"L"``, etc.) for the
            shift, or ``None`` to return the raw local start point without
            shifting.  Defaults to ``"R"``.
        log: Logger used for warning and error messages.

    Returns:
        Shifted voxel coordinate as a 3-element numpy array, or ``None`` when
        required POIs are missing or the vertebra is excluded.
    """
    if vert_id in sacrum_w_o_arcus:
        return

    if direction is None:
        return to_local_np(start_point, bb, poi, vert_id, log)
    sup_articular_right = sup_articular_left = None
    if Vertebra_Instance.is_sacrum(vert_id):
        if (vert_id, Location.Costal_Process_Left) not in poi:
            return
        sup_articular_right = to_local_np(Location.Costal_Process_Right, bb, poi, vert_id, log)
        sup_articular_left = to_local_np(Location.Costal_Process_Left, bb, poi, vert_id, log)
        factor = 6.0
    if sup_articular_left is None or sup_articular_right is None:
        sup_articular_right = to_local_np(Location.Superior_Articular_Right, bb, poi, vert_id, log, verbose=False)
        sup_articular_left = to_local_np(Location.Superior_Articular_Left, bb, poi, vert_id, log, verbose=False)
        factor = 3.0
    if sup_articular_left is None or sup_articular_right is None:
        sup_articular_right = to_local_np(Location.Inferior_Articular_Right, bb, poi, vert_id, log)
        sup_articular_left = to_local_np(Location.Inferior_Articular_Left, bb, poi, vert_id, log)
        factor = 2.0
    if sup_articular_left is None or sup_articular_right is None:
        return
    if vert_id <= 11:
        factor *= (12 - vert_id) / 11 + 1
    vertebra_width = np.linalg.norm(sup_articular_right - sup_articular_left)
    shift = vertebra_width / factor
    normal_vector = get_direction(direction, poi, vert_id)  # / np.array(poi.zoom)
    normal_vector = normal_vector / norm(normal_vector)
```

--------------------------------

### __init__

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Initializes a Searchquery object to filter for specific files or sequences within a BIDS dataset.

```APIDOC
## __init__ 

### Description
Initializes a Searchquery object to filter for specific files or sequences within a BIDS dataset.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **subj** (`Subject_Container`) - Required - The Subject class in with filter and action is applied
- **flatten** (`bool`) - Optional - If true, you are filtering for single files. If False you looking for sequences. Defaults to False.
```

--------------------------------

### dtype property

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Gets or sets the NumPy dtype of the voxel data array.

```APIDOC
## dtype property

### Description
NumPy dtype of the voxel data array.

### Returns
- **dtype** (type) - The NumPy dtype of the voxel data array.
```

--------------------------------

### Get BIDS_FILE Instances by Item

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Retrieves a list of BIDS_FILE instances for the first matching key found. It can accept a single key or an ordered list of keys to search.

```python
def get(self, item: str | list[str], default: list[BIDS_FILE] | None = None) -> list[BIDS_FILE] | None:
        """Return the list of :class:`BIDS_FILE` instances for the first matching key.

        When *item* is a list the method tries each element in order and
        returns the first hit.

        Args:
            item: A single format key or an ordered list of candidate keys.
            default: Value returned when none of the keys are found.

        Returns:
            The list of :class:`BIDS_FILE` instances, or *default*.
        """
        if not isinstance(item, list):
            item = [item]
        for i in item:
            if i in self:
                return self[i]
        return default
```

--------------------------------

### Get Length of BIDS_Global_info

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Returns the number of subjects managed by the BIDS_Global_info instance.

```python
def __len__(self):
        return len(self.subjects)
```

--------------------------------

### BIDS File Initialization

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Initializes a multi-file BIDS record, holding references to various file extensions like .nii.gz and .json. It parses the file name to determine format, info, and BIDS key, and associates related files.

```python
__init__(file: Path | str, dataset: Path | str, verbose=True, bids_ds: BIDS_Global_info | None = None, file_name_manipulation: typing.Callable[[str], str] | None = None)

    Multi-file BIDS record sharing the same identifier (all extensions of one file stem).

    Holds references to `.nii.gz`, `.json`, etc. simultaneously.

    The following fields are imported and can be accessed.
    self.format (str): The last value determining its use/modalities like T1w, msk, dixon
    self.info (dict[str,str]): key,values of the bids file. Can be changed, but will be only reflected in get_changed_path/find_changed_path if the from_info is set True.
                                Oder of insert matter (requires python >3.7). get/set/loop are for this dict
    self.BIDS_key(str): Hashing key.
    self.file (dict[str,Path]): keys are file extensions and values are paths to those files with given extension
                                The first file is added by this init, second by add_file-function. This is usually done by the tree generation of BIDS_Global_info
                                Self generated BIDS_FILE will not automatically have the json/nii.gz pair, except when their are in the same folder.
    self.dataset (Path): root-dataset name. All should paths will start from here.

    Args:
        file (Path): Path to the file in BIDS format.
        dataset (Path): Top Folder of the dataset
        verbose (bool, optional): You will be informed of non-conform Bids names/keys. Defaults to True.
    
```

```python
def __init__(
    self,
    file: Path | str,
    dataset: Path | str,
    verbose=True,
    bids_ds: BIDS_Global_info | None = None,
    file_name_manipulation: typing.Callable[[str], str] | None = None,
):
    """Multi-file BIDS record sharing the same identifier (all extensions of one file stem).

    Holds references to `.nii.gz`, `.json`, etc. simultaneously.

    The following fields are imported and can be accessed.
    self.format (str): The last value determining its use/modalities like T1w, msk, dixon
    self.info (dict[str,str]): key,values of the bids file. Can be changed, but will be only reflected in get_changed_path/find_changed_path if the from_info is set True.
                                Oder of insert matter (requires python >3.7). get/set/loop are for this dict
    self.BIDS_key(str): Hashing key.
    self.file (dict[str,Path]): keys are file extensions and values are paths to those files with given extension
                                The first file is added by this init, second by add_file-function. This is usually done by the tree generation of BIDS_Global_info
                                Self generated BIDS_FILE will not automatically have the json/nii.gz pair, except when their are in the same folder.
    self.dataset (Path): root-dataset name. All should paths will start from here.

    Args:
        file (Path): Path to the file in BIDS format.
        dataset (Path): Top Folder of the dataset
        verbose (bool, optional): You will be informed of non-conform Bids names/keys. Defaults to True.
    """
    file = Path(file) if not isinstance(file, Path) else file
    self.dataset = Path(dataset) if not isinstance(dataset, Path) else dataset
    self.verbose = verbose
    if file_name_manipulation is not None:
        if "WS_" in str(file):
            file.rename(file.parent / Path(file_name_manipulation(file.name)))
        name = file_name_manipulation(file.name)
    else:
        name = file.name
    self.format, self.info, self.BIDS_key, file_type = get_values_from_name(name, verbose)

    if bids_ds is not None:
        bids_ds.add_file_2_subject(bids=self, ds=self.dataset)
    self.file = {file_type: file}
    bids_key, _ = file.name.split(".", maxsplit=1)
    for file_type in ["nii.gz", "json", "png"]:
        if file_type in self.file:
            continue
        if os.path.exists(os.path.join(file.parent, bids_key + "." + file_type)):
            self.file[file_type] = Path(file.parent, bids_key + "." + file_type)
    self.file = dict(sorted(self.file.items()))

```

--------------------------------

### VERTEBRA property

Source: https://tptbox.readthedocs.io/en/latest/api/vert_constants

Gets the integer label of the vertebra. This is the same as the instance's value.

```APIDOC
## VERTEBRA property

### Description
Gets the integer label of the vertebra. This is the same as the instance's value.

### Type
int
```

--------------------------------

### add

Source: https://tptbox.readthedocs.io/en/latest/api/bids

Registers a BIDS file with a subject container. The file is placed into the correct sequence bucket, and a back-reference is set on the file.

```APIDOC
## add

### Description
Register a BIDS file with this subject container. Places the BIDS file into the correct sequence bucket (determined by `get_sequence_name`) and sets the back-reference on the file.

### Method
This is a method within a class, not a direct HTTP endpoint.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **bids** (`BIDS_FILE`) - Required - The BIDS file to add.

### Returns
- **None**

### Request Example
None provided.

### Response
#### Success Response
- **None**

#### Response Example
None provided.
```

--------------------------------

### NII.save_nrrd

Source: https://tptbox.readthedocs.io/en/latest/api/nii

Saves the NII object to an NRRD file. Requires the `pynrrd` package to be installed.

```APIDOC
## save_nrrd

### Description
Save an NII object to an NRRD file.

### Method
`save_nrrd(self: Self, file: str | Path | bids_files.BIDS_FILE, make_parents=True, verbose: logging=True, **args) -> None`

### Parameters
#### Path Parameters
- **file** (str | Path | bids_files.BIDS_FILE) - Required - The file path where the NRRD file will be saved.
- **make_parents** (bool) - Optional - If True, parent directories are created automatically. Defaults to True.
- **verbose** (logging) - Optional - If True (or a non-zero int), logs the save path and dtype. Defaults to True.
- **args** - Optional - Additional arguments to pass to the saving function.

### Raises
- ImportError: If the `pynrrd` package is not installed.
- ValueError: If the affine matrix is invalid or incompatible.
```
Tokens:
Raw