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

import typing
import pathlib
from styxdefs import *
import dataclasses

VOLUME_GRADIENT_METADATA = Metadata(
    id="8af5e6bf60b53a0f383725072c1fa1ba36511752.boutiques",
    name="volume-gradient",
    package="workbench",
    container_image_tag="brainlife/connectome_workbench:1.5.0-freesurfer-update",
)


@dataclasses.dataclass
class VolumeGradientPresmooth:
    """
    smooth the volume before computing the gradient.
    """
    kernel: float
    """the size of the gaussian smoothing kernel in mm, as sigma by default"""
    opt_fwhm: bool = False
    """kernel size is FWHM, not sigma"""
    
    def run(
        self,
        execution: Execution,
    ) -> list[str]:
        """
        Build command line arguments. This method is called by the main command.
        
        Args:
            execution: The execution object.
        Returns:
            Command line arguments
        """
        cargs = []
        cargs.append("-presmooth")
        cargs.append(str(self.kernel))
        if self.opt_fwhm:
            cargs.append("-fwhm")
        return cargs


class VolumeGradientOutputs(typing.NamedTuple):
    """
    Output object returned when calling `volume_gradient(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    volume_out: OutputPathType
    """the output gradient magnitude volume"""
    opt_vectors_vector_volume_out: OutputPathType | None
    """output vectors: the vectors as a volume file"""


def volume_gradient(
    volume_in: InputPathType,
    volume_out: str,
    presmooth: VolumeGradientPresmooth | None = None,
    opt_roi_roi_volume: InputPathType | None = None,
    opt_vectors_vector_volume_out: str | None = None,
    opt_subvolume_subvol: str | None = None,
    runner: Runner | None = None,
) -> VolumeGradientOutputs:
    """
    Gradient of a volume file.
    
    Computes the gradient of the volume by doing linear regressions for each
    voxel, considering only its face neighbors unless too few face neighbors
    exist. The gradient vector is constructed from the partial derivatives of
    the resulting linear function, and the magnitude of this vector is the
    output. If specified, the volume vector output is arranged with the x, y,
    and z components from a subvolume as consecutive subvolumes.
    
    Author: Connectome Workbench Developers
    
    URL: https://github.com/Washington-University/workbench
    
    Args:
        volume_in: the input volume.
        volume_out: the output gradient magnitude volume.
        presmooth: smooth the volume before computing the gradient.
        opt_roi_roi_volume: select a region of interest to take the gradient\
            of: the region to take the gradient within.
        opt_vectors_vector_volume_out: output vectors: the vectors as a volume\
            file.
        opt_subvolume_subvol: select a single subvolume to take the gradient\
            of: the subvolume number or name.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `VolumeGradientOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(VOLUME_GRADIENT_METADATA)
    cargs = []
    cargs.append("wb_command")
    cargs.append("-volume-gradient")
    cargs.append(execution.input_file(volume_in))
    cargs.append(volume_out)
    if presmooth is not None:
        cargs.extend(presmooth.run(execution))
    if opt_roi_roi_volume is not None:
        cargs.extend([
            "-roi",
            execution.input_file(opt_roi_roi_volume)
        ])
    if opt_vectors_vector_volume_out is not None:
        cargs.extend([
            "-vectors",
            opt_vectors_vector_volume_out
        ])
    if opt_subvolume_subvol is not None:
        cargs.extend([
            "-subvolume",
            opt_subvolume_subvol
        ])
    ret = VolumeGradientOutputs(
        root=execution.output_file("."),
        volume_out=execution.output_file(volume_out),
        opt_vectors_vector_volume_out=execution.output_file(opt_vectors_vector_volume_out) if (opt_vectors_vector_volume_out is not None) else None,
    )
    execution.run(cargs)
    return ret


__all__ = [
    "VOLUME_GRADIENT_METADATA",
    "VolumeGradientOutputs",
    "VolumeGradientPresmooth",
    "volume_gradient",
]
