.. _getting_started: =============== Getting started =============== To use PyEnSight, you must have a locally installed and licensed copy of Ansys EnSight 2022 R2 or later. To obtain a copy, see the `Ansys EnSight `_ page on the Ansys website. Install the package ------------------- The ``ansys-pyensight-core`` package supports Python 3.8 through Python 3.11 on Windows and Linux. Install the latest package with this command: .. code:: pip install ansys-pyensight-core If you plan on doing local *development* of PyEnSight on Linux, install the latest package with these commands: .. code:: git clone https://github.com/ansys/pyensight cd pyensight pip install virtualenv virtualenv venv # create virtual environment source venv/bin/activate # (.\venv\Scripts\activate for Windows shell) pip install .[dev] # install development dependencies You can then start developing PyEnSight. To build and install PyEnSight, run these commands: .. code:: python -m build # build # this replaces the editable installation done previously. If you don't want # to replace, switch your virtual environments to test the new install separately. pip install .[tests] # install test dependencies pytest # Run the tests Set up ``pre-commit`` --------------------- ``pre-commit`` is a multi-language package manager for pre-commit hooks. To install ``pre-commit`` into your git hooks, run this command: .. code:: pre-commit install ``pre-commit`` now runs on every commit. Each time that you clone a repository, running the preceding command to install ``pre-commit`` is always the first thing that you should do. If you want to manually run all pre-commit hooks on a repository, run this command: .. code:: pre-commit run --all-files A bunch of formatters run on your source files. To run individual hooks, use this command: .. code:: pre-commit run You can obtain the ```` from the ``.pre-commit-config.yaml`` file. The first time ``pre-commit`` runs on a file, it automatically downloads, installs, and runs the hook. Start the EnSight session ------------------------- The simplest way of starting an EnSight session is to use the following code, which looks for a local Ansys software installation to use to launch an EnSight instance on the local system. .. vale off .. code:: python from ansys.pyensight.core import LocalLauncher session = LocalLauncher().start() Optionally, you can start an EnSight Docker container by using code like this: .. code:: python from ansys.pyensight.core import DockerLauncher launcher = DockerLauncher(data_directory=r"d:\data", use_dev=True) launcher.pull() session = launcher.start() .. vale on In the preceding code, the ``data_directory`` argument specifies the host directory to map into the container at the mount point, providing access to the data within the container. This provides a method for EnSight running in the container to access the host's file system to read or write data. The optional ``use_dev=True`` argument specifies that the latest development version of EnSight should be used. Run commands ------------ Once an EnSight instance is running, you can use the session interface to interact with it. The :func:`cmd` method can execute any Python string in the EnSight Python interpreter. For example, this code returns the value 25.0: .. code:: python value = session.cmd("10.*2.5") The following code uses the :func:`load_data` method to load a dataset and render the current scene into a PNG-formatted stream. .. code:: python session.load_data('D:/data/CFX/example_data.res') image_data = session.render(1920, 1080, aa=4) with open("image.png", "wb") as f: f.write(image_data) The resulting image, which is rendered using 4x antialiasing, is 1920x1080 pixels. You can use the :func:`show` method to view or interact with the current EnSight session via the web. This method supports creating various graphical representations and returns URLs for viewing or interacting with these representations. .. code:: python remote = session.show("remote") remote.browser()