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

import typing
import pathlib
from styxdefs import *

SCENE_CAPTURE_IMAGE_METADATA = Metadata(
    id="d7f78e620a92e4692790ceda0d24ff04fb837ed8.workbench",
    name="scene-capture-image",
    package="workbench",
    container_image_tag="nx10x/workbench:2.1.0",
)


_SceneCaptureImageSizeWidthHeightParamsDictNoTag = typing.TypedDict('_SceneCaptureImageSizeWidthHeightParamsDictNoTag', {
    "width": float,
    "height": float,
})
SceneCaptureImageSizeWidthHeightParamsDictTagged = typing.TypedDict('SceneCaptureImageSizeWidthHeightParamsDictTagged', {
    "@type": typing.Literal["size-width-height"],
    "width": float,
    "height": float,
})
SceneCaptureImageSizeWidthHeightParamsDict = _SceneCaptureImageSizeWidthHeightParamsDictNoTag | SceneCaptureImageSizeWidthHeightParamsDictTagged


_SceneCaptureImageResolutionParamsDictNoTag = typing.TypedDict('_SceneCaptureImageResolutionParamsDictNoTag', {
    "Number of pixels": float,
    "Units Name": str,
})
SceneCaptureImageResolutionParamsDictTagged = typing.TypedDict('SceneCaptureImageResolutionParamsDictTagged', {
    "@type": typing.Literal["resolution"],
    "Number of pixels": float,
    "Units Name": str,
})
SceneCaptureImageResolutionParamsDict = _SceneCaptureImageResolutionParamsDictNoTag | SceneCaptureImageResolutionParamsDictTagged


_SceneCaptureImageSetMapYokeParamsDictNoTag = typing.TypedDict('_SceneCaptureImageSetMapYokeParamsDictNoTag', {
    "map yoking roman numeral": str,
    "map undex": int,
})
SceneCaptureImageSetMapYokeParamsDictTagged = typing.TypedDict('SceneCaptureImageSetMapYokeParamsDictTagged', {
    "@type": typing.Literal["set-map-yoke"],
    "map yoking roman numeral": str,
    "map undex": int,
})
SceneCaptureImageSetMapYokeParamsDict = _SceneCaptureImageSetMapYokeParamsDictNoTag | SceneCaptureImageSetMapYokeParamsDictTagged


_SceneCaptureImageConnDbLoginParamsDictNoTag = typing.TypedDict('_SceneCaptureImageConnDbLoginParamsDictNoTag', {
    "username": str,
    "password": str,
})
SceneCaptureImageConnDbLoginParamsDictTagged = typing.TypedDict('SceneCaptureImageConnDbLoginParamsDictTagged', {
    "@type": typing.Literal["conn-db-login"],
    "username": str,
    "password": str,
})
SceneCaptureImageConnDbLoginParamsDict = _SceneCaptureImageConnDbLoginParamsDictNoTag | SceneCaptureImageConnDbLoginParamsDictTagged


_SceneCaptureImageParamsDictNoTag = typing.TypedDict('_SceneCaptureImageParamsDictNoTag', {
    "scene-file": str,
    "scene-name-or-number": str,
    "image-file-name": str,
    "size-width-height": typing.NotRequired[SceneCaptureImageSizeWidthHeightParamsDict | None],
    "resolution": typing.NotRequired[SceneCaptureImageResolutionParamsDict | None],
    "set-map-yoke": typing.NotRequired[SceneCaptureImageSetMapYokeParamsDict | None],
    "conn-db-login": typing.NotRequired[SceneCaptureImageConnDbLoginParamsDict | None],
    "Renderer": typing.NotRequired[str | None],
    "size": typing.NotRequired[int | None],
    "units": typing.NotRequired[str | None],
    "height": typing.NotRequired[float | None],
    "width": typing.NotRequired[float | None],
    "print-image-info": bool,
    "show-capture-settings": bool,
    "no-scene-colors": bool,
    "size-capture": bool,
    "size-window": bool,
})
SceneCaptureImageParamsDictTagged = typing.TypedDict('SceneCaptureImageParamsDictTagged', {
    "@type": typing.Literal["workbench/scene-capture-image"],
    "scene-file": str,
    "scene-name-or-number": str,
    "image-file-name": str,
    "size-width-height": typing.NotRequired[SceneCaptureImageSizeWidthHeightParamsDict | None],
    "resolution": typing.NotRequired[SceneCaptureImageResolutionParamsDict | None],
    "set-map-yoke": typing.NotRequired[SceneCaptureImageSetMapYokeParamsDict | None],
    "conn-db-login": typing.NotRequired[SceneCaptureImageConnDbLoginParamsDict | None],
    "Renderer": typing.NotRequired[str | None],
    "size": typing.NotRequired[int | None],
    "units": typing.NotRequired[str | None],
    "height": typing.NotRequired[float | None],
    "width": typing.NotRequired[float | None],
    "print-image-info": bool,
    "show-capture-settings": bool,
    "no-scene-colors": bool,
    "size-capture": bool,
    "size-window": bool,
})
SceneCaptureImageParamsDict = _SceneCaptureImageParamsDictNoTag | SceneCaptureImageParamsDictTagged


def scene_capture_image_size_width_height(
    width: float,
    height: float,
) -> SceneCaptureImageSizeWidthHeightParamsDictTagged:
    """
    Build parameters.
    
    Args:
        width: Width for output image.
        height: Height for output image.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "size-width-height",
        "width": width,
        "height": height,
    }
    return params


def scene_capture_image_size_width_height_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `SceneCaptureImageSizeWidthHeightParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("width", None) is None:
        raise StyxValidationError("`width` must not be None")
    if not isinstance(params["width"], (float, int)):
        raise StyxValidationError(f'`width` has the wrong type: Received `{type(params.get("width", None))}` expected `float`')
    if params.get("height", None) is None:
        raise StyxValidationError("`height` must not be None")
    if not isinstance(params["height"], (float, int)):
        raise StyxValidationError(f'`height` has the wrong type: Received `{type(params.get("height", None))}` expected `float`')


def scene_capture_image_size_width_height_cargs(
    params: SceneCaptureImageSizeWidthHeightParamsDict,
    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.extend([
        "-size-width-height",
        str(params.get("width", None)),
        str(params.get("height", None))
    ])
    return cargs


def scene_capture_image_resolution(
    number_of_pixels: float,
    units_name: str,
) -> SceneCaptureImageResolutionParamsDictTagged:
    """
    Build parameters.
    
    Args:
        number_of_pixels: number of pixels.
        units_name: Name of resolution units. Valid resolution unit names are:\
            PIXELS_PER_INCH\
            PIXELS_PER_CENTIMETER\
            PIXELS_PER_METER\
            PIXELS_PER_MILLIMETER.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "resolution",
        "Number of pixels": number_of_pixels,
        "Units Name": units_name,
    }
    return params


def scene_capture_image_resolution_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `SceneCaptureImageResolutionParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("Number of pixels", None) is None:
        raise StyxValidationError("`Number of pixels` must not be None")
    if not isinstance(params["Number of pixels"], (float, int)):
        raise StyxValidationError(f'`Number of pixels` has the wrong type: Received `{type(params.get("Number of pixels", None))}` expected `float`')
    if params.get("Units Name", None) is None:
        raise StyxValidationError("`Units Name` must not be None")
    if not isinstance(params["Units Name"], str):
        raise StyxValidationError(f'`Units Name` has the wrong type: Received `{type(params.get("Units Name", None))}` expected `str`')


def scene_capture_image_resolution_cargs(
    params: SceneCaptureImageResolutionParamsDict,
    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.extend([
        "-resolution",
        str(params.get("Number of pixels", None)),
        params.get("Units Name", None)
    ])
    return cargs


def scene_capture_image_set_map_yoke(
    map_yoking_roman_numeral: str,
    map_undex: int,
) -> SceneCaptureImageSetMapYokeParamsDictTagged:
    """
    Build parameters.
    
    Args:
        map_yoking_roman_numeral: Roman numeral identifying the map yoking\
            group (I, II, III, IV, V, VI, VII, VIII, IX, X).
        map_undex: Map index for yoking group. Indices start at 1 (one).
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "set-map-yoke",
        "map yoking roman numeral": map_yoking_roman_numeral,
        "map undex": map_undex,
    }
    return params


def scene_capture_image_set_map_yoke_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `SceneCaptureImageSetMapYokeParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("map yoking roman numeral", None) is None:
        raise StyxValidationError("`map yoking roman numeral` must not be None")
    if not isinstance(params["map yoking roman numeral"], str):
        raise StyxValidationError(f'`map yoking roman numeral` has the wrong type: Received `{type(params.get("map yoking roman numeral", None))}` expected `str`')
    if params.get("map undex", None) is None:
        raise StyxValidationError("`map undex` must not be None")
    if not isinstance(params["map undex"], int):
        raise StyxValidationError(f'`map undex` has the wrong type: Received `{type(params.get("map undex", None))}` expected `int`')


def scene_capture_image_set_map_yoke_cargs(
    params: SceneCaptureImageSetMapYokeParamsDict,
    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.extend([
        "-set-map-yoke",
        params.get("map yoking roman numeral", None),
        str(params.get("map undex", None))
    ])
    return cargs


def scene_capture_image_conn_db_login(
    username: str,
    password: str,
) -> SceneCaptureImageConnDbLoginParamsDictTagged:
    """
    Build parameters.
    
    Args:
        username: Connectome DB Username.
        password: Connectome DB Password.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "conn-db-login",
        "username": username,
        "password": password,
    }
    return params


def scene_capture_image_conn_db_login_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `SceneCaptureImageConnDbLoginParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("username", None) is None:
        raise StyxValidationError("`username` must not be None")
    if not isinstance(params["username"], str):
        raise StyxValidationError(f'`username` has the wrong type: Received `{type(params.get("username", None))}` expected `str`')
    if params.get("password", None) is None:
        raise StyxValidationError("`password` must not be None")
    if not isinstance(params["password"], str):
        raise StyxValidationError(f'`password` has the wrong type: Received `{type(params.get("password", None))}` expected `str`')


def scene_capture_image_conn_db_login_cargs(
    params: SceneCaptureImageConnDbLoginParamsDict,
    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.extend([
        "-conn-db-login",
        params.get("username", None),
        params.get("password", None)
    ])
    return cargs


class SceneCaptureImageOutputs(typing.NamedTuple):
    """
    Output object returned when calling `SceneCaptureImageParamsDict(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""


def scene_capture_image_params(
    scene_file: str,
    scene_name_or_number: str,
    image_file_name: str,
    size_width_height: SceneCaptureImageSizeWidthHeightParamsDict | None = None,
    resolution: SceneCaptureImageResolutionParamsDict | None = None,
    set_map_yoke: SceneCaptureImageSetMapYokeParamsDict | None = None,
    conn_db_login: SceneCaptureImageConnDbLoginParamsDict | None = None,
    renderer: str | None = None,
    size: int | None = None,
    units: str | None = None,
    height: float | None = None,
    width: float | None = None,
    print_image_info: bool = False,
    show_capture_settings: bool = False,
    no_scene_colors: bool = False,
    size_capture: bool = False,
    size_window: bool = False,
) -> SceneCaptureImageParamsDictTagged:
    """
    Build parameters.
    
    Args:
        scene_file: scene file.
        scene_name_or_number: name or number (starting at one) of the scene in\
            the scene file.
        image_file_name: output - image file name\
            The file name must end with a valid extension that identifies the\
            image file format. Valid extensions on this system are: (.bmp .jpeg\
            .jpg .png .ppm).\
            \
            If there is more than one window in the scene, multiple image files\
            are output with the window's number inserted into the name of the\
            image file immediately before the image file's extension.
        size_width_height: Width and height for output image.
        resolution: Image resolution (number pixels per size unit)\
            Default is 300 PIXELS_PER_INCH.
        set_map_yoke: Override selected map index for a map yoking group.
        conn_db_login: Login for scenes with files in Connectome Database. If\
            this option is not specified, the login and password stored in the\
            user's preferences is used.
        renderer: Select renderer for drawing image\
            \
            Name of renderer to use for drawing image\
            Available renderers are (first is default):\
            OSMesa - Mesa3D OSMesa software renderer.
        size: Add a margin to sides of the image using the window's background\
            color.\
            \
            size of margin, in pixels, added to all sides of output image.
        units: Units for image width/height\
            Default is PIXELS\
            \
            Name of units for image width/height. Valid units are:\
            INCHES\
            CENTIMETERS\
            MILLIMETERS\
            METERS\
            PIXELS.
        height: Height for output image. Width is computed using the aspect\
            ratio from the window's width and height saved in the scene.\
            \
            Height for output image.
        width: Width for output image. Height is computed using the aspect\
            ratio from the window's width and height saved in the scene.\
            \
            Width for output image.
        print_image_info: Print the size and other information about output\
            images only and DO NOT create any output images.
        show_capture_settings: Print settings from Capture Dialog only, DO NOT\
            create image file(s).
        no_scene_colors: Do not use background and foreground colors in scene.
        size_capture: Output image uses size from Capture Dialog when scene was\
            created.
        size_window: Output image is size of window's graphics region from when\
            scene was created.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "workbench/scene-capture-image",
        "scene-file": scene_file,
        "scene-name-or-number": scene_name_or_number,
        "image-file-name": image_file_name,
        "print-image-info": print_image_info,
        "show-capture-settings": show_capture_settings,
        "no-scene-colors": no_scene_colors,
        "size-capture": size_capture,
        "size-window": size_window,
    }
    if size_width_height is not None:
        params["size-width-height"] = size_width_height
    if resolution is not None:
        params["resolution"] = resolution
    if set_map_yoke is not None:
        params["set-map-yoke"] = set_map_yoke
    if conn_db_login is not None:
        params["conn-db-login"] = conn_db_login
    if renderer is not None:
        params["Renderer"] = renderer
    if size is not None:
        params["size"] = size
    if units is not None:
        params["units"] = units
    if height is not None:
        params["height"] = height
    if width is not None:
        params["width"] = width
    return params


def scene_capture_image_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `SceneCaptureImageParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("scene-file", None) is None:
        raise StyxValidationError("`scene-file` must not be None")
    if not isinstance(params["scene-file"], str):
        raise StyxValidationError(f'`scene-file` has the wrong type: Received `{type(params.get("scene-file", None))}` expected `str`')
    if params.get("scene-name-or-number", None) is None:
        raise StyxValidationError("`scene-name-or-number` must not be None")
    if not isinstance(params["scene-name-or-number"], str):
        raise StyxValidationError(f'`scene-name-or-number` has the wrong type: Received `{type(params.get("scene-name-or-number", None))}` expected `str`')
    if params.get("image-file-name", None) is None:
        raise StyxValidationError("`image-file-name` must not be None")
    if not isinstance(params["image-file-name"], str):
        raise StyxValidationError(f'`image-file-name` has the wrong type: Received `{type(params.get("image-file-name", None))}` expected `str`')
    if params.get("size-width-height", None) is not None:
        scene_capture_image_size_width_height_validate(params["size-width-height"])
    if params.get("resolution", None) is not None:
        scene_capture_image_resolution_validate(params["resolution"])
    if params.get("set-map-yoke", None) is not None:
        scene_capture_image_set_map_yoke_validate(params["set-map-yoke"])
    if params.get("conn-db-login", None) is not None:
        scene_capture_image_conn_db_login_validate(params["conn-db-login"])
    if params.get("Renderer", None) is not None:
        if not isinstance(params["Renderer"], str):
            raise StyxValidationError(f'`Renderer` has the wrong type: Received `{type(params.get("Renderer", None))}` expected `str | None`')
    if params.get("size", None) is not None:
        if not isinstance(params["size"], int):
            raise StyxValidationError(f'`size` has the wrong type: Received `{type(params.get("size", None))}` expected `int | None`')
    if params.get("units", None) is not None:
        if not isinstance(params["units"], str):
            raise StyxValidationError(f'`units` has the wrong type: Received `{type(params.get("units", None))}` expected `str | None`')
    if params.get("height", None) is not None:
        if not isinstance(params["height"], (float, int)):
            raise StyxValidationError(f'`height` has the wrong type: Received `{type(params.get("height", None))}` expected `float | None`')
    if params.get("width", None) is not None:
        if not isinstance(params["width"], (float, int)):
            raise StyxValidationError(f'`width` has the wrong type: Received `{type(params.get("width", None))}` expected `float | None`')
    if params.get("print-image-info", False) is None:
        raise StyxValidationError("`print-image-info` must not be None")
    if not isinstance(params["print-image-info"], bool):
        raise StyxValidationError(f'`print-image-info` has the wrong type: Received `{type(params.get("print-image-info", False))}` expected `bool`')
    if params.get("show-capture-settings", False) is None:
        raise StyxValidationError("`show-capture-settings` must not be None")
    if not isinstance(params["show-capture-settings"], bool):
        raise StyxValidationError(f'`show-capture-settings` has the wrong type: Received `{type(params.get("show-capture-settings", False))}` expected `bool`')
    if params.get("no-scene-colors", False) is None:
        raise StyxValidationError("`no-scene-colors` must not be None")
    if not isinstance(params["no-scene-colors"], bool):
        raise StyxValidationError(f'`no-scene-colors` has the wrong type: Received `{type(params.get("no-scene-colors", False))}` expected `bool`')
    if params.get("size-capture", False) is None:
        raise StyxValidationError("`size-capture` must not be None")
    if not isinstance(params["size-capture"], bool):
        raise StyxValidationError(f'`size-capture` has the wrong type: Received `{type(params.get("size-capture", False))}` expected `bool`')
    if params.get("size-window", False) is None:
        raise StyxValidationError("`size-window` must not be None")
    if not isinstance(params["size-window"], bool):
        raise StyxValidationError(f'`size-window` has the wrong type: Received `{type(params.get("size-window", False))}` expected `bool`')


def scene_capture_image_cargs(
    params: SceneCaptureImageParamsDict,
    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.extend([
        "wb_command",
        "-scene-capture-image"
    ])
    cargs.append(params.get("scene-file", None))
    cargs.append(params.get("scene-name-or-number", None))
    cargs.append(params.get("image-file-name", None))
    if params.get("size-width-height", None) is not None or params.get("resolution", None) is not None or params.get("set-map-yoke", None) is not None or params.get("conn-db-login", None) is not None:
        cargs.extend([
            *(scene_capture_image_size_width_height_cargs(params.get("size-width-height", None), execution) if (params.get("size-width-height", None) is not None) else []),
            *(scene_capture_image_resolution_cargs(params.get("resolution", None), execution) if (params.get("resolution", None) is not None) else []),
            *(scene_capture_image_set_map_yoke_cargs(params.get("set-map-yoke", None), execution) if (params.get("set-map-yoke", None) is not None) else []),
            *(scene_capture_image_conn_db_login_cargs(params.get("conn-db-login", None), execution) if (params.get("conn-db-login", None) is not None) else [])
        ])
    if params.get("Renderer", None) is not None:
        cargs.extend([
            "-renderer",
            params.get("Renderer", None)
        ])
    if params.get("size", None) is not None:
        cargs.extend([
            "-margin",
            str(params.get("size", None))
        ])
    if params.get("units", None) is not None:
        cargs.extend([
            "-units",
            params.get("units", None)
        ])
    if params.get("height", None) is not None:
        cargs.extend([
            "-size-height",
            str(params.get("height", None))
        ])
    if params.get("width", None) is not None:
        cargs.extend([
            "-size-width",
            str(params.get("width", None))
        ])
    if params.get("print-image-info", False):
        cargs.append("-print-image-info")
    if params.get("show-capture-settings", False):
        cargs.append("-show-capture-settings")
    if params.get("no-scene-colors", False):
        cargs.append("-no-scene-colors")
    if params.get("size-capture", False):
        cargs.append("-size-capture")
    if params.get("size-window", False):
        cargs.append("-size-window")
    return cargs


def scene_capture_image_outputs(
    params: SceneCaptureImageParamsDict,
    execution: Execution,
) -> SceneCaptureImageOutputs:
    """
    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 = SceneCaptureImageOutputs(
        root=execution.output_file("."),
    )
    return ret


def scene_capture_image_execute(
    params: SceneCaptureImageParamsDict,
    runner: Runner | None = None,
) -> SceneCaptureImageOutputs:
    """
    OFFSCREEN RENDERING OF SCENE TO AN IMAGE FILE.
    
    ----------------------------------------------------------------------
    
    Render content of browser windows displayed in a scene into image file(s).
    
    If none of the "-size" options are specified, the default is "-size-window"
    (Output image is size of the window that was saved in the scene).
    
    For the "-size" options that accept a width and/or height, the values
    default to number of pixels. To express the width and/or height in physical
    units (inches, centimeters, etc.), use the "-units" option. When physical
    units are used, the pixel width and height are derived using the physical
    width/height and the image resolution (see the "-resolution" option).
    
    Note that scenes created prior to version 1.2 (May 2016) do not contain
    information about the size of the window. Therefore, one must use the
    "-size-width-height" option.
    
    Examples:
    
    Generate an image of the second scene. Width and height of image is width
    and height of window saved in the scene.
    wb_command -scene-capture-image myscene.scene 2 image2.jpg
    
    Generate an image of the second scene with a margin around sides of the
    image. Width and height of image is width and height of window saved in the
    scene.
    wb_command -scene-capture-image myscene.scene 2 image2.jpg -margin 10
    
    Generate an image of the second scene that is 6 inches width with 300 pixels
    per inch. The resulting width is 1800 pixels. The resulting height of the
    image is a function of the width and the aspect ratio (height divided by
    width) of the window size saved in the scene.
    wb_command -scene-capture-image myscene.scene 2 image21.jpg \\
    -size-width 6 -units INCHES -resolution 300 PIXELS_PER_INCH
    
    Print information about the size of the output image for the second scene
    (no image file is created) using a width of 4.5 centimeters.
    wb_command -scene-capture-image myscene.scene 2 test.jpg \\
    -size-width 4.5 -units CENTIMETERS -print-image-info
    
    
    .
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `SceneCaptureImageOutputs`).
    """
    scene_capture_image_validate(params)
    runner = runner or get_global_runner()
    execution = runner.start_execution(SCENE_CAPTURE_IMAGE_METADATA)
    params = execution.params(params)
    cargs = scene_capture_image_cargs(params, execution)
    ret = scene_capture_image_outputs(params, execution)
    execution.run(cargs)
    return ret


def scene_capture_image(
    scene_file: str,
    scene_name_or_number: str,
    image_file_name: str,
    size_width_height: SceneCaptureImageSizeWidthHeightParamsDict | None = None,
    resolution: SceneCaptureImageResolutionParamsDict | None = None,
    set_map_yoke: SceneCaptureImageSetMapYokeParamsDict | None = None,
    conn_db_login: SceneCaptureImageConnDbLoginParamsDict | None = None,
    renderer: str | None = None,
    size: int | None = None,
    units: str | None = None,
    height: float | None = None,
    width: float | None = None,
    print_image_info: bool = False,
    show_capture_settings: bool = False,
    no_scene_colors: bool = False,
    size_capture: bool = False,
    size_window: bool = False,
    runner: Runner | None = None,
) -> SceneCaptureImageOutputs:
    """
    OFFSCREEN RENDERING OF SCENE TO AN IMAGE FILE.
    
    ----------------------------------------------------------------------
    
    Render content of browser windows displayed in a scene into image file(s).
    
    If none of the "-size" options are specified, the default is "-size-window"
    (Output image is size of the window that was saved in the scene).
    
    For the "-size" options that accept a width and/or height, the values
    default to number of pixels. To express the width and/or height in physical
    units (inches, centimeters, etc.), use the "-units" option. When physical
    units are used, the pixel width and height are derived using the physical
    width/height and the image resolution (see the "-resolution" option).
    
    Note that scenes created prior to version 1.2 (May 2016) do not contain
    information about the size of the window. Therefore, one must use the
    "-size-width-height" option.
    
    Examples:
    
    Generate an image of the second scene. Width and height of image is width
    and height of window saved in the scene.
    wb_command -scene-capture-image myscene.scene 2 image2.jpg
    
    Generate an image of the second scene with a margin around sides of the
    image. Width and height of image is width and height of window saved in the
    scene.
    wb_command -scene-capture-image myscene.scene 2 image2.jpg -margin 10
    
    Generate an image of the second scene that is 6 inches width with 300 pixels
    per inch. The resulting width is 1800 pixels. The resulting height of the
    image is a function of the width and the aspect ratio (height divided by
    width) of the window size saved in the scene.
    wb_command -scene-capture-image myscene.scene 2 image21.jpg \\
    -size-width 6 -units INCHES -resolution 300 PIXELS_PER_INCH
    
    Print information about the size of the output image for the second scene
    (no image file is created) using a width of 4.5 centimeters.
    wb_command -scene-capture-image myscene.scene 2 test.jpg \\
    -size-width 4.5 -units CENTIMETERS -print-image-info
    
    
    .
    
    Args:
        scene_file: scene file.
        scene_name_or_number: name or number (starting at one) of the scene in\
            the scene file.
        image_file_name: output - image file name\
            The file name must end with a valid extension that identifies the\
            image file format. Valid extensions on this system are: (.bmp .jpeg\
            .jpg .png .ppm).\
            \
            If there is more than one window in the scene, multiple image files\
            are output with the window's number inserted into the name of the\
            image file immediately before the image file's extension.
        size_width_height: Width and height for output image.
        resolution: Image resolution (number pixels per size unit)\
            Default is 300 PIXELS_PER_INCH.
        set_map_yoke: Override selected map index for a map yoking group.
        conn_db_login: Login for scenes with files in Connectome Database. If\
            this option is not specified, the login and password stored in the\
            user's preferences is used.
        renderer: Select renderer for drawing image\
            \
            Name of renderer to use for drawing image\
            Available renderers are (first is default):\
            OSMesa - Mesa3D OSMesa software renderer.
        size: Add a margin to sides of the image using the window's background\
            color.\
            \
            size of margin, in pixels, added to all sides of output image.
        units: Units for image width/height\
            Default is PIXELS\
            \
            Name of units for image width/height. Valid units are:\
            INCHES\
            CENTIMETERS\
            MILLIMETERS\
            METERS\
            PIXELS.
        height: Height for output image. Width is computed using the aspect\
            ratio from the window's width and height saved in the scene.\
            \
            Height for output image.
        width: Width for output image. Height is computed using the aspect\
            ratio from the window's width and height saved in the scene.\
            \
            Width for output image.
        print_image_info: Print the size and other information about output\
            images only and DO NOT create any output images.
        show_capture_settings: Print settings from Capture Dialog only, DO NOT\
            create image file(s).
        no_scene_colors: Do not use background and foreground colors in scene.
        size_capture: Output image uses size from Capture Dialog when scene was\
            created.
        size_window: Output image is size of window's graphics region from when\
            scene was created.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `SceneCaptureImageOutputs`).
    """
    params = scene_capture_image_params(
        scene_file=scene_file,
        scene_name_or_number=scene_name_or_number,
        image_file_name=image_file_name,
        size_width_height=size_width_height,
        resolution=resolution,
        set_map_yoke=set_map_yoke,
        conn_db_login=conn_db_login,
        renderer=renderer,
        size=size,
        units=units,
        height=height,
        width=width,
        print_image_info=print_image_info,
        show_capture_settings=show_capture_settings,
        no_scene_colors=no_scene_colors,
        size_capture=size_capture,
        size_window=size_window,
    )
    return scene_capture_image_execute(params, runner)


__all__ = [
    "SCENE_CAPTURE_IMAGE_METADATA",
    "SceneCaptureImageConnDbLoginParamsDict",
    "SceneCaptureImageConnDbLoginParamsDictTagged",
    "SceneCaptureImageOutputs",
    "SceneCaptureImageParamsDict",
    "SceneCaptureImageParamsDictTagged",
    "SceneCaptureImageResolutionParamsDict",
    "SceneCaptureImageResolutionParamsDictTagged",
    "SceneCaptureImageSetMapYokeParamsDict",
    "SceneCaptureImageSetMapYokeParamsDictTagged",
    "SceneCaptureImageSizeWidthHeightParamsDict",
    "SceneCaptureImageSizeWidthHeightParamsDictTagged",
    "scene_capture_image",
    "scene_capture_image_conn_db_login",
    "scene_capture_image_execute",
    "scene_capture_image_params",
    "scene_capture_image_resolution",
    "scene_capture_image_set_map_yoke",
    "scene_capture_image_size_width_height",
]
