# 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="1af6dba5a41109de0e8ac9966c8bb6bae92d9c35.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
    """Output ASCII file with voxel values"""


def v_3dmaskdump(
    input_files: list[InputPathType],
    calc_mask_opts: str | None = None,
    output_filename: str | None = None,
    nball_coords: 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 Team
    
    URL: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dmaskdump.html
    
    Args:
        input_files: Input datasets to dump voxel values.
        calc_mask_opts: Execute options enclosed as a 3dcalc-like program to\
            produce a mask from the resulting 3D brick.
        output_filename: Write output to specified file.
        nball_coords: Put a ball (sphere) mask at LPI/SPM coordinates (x,y,z)\
            with radius r.
        quiet_mode: Do not print progress messages to stderr.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V3dmaskdumpOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_3DMASKDUMP_METADATA)
    cargs = []
    cargs.append("3dmaskdump")
    if calc_mask_opts is not None:
        cargs.extend([
            "-cmask",
            calc_mask_opts
        ])
    if output_filename is not None:
        cargs.extend([
            "-o",
            output_filename
        ])
    if nball_coords is not None:
        cargs.extend([
            "-nball",
            nball_coords
        ])
    if quiet_mode:
        cargs.append("-quiet")
    cargs.extend([execution.input_file(f) for f in input_files])
    ret = V3dmaskdumpOutputs(
        root=execution.output_file("."),
        output_file=execution.output_file("[OUTPUT_FILENAME]"),
    )
    execution.run(cargs)
    return ret


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