"""Image export helpers for rendered FieldView output.
The :mod:`fieldview.export` namespace provides thin wrappers around FieldView's
host-side image export commands. These functions are intended for automation
workflows that need to capture the current graphics view to PNG, JPG, BMP, or
other supported image formats.
Example:
.. code-block:: python
>>> import os
>>> import fieldview as fv
>>> data_dir = os.path.join(fv.home, "examples", "f18")
>>> ds = fv.data.load_plot3d(
... os.path.join(data_dir, "f18i9b_g_bin"),
... os.path.join(data_dir, "f18i9b_q_bin"),
... )
>>> fv.view.fit()
>>> request_id = fv.export_png("/tmp/f18.png")
"""
from __future__ import annotations
import os
from . import _core
from ._core_utils import _core_call
from .exceptions import InvalidArgumentError
from .utils import _coerce_pathlike_str
__all__: list[str] = ["export_image", "export_png", "export_jpg", "export_bmp"]
def _normalize_export_path(path: str | os.PathLike[str]) -> str:
normalized = _coerce_pathlike_str(path, "path")
if not normalized.strip():
raise InvalidArgumentError("path cannot be empty")
return normalized
[docs]
def export_image(
path: str | os.PathLike[str],
format: str = "png",
source: str = "graphics",
render_sync: bool = True,
) -> str:
"""Export an image through FieldView.
Args:
path: Output file path.
format: Image format name (e.g., "png", "jpg", "bmp").
source: Render source; defaults to "graphics".
render_sync: Whether to block until render completes.
Returns:
str: Request id from the dispatcher.
Example:
.. code-block:: python
>>> import os
>>> import fieldview as fv
>>> data_dir = os.path.join(fv.home, "examples", "f18")
>>> ds = fv.data.load_plot3d(
... os.path.join(data_dir, "f18i9b_g_bin"),
... os.path.join(data_dir, "f18i9b_q_bin"),
... )
>>> fv.view.fit()
>>> request_id = fv.export_image("/tmp/f18.jpg", format="jpg")
"""
path = _normalize_export_path(path)
return _core_call(
_core.do_print_command,
format=format,
filename=path,
source=source,
render_sync=render_sync,
)
[docs]
def export_png(
path: str | os.PathLike[str],
source: str = "graphics",
render_sync: bool = True,
) -> str:
"""Export a PNG image.
Args:
path: Output file path.
source: Render source; defaults to "graphics".
render_sync: Whether to block until render completes.
Returns:
str: Request id from the dispatcher.
Example:
.. code-block:: python
>>> import os
>>> import fieldview as fv
>>> data_dir = os.path.join(fv.home, "examples", "f18")
>>> ds = fv.data.load_plot3d(
... os.path.join(data_dir, "f18i9b_g_bin"),
... os.path.join(data_dir, "f18i9b_q_bin"),
... )
>>> fv.view.fit()
>>> request_id = fv.export_png("/tmp/f18.png")
"""
path = _normalize_export_path(path)
return _core_call(
_core.do_print_command, "png", path, source=source, render_sync=render_sync
)
[docs]
def export_jpg(
path: str | os.PathLike[str],
source: str = "graphics",
render_sync: bool = True,
) -> str:
"""Export a JPG image.
Args:
path: Output file path.
source: Render source; defaults to "graphics".
render_sync: Whether to block until render completes.
Returns:
str: Request id from the dispatcher.
Example:
.. code-block:: python
>>> import os
>>> import fieldview as fv
>>> data_dir = os.path.join(fv.home, "examples", "f18")
>>> ds = fv.data.load_plot3d(
... os.path.join(data_dir, "f18i9b_g_bin"),
... os.path.join(data_dir, "f18i9b_q_bin"),
... )
>>> fv.view.fit()
>>> request_id = fv.export_jpg("/tmp/f18.jpg")
"""
path = _normalize_export_path(path)
return _core_call(
_core.do_print_command, "jpg", path, source=source, render_sync=render_sync
)
[docs]
def export_bmp(
path: str | os.PathLike[str],
source: str = "graphics",
render_sync: bool = True,
) -> str:
"""Export a BMP image.
Args:
path: Output file path.
source: Render source; defaults to "graphics".
render_sync: Whether to block until render completes.
Returns:
str: Request id from the dispatcher.
Example:
.. code-block:: python
>>> import os
>>> import fieldview as fv
>>> data_dir = os.path.join(fv.home, "examples", "f18")
>>> ds = fv.data.load_plot3d(
... os.path.join(data_dir, "f18i9b_g_bin"),
... os.path.join(data_dir, "f18i9b_q_bin"),
... )
>>> fv.view.fit()
>>> request_id = fv.export_bmp("/tmp/f18.bmp")
"""
path = _normalize_export_path(path)
return _core_call(
_core.do_print_command, "bmp", path, source=source, render_sync=render_sync
)
