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

import typing
import pathlib
from styxdefs import *

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


VolumeGradientPresmoothParameters = typing.TypedDict('VolumeGradientPresmoothParameters', {
    "@type": typing.NotRequired[typing.Literal["presmooth"]],
    "kernel": float,
    "opt_fwhm": bool,
})
VolumeGradientPresmoothParametersTagged = typing.TypedDict('VolumeGradientPresmoothParametersTagged', {
    "@type": typing.Literal["presmooth"],
    "kernel": float,
    "opt_fwhm": bool,
})


VolumeGradientParameters = typing.TypedDict('VolumeGradientParameters', {
    "@type": typing.NotRequired[typing.Literal["workbench/volume-gradient"]],
    "volume_in": InputPathType,
    "volume_out": str,
    "presmooth": typing.NotRequired[VolumeGradientPresmoothParameters | None],
    "opt_roi_roi_volume": typing.NotRequired[InputPathType | None],
    "opt_vectors_vector_volume_out": typing.NotRequired[str | None],
    "opt_subvolume_subvol": typing.NotRequired[str | None],
})
VolumeGradientParametersTagged = typing.TypedDict('VolumeGradientParametersTagged', {
    "@type": typing.Literal["workbench/volume-gradient"],
    "volume_in": InputPathType,
    "volume_out": str,
    "presmooth": typing.NotRequired[VolumeGradientPresmoothParameters | None],
    "opt_roi_roi_volume": typing.NotRequired[InputPathType | None],
    "opt_vectors_vector_volume_out": typing.NotRequired[str | None],
    "opt_subvolume_subvol": typing.NotRequired[str | None],
})


def volume_gradient_presmooth_params(
    kernel: float,
    opt_fwhm: bool = False,
) -> VolumeGradientPresmoothParametersTagged:
    """
    Build parameters.
    
    Args:
        kernel: the size of the gaussian smoothing kernel in mm, as sigma by\
            default.
        opt_fwhm: kernel size is FWHM, not sigma.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "presmooth",
        "kernel": kernel,
        "opt_fwhm": opt_fwhm,
    }
    return params


def volume_gradient_presmooth_cargs(
    params: VolumeGradientPresmoothParameters,
    execution: Execution,
) -> list[str]:
    """
    Build command-line arguments from parameters.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Command-line arguments.
    """
    cargs = []
    cargs.append("-presmooth")
    cargs.append(str(params.get("kernel", None)))
    if params.get("opt_fwhm", False):
        cargs.append("-fwhm")
    return cargs


class VolumeGradientOutputs(typing.NamedTuple):
    """
    Output object returned when calling `VolumeGradientParameters(...)`.
    """
    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_params(
    volume_in: InputPathType,
    volume_out: str,
    presmooth: VolumeGradientPresmoothParameters | None = None,
    opt_roi_roi_volume: InputPathType | None = None,
    opt_vectors_vector_volume_out: str | None = None,
    opt_subvolume_subvol: str | None = None,
) -> VolumeGradientParametersTagged:
    """
    Build parameters.
    
    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.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "workbench/volume-gradient",
        "volume_in": volume_in,
        "volume_out": volume_out,
    }
    if presmooth is not None:
        params["presmooth"] = presmooth
    if opt_roi_roi_volume is not None:
        params["opt_roi_roi_volume"] = opt_roi_roi_volume
    if opt_vectors_vector_volume_out is not None:
        params["opt_vectors_vector_volume_out"] = opt_vectors_vector_volume_out
    if opt_subvolume_subvol is not None:
        params["opt_subvolume_subvol"] = opt_subvolume_subvol
    return params


def volume_gradient_cargs(
    params: VolumeGradientParameters,
    execution: Execution,
) -> list[str]:
    """
    Build command-line arguments from parameters.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Command-line arguments.
    """
    cargs = []
    cargs.append("wb_command")
    cargs.append("-volume-gradient")
    cargs.append(execution.input_file(params.get("volume_in", None)))
    cargs.append(params.get("volume_out", None))
    if params.get("presmooth", None) is not None:
        cargs.extend(volume_gradient_presmooth_cargs(params.get("presmooth", None), execution))
    if params.get("opt_roi_roi_volume", None) is not None:
        cargs.extend([
            "-roi",
            execution.input_file(params.get("opt_roi_roi_volume", None))
        ])
    if params.get("opt_vectors_vector_volume_out", None) is not None:
        cargs.extend([
            "-vectors",
            params.get("opt_vectors_vector_volume_out", None)
        ])
    if params.get("opt_subvolume_subvol", None) is not None:
        cargs.extend([
            "-subvolume",
            params.get("opt_subvolume_subvol", None)
        ])
    return cargs


def volume_gradient_outputs(
    params: VolumeGradientParameters,
    execution: Execution,
) -> VolumeGradientOutputs:
    """
    Build outputs object containing output file paths and possibly stdout/stderr.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Outputs object.
    """
    ret = VolumeGradientOutputs(
        root=execution.output_file("."),
        volume_out=execution.output_file(params.get("volume_out", None)),
        opt_vectors_vector_volume_out=execution.output_file(params.get("opt_vectors_vector_volume_out", None)) if (params.get("opt_vectors_vector_volume_out") is not None) else None,
    )
    return ret


def volume_gradient_execute(
    params: VolumeGradientParameters,
    runner: Runner | None = None,
) -> VolumeGradientOutputs:
    """
    volume-gradient
    
    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:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `VolumeGradientOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(VOLUME_GRADIENT_METADATA)
    params = execution.params(params)
    cargs = volume_gradient_cargs(params, execution)
    ret = volume_gradient_outputs(params, execution)
    execution.run(cargs)
    return ret


def volume_gradient(
    volume_in: InputPathType,
    volume_out: str,
    presmooth: VolumeGradientPresmoothParameters | 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:
    """
    volume-gradient
    
    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`).
    """
    params = volume_gradient_params(
        volume_in=volume_in,
        volume_out=volume_out,
        presmooth=presmooth,
        opt_roi_roi_volume=opt_roi_roi_volume,
        opt_vectors_vector_volume_out=opt_vectors_vector_volume_out,
        opt_subvolume_subvol=opt_subvolume_subvol,
    )
    return volume_gradient_execute(params, runner)


__all__ = [
    "VOLUME_GRADIENT_METADATA",
    "VolumeGradientOutputs",
    "volume_gradient",
    "volume_gradient_execute",
    "volume_gradient_params",
    "volume_gradient_presmooth_params",
]
