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

import typing
import pathlib
from styxdefs import *
import dataclasses

N3_BIAS_FIELD_CORRECTION_METADATA = Metadata(
    id="12e6ca015aa736902ad4369af67b842768a91549.boutiques",
    name="N3BiasFieldCorrection",
    package="ants",
    container_image_tag="antsx/ants:v2.5.3",
)


class N3BiasFieldCorrectionOutputs(typing.NamedTuple):
    """
    Output object returned when calling `n3_bias_field_correction(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    corrected_image: OutputPathType
    """The bias-corrected version of the input image."""
    bias_field: OutputPathType
    """The estimated bias field, if specified in the output."""


def n3_bias_field_correction(
    input_image: InputPathType,
    output: str,
    image_dimensionality: typing.Literal[2, 3, 4] | None = None,
    mask_image: InputPathType | None = None,
    rescale_intensities: typing.Literal[0, 1] | None = None,
    weight_image: InputPathType | None = None,
    shrink_factor: int | None = None,
    convergence: str | None = None,
    bspline_fitting: str | None = None,
    histogram_sharpening: str | None = None,
    verbose: typing.Literal[0, 1] | None = None,
    runner: Runner | None = None,
) -> N3BiasFieldCorrectionOutputs:
    """
    This N3 is a variant of the popular N3 (nonparametric nonuniform normalization)
    retrospective bias correction algorithm. Based on the assumption that the
    corruption of the low frequency bias field can be modeled as a convolution of
    the intensity histogram by a Gaussian, the basic algorithmic protocol is to
    iterate between deconvolving the intensity histogram by a Gaussian, remapping
    the intensities, and then spatially smoothing this result by a B-spline modeling
    of the bias field itself.
    
    Author: ANTs Developers
    
    URL: https://github.com/ANTsX/ANTs
    
    Args:
        input_image: A scalar image is expected as input for bias correction.\
            Since N3 log transforms the intensities, negative values or values\
            close to zero should be processed prior to correction.
        output: The bias-corrected version of the input image and optionally\
            the estimated bias field.
        image_dimensionality: This option forces the image to be treated as a\
            specified-dimensional image. If not specified, N3 tries to infer the\
            dimensionality from the input image.
        mask_image: If a mask image is specified, the final bias correction is\
            only performed in the mask region. If a mask image is not specified,\
            the entire image region will be used as the mask region. Note: this\
            differs from the original N3 implementation.
        rescale_intensities: This option rescales the intensity range within\
            the user-specified mask to the original [min, max] range.
        weight_image: The weight image allows the user to perform a relative\
            weighting of specific voxels during the B-spline fitting.
        shrink_factor: Shrink factor to resample the input image. Commonly used\
            values are <= 4.
        convergence: Describes the convergence criteria with default value as\
            [50,0.0].
        bspline_fitting: Describes the parameters for B-Spline fitting.\
            Defaults are [splineDistance,4,3].
        histogram_sharpening: Describes histogram sharpening parameters;\
            defaults are [0.15,0.01,200].
        verbose: Verbose output.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `N3BiasFieldCorrectionOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(N3_BIAS_FIELD_CORRECTION_METADATA)
    cargs = []
    cargs.append("N3BiasFieldCorrection")
    if image_dimensionality is not None:
        cargs.extend([
            "--image-dimensionality",
            str(image_dimensionality)
        ])
    cargs.extend([
        "--input-image",
        execution.input_file(input_image)
    ])
    if mask_image is not None:
        cargs.extend([
            "--mask-image",
            execution.input_file(mask_image)
        ])
    if rescale_intensities is not None:
        cargs.extend([
            "--rescale-intensities",
            str(rescale_intensities)
        ])
    if weight_image is not None:
        cargs.extend([
            "--weight-image",
            execution.input_file(weight_image)
        ])
    if shrink_factor is not None:
        cargs.extend([
            "--shrink-factor",
            str(shrink_factor)
        ])
    if convergence is not None:
        cargs.extend([
            "--convergence",
            convergence
        ])
    if bspline_fitting is not None:
        cargs.extend([
            "--bspline-fitting",
            bspline_fitting
        ])
    if histogram_sharpening is not None:
        cargs.extend([
            "--histogram-sharpening",
            histogram_sharpening
        ])
    cargs.extend([
        "--output",
        output
    ])
    if verbose is not None:
        cargs.extend([
            "--verbose",
            str(verbose)
        ])
    ret = N3BiasFieldCorrectionOutputs(
        root=execution.output_file("."),
        corrected_image=execution.output_file(output),
        bias_field=execution.output_file("[BIS_FIELD]"),
    )
    execution.run(cargs)
    return ret


__all__ = [
    "N3BiasFieldCorrectionOutputs",
    "N3_BIAS_FIELD_CORRECTION_METADATA",
    "n3_bias_field_correction",
]
