Quick Start
===========

.. contents::
   :local:
   :depth: 2

This page gives you an introduction on how to get started with PyFieldView.
For installation and system requirements, see the
:doc:`installation instructions <installation>`.

This example loads a Plot3D dataset from ``<FieldView install>/examples/f18``
via ``fv.home`` and exports an image.

Getting Started Example
-----------------------

.. literalinclude:: _examples/load_export_example.py
   :language: python
   :emphasize-lines: 10-12,16,18

Related API symbols:

- :func:`fieldview.data.load_plot3d`
- :attr:`fieldview.data.Dataset.num_grids`
- :func:`fieldview.export.export_png`

Python Script Errors
--------------------

Interactive or GUI sessions
~~~~~~~~~~~~~~~~~~~~~~~~~~~

When you run a script from ``Tools > Execute Python File...`` or from
``-python``, FieldView distinguishes a few different failure cases:

- **Startup or preflight failures**: if FieldView cannot initialize a supported
  Python runtime, cannot find the required helper components, or the license
  does not include valid `TecPLUS™ <https://tecplot.com/support/support-policy/>`_
  Software Maintenance Service (SMS) for Python scripting, the script does not
  start. FieldView reports the startup problem before any user code runs.
- **Unhandled Python exceptions**: if your script hits a normal Python error
  that is not caught with ``try``/``except``, FieldView stops the script at the
  failing line. This includes both regular Python errors such as undefined
  names (``NameError``), missing files (``FileNotFoundError``), and type or
  value mistakes in your script, and PyFieldView-specific exceptions from
  :mod:`fieldview.exceptions`. In general, regular Python exceptions come from
  your script or the Python runtime, while ``fieldview.exceptions`` usually
  mean the Python call reached FieldView but FieldView rejected the request or
  reported a backend failure such as ``fieldview.exceptions.CoreError``. For a
  full list of PyFieldView exception types, see :mod:`fieldview.exceptions`.
  FieldView prints the full traceback to the console and, in GUI mode, also
  shows a popup with a short summary. Close the popup and inspect the console
  to see the file name, line number, and full call stack for the error.

Batch mode
~~~~~~~~~~

When you run FieldView in batch mode, for example with ``-batch -python``, GUI
error popups are suppressed. Use the console output and the process exit status
to diagnose startup problems, Python exceptions, and other script failures.