Examples ======== .. contents:: :local: :depth: 2 Loading a Dataset and Exporting an Image ---------------------------------------- This example loads a Plot3D dataset from ``fv.home/examples/f18`` and exports an image. .. literalinclude:: _examples/load_export_example.py :language: python :emphasize-lines: 10-12,16,18 Expected visual result: .. figure:: _static/example_images/load_export_example.png :alt: Expected result for load_export_example.py :width: 50% Expected output from ``load_export_example.py``. Related API symbols: - :func:`fieldview.data.load_plot3d` - :attr:`fieldview.data.Dataset.num_grids` - :func:`fieldview.export.export_png` Coordinate Surface ------------------ This example creates 20 coordinate surfaces spaced across the X axis, applies scalar coloring with constant shading, disables outlines, and sets each surface transparency to 0.75. .. literalinclude:: _examples/coord_surface_example.py :language: python :emphasize-lines: 17,20-24,26-28 Expected visual result: .. figure:: _static/example_images/coord_surface_example.png :alt: Expected result for coord_surface_example.py :width: 50% Expected output from ``coord_surface_example.py``. Related API symbols: - :func:`fieldview.vis.create_coord` - :attr:`fieldview.vis.Coord.plane` - :attr:`fieldview.vis.Coord.x_plane` - :attr:`fieldview.vis.Coord.transparency` .. note:: When **modify(...)** is available, PyFieldView can batch several property updates into one host-side modify command. For example, one round trip can update several coordinate-surface properties together: .. code-block:: python cs.modify( coloring=fv.constant.Coloring.SCALAR, scalar_func=ds.scalar_functions[0], display_type=fv.constant.DisplayType.CONSTANT, ) instead of separate round trips for: .. code-block:: python cs.coloring = fv.constant.Coloring.SCALAR cs.scalar_func = ds.scalar_functions[0] cs.display_type = fv.constant.DisplayType.CONSTANT If those values are known when the object is created and are not going to be modified later, prefer passing them directly to **create_coord(...)** so the surface is configured in the initial create call. Computational Surface --------------------- This example creates a computational surface on grid 1 and positions it along the I plane. .. literalinclude:: _examples/comp_surface_example.py :language: python :emphasize-lines: 13-16 Expected visual result: .. figure:: _static/example_images/comp_surface_example.png :alt: Expected result for comp_surface_example.py :width: 50% Expected output from ``comp_surface_example.py``. Related API symbols: - :func:`fieldview.vis.create_comp` - :attr:`fieldview.vis.Comp.plane` - :attr:`fieldview.vis.Comp.i_plane` - :attr:`fieldview.vis.Comp.coloring` Iso Surface ----------- This example creates an iso surface from ``"Mach number [PLOT3D]"``, sets its iso value to ``0.31``, applies scalar coloring and transparency, then adjusts the camera with ``zoom()`` and ``pan()``. .. literalinclude:: _examples/iso_surface_example.py :language: python :emphasize-lines: 22-26,28-29 Expected visual result: .. figure:: _static/example_images/iso_surface_example.png :alt: Expected result for iso_surface_example.py :width: 50% Expected output from ``iso_surface_example.py``. Related API symbols: - :func:`fieldview.vis.create_iso` - :attr:`fieldview.vis.Iso.iso_value` - :attr:`fieldview.vis.Iso.coloring` - :attr:`fieldview.vis.Iso.transparency` - :func:`fieldview.camera.zoom` - :func:`fieldview.camera.pan` Boundary Surface ---------------- This example creates a boundary surface, enables all boundary types, and applies scalar coloring with a colormap. .. literalinclude:: _examples/boundary_surface_example.py :language: python :emphasize-lines: 15-19 Expected visual result: .. figure:: _static/example_images/boundary_surface_example.png :alt: Expected result for boundary_surface_example.py :width: 50% Expected output from ``boundary_surface_example.py``. Related API symbols: - :func:`fieldview.vis.create_boundary` - :attr:`fieldview.vis.Boundary.types` - :attr:`fieldview.vis.Boundary.coloring` - :attr:`fieldview.vis.Boundary.scalar_func` - :attr:`fieldview.vis.Boundary.colormap` Formula Creation ---------------- This example loads the same Plot3D dataset twice, then creates formulas from both raw FieldView text and Python builder helpers. It also shows a dataset-comparison formula built with ``dataset_quantity(...)``. .. literalinclude:: _examples/formula_example.py :language: python :emphasize-lines: 13-16,19-21,24-26,29-32 Related API symbols: - :func:`fieldview.formula.create` - :func:`fieldview.formula.dataset_quantity` - :func:`fieldview.formula.mag` Exit FieldView -------------- This example exits the FieldView host directly from Python. Use ``fv.exit(status=...)`` when the intent is to terminate the application and report a specific result to a test harness, rather than passing ``"exit"`` through :func:`fieldview.fv_script`. .. literalinclude:: _examples/exit_example.py :language: python :emphasize-lines: 5 Related API symbols: - :func:`fieldview.exit` - :func:`fieldview.fv_script` Appending Datasets ------------------ This example appends a second Plot3D dataset using the local-parallel configuration, then applies duplication and transform operations. .. literalinclude:: _examples/load_append_example.py :language: python :emphasize-lines: 9-11,15-19,23-24 Expected visual result: .. figure:: _static/example_images/load_append_example.png :alt: Expected result for load_append_example.py :width: 50% Expected output from ``load_append_example.py``. Related API symbols: - :class:`fieldview.constant.InputMode` - :class:`fieldview.constant.ServerConfig` - :func:`fieldview.data.load_plot3d` - :attr:`fieldview.data.Dataset.duplication` - :attr:`fieldview.data.Dataset.transform` Point Probes ------------ This example probes the current scalar and vector functions at a displayed point and at a structured-grid IJK location. .. literalinclude:: _examples/point_probes_example.py :language: python :emphasize-lines: 13-14 Related API symbols: - :func:`fieldview.data.probe` - :func:`fieldview.data.probe_ijk` - :class:`fieldview.data.ProbeResult` Integration ----------- This example creates a boundary surface and a coordinate surface, integrates a scalar over the boundary selection, then integrates over a connected partial region on the coordinate surface. It also writes a summary of those results into a screen annotation. .. literalinclude:: _examples/integration_example.py :language: python :emphasize-lines: 27-28,43-52 Expected visual result: .. figure:: _static/example_images/integration_example.png :alt: Expected result for integration_example.py :width: 50% Expected output from ``integration_example.py``. Related API symbols: - :meth:`fieldview.vis.Boundary.integrate` - :meth:`fieldview.vis.Coord.integrate_partial_surface` - :class:`fieldview.data.IntegrationResult` Streamlines ----------- This example creates streamlines, adds seeds, and calculates the paths. .. literalinclude:: _examples/streamlines_example.py :language: python :emphasize-lines: 22-29,45-46 Expected visual result: .. figure:: _static/example_images/streamlines_example.png :alt: Expected result for streamlines_example.py :width: 50% Expected output from ``streamlines_example.py``. Changing ``sl.seed_coord`` after seeds have been added is rejected. Call ``sl.delete_all_seeds()`` first if you need to switch between ``IJK``, ``IJK_REAL``, and ``XYZ`` seed coordinates. When using ``sl.seed_surface(...)``, the source surface must still be live and must come from the same dataset as the streamline object. Streak controls follow one Python-side contract: ``release_interval`` must be greater than ``0`` and ``duration`` must be greater than ``0`` and smaller than ``release_interval``. Invalid values are rejected before any core call. Related API symbols: - :func:`fieldview.vis.create_streamlines` - :attr:`fieldview.vis.Streamlines.seed_coord` - :meth:`fieldview.vis.Streamlines.add_seeds` - :meth:`fieldview.vis.Streamlines.calculate` Particle Paths -------------- This example imports a particle-path file, applies scalar coloring, and enables animation. .. literalinclude:: _examples/particle_paths_example.py :language: python :emphasize-lines: 15-24,26-27 Related API symbols: - :func:`fieldview.vis.create_particle_paths` - :class:`fieldview.vis.ParticlePaths` - :attr:`fieldview.vis.ParticlePaths.scalar_func` - :attr:`fieldview.vis.ParticlePaths.select_by_initial_value` - :attr:`fieldview.vis.ParticlePaths.select_by_initial_value_variable` 2D Plot ------- This example creates a 2D plot on the current dataset, defines one centerline volume path, and exports that path using FieldView's native path text format. Non-fatal Plot2D host diagnostics are emitted as Python warnings and may appear in the Python console during interactive use. .. literalinclude:: _examples/plot2d_example.py :language: python :emphasize-lines: 17-20,23-25,31 Expected visual result: .. figure:: _static/example_images/plot2d_example.png :alt: Expected result for plot2d_example.py :width: 50% Expected output from ``plot2d_example.py``. Related API symbols: - :func:`fieldview.vis.create_plot2d` - :class:`fieldview.vis.Plot2D` - :meth:`fieldview.vis.Plot2D.create_line_path_volume` - :attr:`fieldview.vis.Plot2DAxis.label` - :meth:`fieldview.vis.Plot2DPath.export_txt` Surface Flows ------------- This example creates a surface flow object, updates its scalar path variable, calculates the flow, and enables a local colormap range. .. literalinclude:: _examples/surface_flows_example.py :language: python :emphasize-lines: 21-29,31-32 Expected visual result: .. figure:: _static/example_images/surface_flows_example.png :alt: Expected result for surface_flows_example.py :width: 50% Expected output from ``surface_flows_example.py``. Related API symbols: - :func:`fieldview.vis.create_surface_flows` - :attr:`fieldview.vis.SurfaceFlows.scalar_path_variable` - :meth:`fieldview.vis.SurfaceFlows.calculate` - :attr:`fieldview.utils.Colormap.use_local` - :class:`fieldview.constant.SurfaceFlowMode` - :class:`fieldview.constant.SurfaceFlowSeeding` Vortex Cores ------------ This example creates a vortex-cores surface, enables scalar coloring, and sets the scalar colormap. .. literalinclude:: _examples/vortex_cores_example.py :language: python :emphasize-lines: 13-16,18-20 Expected visual result: .. figure:: _static/example_images/vortex_cores_example.png :alt: Expected result for vortex_cores_example.py :width: 50% Expected output from ``vortex_cores_example.py``. Related API symbols: - :func:`fieldview.vis.create_vortex_cores` - :class:`fieldview.vis.VortexCores` - :attr:`fieldview.vis.VortexCores.coloring` - :attr:`fieldview.vis.VortexCores.scalar_path_variable` - :attr:`fieldview.vis.VortexCores.colormap` Transient --------- This example loads a transient FV-UNS dataset and inspects metadata, then selects a time step and runs a simple transient sweep. ``Dataset.sweep_time()`` supports four explicit range modes: - time-step values via ``from_time_step`` / ``to_time_step`` - time-step indices via ``from_time_step_index`` / ``to_time_step_index`` - solution-time values via ``from_solution_time`` / ``to_solution_time`` - solution-time indices via ``from_solution_time_index`` / ``to_solution_time_index`` Calling ``ds.sweep_time()`` with no range arguments defaults to ``from_time_step_index=0`` and ``to_time_step_index=-1``. .. literalinclude:: _examples/transient_example.py :language: python :emphasize-lines: 9,12,17,27 Related API symbols: - :func:`fieldview.data.load_fvuns` - :meth:`fieldview.data.Dataset.set_transient` - :meth:`fieldview.data.Dataset.transient_info` - :meth:`fieldview.data.Dataset.sweep_time` - :class:`fieldview.data.TransientInfo` Registry Arrays + Derived Functions ----------------------------------- This example reads scalar, vector, and native XYZ position snapshots, then creates derived scalar and vector functions from NumPy arrays. .. literalinclude:: _examples/registry_arrays_example.py :language: python :emphasize-lines: 16-17,20-22,35-37,39-40,48-49,60 Expected visual result: .. figure:: _static/example_images/registry_arrays_example.png :alt: Expected result for registry_arrays_example.py :width: 50% Expected output from ``registry_arrays_example.py``. Related API symbols: - :attr:`fieldview.data.Dataset.scalars` - :attr:`fieldview.data.Dataset.vectors` - :attr:`fieldview.data.Dataset.positions` - :meth:`fieldview.data.ScalarRegistry.to_numpy` - :meth:`fieldview.data.VectorRegistry.to_numpy` - :meth:`fieldview.data.PositionRegistry.to_numpy` - :meth:`fieldview.data.ScalarRegistry.create` - :meth:`fieldview.data.VectorRegistry.create` Transient datasets ~~~~~~~~~~~~~~~~~~ For transient datasets, :meth:`fieldview.data.ScalarRegistry.create` and :meth:`fieldview.data.VectorRegistry.create` write values for the currently active time step (the one selected with ``ds.set_transient(...)``). To define custom arrays for multiple time steps, loop over time steps and call ``create(...)`` after selecting each step. .. code-block:: python for step in ds.transient_info().time_step_values: ds.set_transient(time_step=step) values = compute_values_for_step(ds) ds.scalars.create("My Scalar", values, grid=1) Behavior when not all time steps are explicitly written: - If you write a custom scalar/vector at only one time step, that same data is reused for all time steps. - If you write data at some time steps only, FieldView reuses the most recent previous stored frame for intermediate steps. - For steps before the first stored frame, the first stored frame is used. - For steps after the last stored frame, the last stored frame is used. - No interpolation is applied between stored time steps. .. _examples-live-session: Accessing Scene Objects ----------------------- PyFieldView can access and modify objects that were already created before the current PyFieldView script started. Create scene content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Run this once to load a dataset and create a boundary surface that the next script can discover and modify. .. literalinclude:: _examples/scene_objects_prep_boundary_example.py :language: python :emphasize-lines: 13 Discover and update objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This script uses ``fv.data.get_session_state()`` and ``fv.get_all_objects()`` to fetch existing objects, grab the first boundary surface, then: - reset the current view - turn off grid/outline display - set display type to smooth - show scalar min/max - show mesh .. literalinclude:: _examples/scene_objects_reuse_boundary_example.py :language: python :emphasize-lines: 6,12,19-23,25 Expected visual result: .. figure:: _static/example_images/scene_objects_reuse_boundary_example.png :alt: Expected result for scene_objects_reuse_boundary_example.py :width: 50% Expected output from ``scene_objects_reuse_boundary_example.py``. Related API symbols: - :func:`fieldview.data.get_session_state` - :func:`fieldview.get_all_objects` - :func:`fieldview.view.reset` - :func:`fieldview.view.set_outline` - :attr:`fieldview.vis.Boundary.display_type` - :attr:`fieldview.vis.Boundary.scalar_minmax` - :attr:`fieldview.vis.Boundary.show_mesh` Layout Management + View Control -------------------------------- This example uses the public ``fieldview.layout`` and ``fieldview.view`` submodules to split one window into two panes and apply a different view in the second pane. View functions default to the current window and also accept ``window=`` for direct targeting. The same API works in interactive and batch graphics sessions. When examples are run back-to-back in the same FV session, remember that view display toggles such as outline are shared session state. Because ``reset()``, ``center()``, and ``fit()`` all depend on the currently visible scene contents, running another script after changing them can affect how ``reset()``, ``center()``, or ``fit()`` frame the scene. Set outline explicitly when an example depends on it. For deterministic scripted navigation, call :func:`fieldview.view.reset` before a sequence of ``fieldview.view`` or ``fieldview.camera`` operations. This resets the world/view transform, but view display toggles such as outline must still be set explicitly if your script depends on them. A good default sequence after loading a dataset is: - set view display toggles such as outline explicitly - call :func:`fieldview.view.reset` - create any view-size-dependent objects - apply final :mod:`fieldview.camera` adjustments at the end This helps keep scripted results reproducible because some invariant-size or screen-sized objects can depend on the current view state at creation time. ``reset()``, ``center()``, and ``fit()`` are related but not equivalent: - :func:`fieldview.view.reset` performs the UI reset action for the world transform. It recenters the visible scene and restores the default view orientation. - :func:`fieldview.view.center` recenters the visible scene, or centers a specific world-space point when ``x``, ``y``, and ``z`` are provided. It preserves the current viewing orientation. - :func:`fieldview.view.fit` adjusts the current view so the visible scene fits well in the window while preserving the current viewing orientation. .. literalinclude:: _examples/window_view_example.py :language: python :emphasize-lines: 13,16-17,19-21,23-25 Expected visual result: .. figure:: _static/example_images/window_view_example.png :alt: Expected result for window_view_example.py :width: 50% Expected output from ``window_view_example.py``. Related API symbols: - :func:`fieldview.layout.split_horizontal` - :func:`fieldview.layout.set_view_sync` - :func:`fieldview.view.reset` - :func:`fieldview.view.align` - :func:`fieldview.view.set_perspective` Camera Navigation ----------------- This example uses the public ``fieldview.camera`` submodule for direct scripted navigation and deterministic camera state capture. It demonstrates ``look_at()`` to define a reproducible camera pose, then uses ``get_pose()`` to inspect the resulting ``eye/target/up`` values. It then performs an orbit sequence in a single window and shows ``get_state()`` before and after the scripted motion. Note: ``get_pose()`` is intended for inspection and pose-style workflows with ``look_at()``. For exact view replay, prefer ``get_state()`` + ``set_state()``. .. literalinclude:: _examples/camera_navigation_example.py :language: python :emphasize-lines: 25,29-32,37,42,45,48,51,54-55 Related API symbols: - :func:`fieldview.camera.orbit` - :func:`fieldview.camera.look_at` - :func:`fieldview.camera.get_pose` - :func:`fieldview.camera.get_state`