"""Top-level Python entry point for FieldView automation.
The :mod:`fieldview` namespace exposes the main submodules used for in-process
automation, including dataset access, formula creation, visualization object
creation, layout and camera control, image export, shared constants, and
common utility value types.
Use this top-level namespace when you want the overall package entry point,
shared session helpers such as scene discovery, or convenient access to the
major submodules through names like :mod:`fieldview.data`,
:mod:`fieldview.formula`, and :mod:`fieldview.vis`.
"""
from __future__ import annotations
import importlib
from types import ModuleType
from typing import cast
from collections.abc import Callable
from . import _core as _core_module
from ._core import undo, redo
from ._core_utils import _core_call
from . import constant
from . import exceptions
from .exceptions import (
CoreError,
FieldViewError,
InvalidArgumentError,
InvalidDatasetError,
)
__version__ = "1.0.0"
__fieldview_compat__ = "2025.0.12"
_dist_version: Callable[[str], str] | None = None
# Keep a literal fallback for startup preflight parsing, but prefer installed
# package metadata when available (e.g., beta wheels).
try:
from importlib.metadata import version as _dist_version
except Exception:
pass
if _dist_version is not None:
try:
__version__ = _dist_version("fieldview")
except Exception:
pass
def _import_module(name: str) -> ModuleType:
return importlib.import_module(name, __name__)
def _import_attr(module_name: str, attr_name: str) -> object:
return cast(object, getattr(_import_module(module_name), attr_name))
export_image = cast(Callable[..., str], _import_attr(".export", "export_image"))
export_png = cast(Callable[..., str], _import_attr(".export", "export_png"))
export_jpg = cast(Callable[..., str], _import_attr(".export", "export_jpg"))
export_bmp = cast(Callable[..., str], _import_attr(".export", "export_bmp"))
data = _import_module(".data")
formula = _import_module(".formula")
vis = _import_module(".vis")
camera = _import_module(".camera")
layout = _import_module(".layout")
view = _import_module(".view")
_utils = _import_module(".utils")
ObjectLists = cast(type[object], _import_attr("._objects", "ObjectLists"))
get_current_object = cast(
Callable[..., object], _import_attr("._objects", "get_current_object")
)
get_all_objects = cast(
Callable[..., object], _import_attr("._objects", "get_all_objects")
)
DatasetBounds = cast(type[object], getattr(data, "DatasetBounds"))
CameraPose = cast(type[object], getattr(data, "CameraPose"))
CameraExactState = cast(type[object], getattr(data, "CameraExactState"))
ViewState = cast(type[object], getattr(data, "ViewState"))
CameraState = cast(type[object], getattr(data, "CameraState"))
PerspectiveState = cast(type[object], getattr(data, "PerspectiveState"))
SessionState = cast(type[object], getattr(data, "SessionState"))
WindowInfo = cast(type[object], getattr(data, "WindowInfo"))
WindowList = cast(type[object], getattr(data, "WindowList"))
WindowSplitResult = cast(type[object], getattr(data, "WindowSplitResult"))
get_session_state = cast(Callable[..., object], getattr(data, "get_session_state"))
Range = cast(type[object], getattr(_utils, "Range"))
RangedValue = cast(type[object], getattr(_utils, "RangedValue"))
LegendAnnotation = cast(type[object], getattr(_utils, "LegendAnnotation"))
LegendAnnotationText = cast(type[object], getattr(_utils, "LegendAnnotationText"))
LegendContour = cast(type[object], getattr(_utils, "LegendContour"))
LegendLabels = cast(type[object], getattr(_utils, "LegendLabels"))
Legend = cast(type[object], getattr(_utils, "Legend"))
LegendSpectrum = cast(type[object], getattr(_utils, "LegendSpectrum"))
RuledGridAxisOptions = cast(type[object], getattr(_utils, "RuledGridAxisOptions"))
RuledGridOptions = cast(type[object], getattr(_utils, "RuledGridOptions"))
ScalarAnnotation = cast(type[object], getattr(_utils, "ScalarAnnotation"))
Colormap = cast(type[object], getattr(_utils, "Colormap"))
ScalarMinMax = cast(type[object], getattr(_utils, "ScalarMinMax"))
TripletLike = cast(type[object], getattr(_utils, "TripletLike"))
VectorOptions = cast(type[object], getattr(_utils, "VectorOptions"))
__all__: list[str] = [
"export_image",
"export_png",
"export_jpg",
"export_bmp",
"exit",
"fv_script",
"restart_read_component",
"undo",
"redo",
"get_current_object",
"get_all_objects",
"ObjectLists",
"DatasetBounds",
"WindowInfo",
"WindowList",
"WindowSplitResult",
"CameraPose",
"CameraExactState",
"ViewState",
"CameraState",
"PerspectiveState",
"SessionState",
"get_session_state",
"home",
"constant",
"data",
"exceptions",
"formula",
"vis",
"camera",
"layout",
"view",
"Range",
"RangedValue",
"LegendAnnotation",
"LegendAnnotationText",
"LegendContour",
"LegendLabels",
"Legend",
"LegendSpectrum",
"RuledGridAxisOptions",
"RuledGridOptions",
"ScalarAnnotation",
"Colormap",
"ScalarMinMax",
"TripletLike",
"VectorOptions",
"FieldViewError",
"InvalidArgumentError",
"InvalidDatasetError",
"CoreError",
"__version__",
"__fieldview_compat__",
]
_get_fv_home = getattr(_core_module, "get_fv_home", None)
home: str = str(_get_fv_home()) if callable(_get_fv_home) else ""
[docs]
def exit(status: int = 0) -> None:
"""Exit the FieldView host process.
This is the direct Python API for host shutdown.
Args:
status: Process exit status to report back to test harnesses or other
automation. Defaults to ``0``.
Example:
.. code-block:: python
import fieldview as fv
fv.exit()
# or
fv.exit(2)
"""
if not isinstance(status, int) or isinstance(status, bool):
raise InvalidArgumentError("status must be an integer")
func = getattr(_core_module, "exit", None)
if not callable(func):
raise CoreError("FieldView host does not provide exit.")
_core_call(func, status)
[docs]
def fv_script(script: str) -> None:
"""Execute SCR script text through the FieldView host.
Args:
script: SCR command text to execute. The string must be non-empty after
trimming whitespace.
Example:
.. code-block:: python
import fieldview as fv
fv.fv_script("OUTLINE ON")
"""
if not isinstance(script, str):
raise InvalidArgumentError("script must be a string")
if not script.strip():
raise InvalidArgumentError("script must not be empty")
func = getattr(_core_module, "fv_script", None)
if not callable(func):
raise CoreError("FieldView host does not provide fv_script.")
_core_call(func, script)
def restart_read_component(kind: str, filename: str) -> None:
"""Read one restart component file through native host restart handlers.
Args:
kind: Restart component family, such as ``"comp"``, ``"iso"``,
``"stream"``, ``"coord"``, ``"paths"``, ``"vcore"``,
``"boundary"``, ``"formula"``, ``"view"``, ``"color"``,
``"line"``, ``"presentation"``, or ``"dynamic_clip"``.
filename: Path to the restart component file.
"""
if not isinstance(kind, str):
raise InvalidArgumentError("kind must be a string")
if not kind.strip():
raise InvalidArgumentError("kind must not be empty")
if not isinstance(filename, str):
raise InvalidArgumentError("filename must be a string")
if not filename.strip():
raise InvalidArgumentError("filename must not be empty")
func = getattr(_core_module, "restart_read_component", None)
if not callable(func):
raise CoreError("FieldView host does not provide restart_read_component.")
_core_call(func, kind, filename)
if kind.strip().lower() == "formula":
refresh = getattr(data, "_refresh_current_dataset_function_lists", None)
try:
if callable(refresh):
refresh()
except Exception:
pass
