"""Separation-line feature-extraction path helpers.
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"),
... )
>>> sep = fv.vis.create_separation_lines(ds)
>>> sep.coloring = fv.constant.Coloring.SCALAR
"""
from __future__ import annotations
from .. import _core
from .. import constant
from .._core_utils import _core_call
from .._base import PathBase
from ..data import Dataset, _resolve_dataset_or_current
from ..exceptions import InvalidArgumentError
from ..utils import Colormap, Legend
from .surface_flows import (
_build_path_visual_payload,
_feature_state_kwargs,
_require_dataset,
)
__all__: list[str] = ["SeparationLines", "create_separation_lines"]
[docs]
class SeparationLines(PathBase):
"""Separation-line path wrapper.
Example usage:
.. 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"),
... )
>>> sep = fv.vis.create_separation_lines(ds)
>>> sep.coloring = fv.constant.Coloring.SCALAR
"""
_core_prefix = "separation_lines"
__slots__ = ("_dataset",)
def __init__(
self, phigs_obj: int, dataset_id: int, dataset: Dataset | None = None
) -> None:
"""Create a separation-lines wrapper around an existing host object.
Args:
phigs_obj: Host PHIGS object identifier for the feature object.
dataset_id: Host dataset identifier backing the feature object.
dataset: Optional live :class:`Dataset` wrapper for validation.
"""
super().__init__(phigs_obj, dataset_id)
self._dataset = dataset
def _state(self) -> dict[str, object]:
return _core_call(_core.separation_lines_get_state, self._phigs_obj)
@property
def display_type(self) -> constant.PathsDisplayType:
"""`PathsDisplayType`: Display representation for separation lines."""
return constant.PathsDisplayType.COMPLETE
@display_type.setter
def display_type(self, value: constant.PathsDisplayType | str) -> None:
normalized = (
value.value
if isinstance(value, constant.PathsDisplayType)
else str(value).strip().lower()
)
if normalized != constant.PathsDisplayType.COMPLETE.value:
raise InvalidArgumentError(
"separation lines only support display_type='complete'"
)
[docs]
def modify(
self,
*,
visibility: bool | None = None,
line_type: constant.LineType | str | None = None,
geometric_color: constant.GeometricColor | int | None = None,
coloring: constant.Coloring | str | None = None,
colormap: Colormap | dict[str, object] | None = None,
legend: Legend | dict[str, object] | None = None,
) -> None:
"""Modify multiple separation-line display settings.
Args:
visibility: Whether the object is visible.
line_type: Line style used for the extracted lines.
geometric_color: Geometric color id used when geometric coloring is
active.
coloring: Coloring mode for the extracted lines.
colormap: Scalar colormap options.
legend: Legend options.
"""
payload = _build_path_visual_payload(
visibility=visibility,
line_type=line_type,
geometric_color=geometric_color,
coloring=coloring,
colormap=colormap,
legend=legend,
)
if not payload:
raise InvalidArgumentError("modify requires at least one property")
_core_call(_core.separation_lines_modify, self._phigs_obj, payload)
[docs]
def copy(self) -> "SeparationLines":
"""Return a new separation-line object with the same settings."""
dataset = _require_dataset(self._dataset, "separation lines")
return create_separation_lines(dataset, **_feature_state_kwargs(self._state()))
[docs]
def delete(self) -> None:
"""Delete this separation-line object."""
self._delete_surface(_core.separation_lines_delete)
[docs]
def create_separation_lines(
dataset: Dataset | None = None,
*,
visibility: bool | None = None,
line_type: constant.LineType | str | None = None,
geometric_color: constant.GeometricColor | int | None = None,
coloring: constant.Coloring | str | None = None,
colormap: Colormap | dict[str, object] | None = None,
legend: Legend | dict[str, object] | None = None,
) -> SeparationLines:
"""Create a separation-line feature-extraction object.
Args:
dataset: Dataset to attach the new feature object to. When omitted,
the current dataset is used.
visibility: Whether the object is initially visible.
line_type: Line style used for the extracted lines.
geometric_color: Geometric color id used when geometric coloring is
active.
coloring: Coloring mode for the extracted lines.
colormap: Scalar colormap options.
legend: Legend options.
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"),
... )
>>> sep = fv.vis.create_separation_lines(
... ds,
... coloring=fv.constant.Coloring.SCALAR,
... )
"""
ds = _resolve_dataset_or_current(dataset)
payload = _build_path_visual_payload(
visibility=visibility,
line_type=line_type,
geometric_color=geometric_color,
coloring=coloring,
colormap=colormap,
legend=legend,
)
phigs_obj = _core_call(_core.separation_lines_create, ds.dataset_id)
surf = SeparationLines(phigs_obj=phigs_obj, dataset_id=ds.dataset_id, dataset=ds)
if payload:
try:
_core_call(_core.separation_lines_modify, phigs_obj, payload)
except Exception:
_core_call(_core.separation_lines_delete, phigs_obj)
raise
return surf
