# This file was auto generated by Styx.
# Do not edit this file directly.

import typing
import pathlib
from styxdefs import *
import dataclasses

V_3DMASKDUMP_METADATA = Metadata(
    id="9cb4c849a9357c37ec67fbe234f23f59f3a3a158.boutiques",
    name="3dmaskdump",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


class V3dmaskdumpOutputs(typing.NamedTuple):
    """
    Output object returned when calling `v_3dmaskdump(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    output_file: OutputPathType | None
    """Output ASCII file with voxel values"""


def v_3dmaskdump(
    input_files: list[InputPathType],
    mask_dataset: InputPathType | None = None,
    mask_range: list[str] | None = None,
    output_index: bool = False,
    output_noijk: bool = False,
    output_xyz: bool = False,
    output_filename: str | None = None,
    calc_mask_opts: str | None = None,
    xbox_coords: str | None = None,
    dbox_coords: str | None = None,
    nbox_coords: str | None = None,
    ibox_coords: str | None = None,
    xball_coords: str | None = None,
    dball_coords: str | None = None,
    nball_coords: str | None = None,
    nozero_output: bool = False,
    random_voxels: float | None = None,
    random_seed: float | None = None,
    output_niml: str | None = None,
    quiet_mode: bool = False,
    runner: Runner | None = None,
) -> V3dmaskdumpOutputs:
    """
    Outputs voxel values from AFNI datasets satisfying mask criteria to an ASCII
    file.
    
    Author: AFNI Developers
    
    URL: https://afni.nimh.nih.gov/
    
    Args:
        input_files: Input datasets to dump voxel values.
        mask_dataset: Use the dataset as a mask. Only voxels with nonzero\
            values in the mask will be printed from the input dataset.
        mask_range: Further restrict the voxels from mask dataset to those mask\
            values between 'a' and 'b' (inclusive).
        output_index: Write out the dataset index values.
        output_noijk: Do not write out the i,j,k values.
        output_xyz: Write the x,y,z coordinates from the first input dataset at\
            the start of each output line.
        output_filename: Write output to specified file.
        calc_mask_opts: Execute options enclosed as a 3dcalc-like program to\
            produce a mask from the resulting 3D brick.
        xbox_coords: Put a 'mask' at dataset coordinates 'x y z' mm.
        dbox_coords: Put a 'mask' at RAI/DICOM coordinates of 'x y z' mm.
        nbox_coords: Put a 'mask' at LPI/SPM coordinates of 'x y z' mm.
        ibox_coords: Put a 'mask' at voxel indexes 'i j k'.
        xball_coords: Put a ball (sphere) mask at dataset coordinates (x,y,z)\
            with radius r.
        dball_coords: Put a ball (sphere) mask at RAI/DICOM coordinates (x,y,z)\
            with radius r.
        nball_coords: Put a ball (sphere) mask at LPI/SPM coordinates (x,y,z)\
            with radius r.
        nozero_output: Skip output of any voxel where all the data values are\
            zero.
        random_voxels: Keep only N_RAND randomly selected voxels from what\
            would have been the output.
        random_seed: Seed the random number generator with SEED.
        output_niml: Output data in the XML/NIML format compatible with input\
            back to AFNI via the READ_NIML_FILE command.
        quiet_mode: Do not print progress messages to stderr.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V3dmaskdumpOutputs`).
    """
    if mask_range is not None and (len(mask_range) != 2): 
        raise ValueError(f"Length of 'mask_range' must be 2 but was {len(mask_range)}")
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_3DMASKDUMP_METADATA)
    cargs = []
    cargs.append("3dmaskdump")
    cargs.extend([execution.input_file(f) for f in input_files])
    if mask_dataset is not None:
        cargs.extend([
            "-mask",
            execution.input_file(mask_dataset)
        ])
    if mask_range is not None:
        cargs.extend([
            "-mrange",
            *mask_range
        ])
    if output_index:
        cargs.append("-index")
    if output_noijk:
        cargs.append("-noijk")
    if output_xyz:
        cargs.append("-xyz")
    if output_filename is not None:
        cargs.extend([
            "-o",
            output_filename
        ])
    if calc_mask_opts is not None:
        cargs.extend([
            "-cmask",
            calc_mask_opts
        ])
    if xbox_coords is not None:
        cargs.extend([
            "-xbox",
            xbox_coords
        ])
    if dbox_coords is not None:
        cargs.extend([
            "-dbox",
            dbox_coords
        ])
    if nbox_coords is not None:
        cargs.extend([
            "-nbox",
            nbox_coords
        ])
    if ibox_coords is not None:
        cargs.extend([
            "-ibox",
            ibox_coords
        ])
    if xball_coords is not None:
        cargs.extend([
            "-xball",
            xball_coords
        ])
    if dball_coords is not None:
        cargs.extend([
            "-dball",
            dball_coords
        ])
    if nball_coords is not None:
        cargs.extend([
            "-nball",
            nball_coords
        ])
    if nozero_output:
        cargs.append("-nozero")
    if random_voxels is not None:
        cargs.extend([
            "-n_rand",
            str(random_voxels)
        ])
    if random_seed is not None:
        cargs.extend([
            "-n_randseed",
            str(random_seed)
        ])
    if output_niml is not None:
        cargs.extend([
            "-niml",
            output_niml
        ])
    if quiet_mode:
        cargs.append("-quiet")
    ret = V3dmaskdumpOutputs(
        root=execution.output_file("."),
        output_file=execution.output_file(output_filename) if (output_filename is not None) else None,
    )
    execution.run(cargs)
    return ret


__all__ = [
    "V3dmaskdumpOutputs",
    "V_3DMASKDUMP_METADATA",
    "v_3dmaskdump",
]
