# First Steps with eVision

<a id="first-steps-cpp"></a>

## First Steps In C++

The only requirement to use **eVision** in C++ is to include the headers. Those headers form a header-only C++ library that is able to load the `eVision DLL`.

The location of those headers depends on the platform:

* On **Windows**, they are located in `C:\Program Files\Allied Vision\eVision 26.10\Include`
* On **Linux**, they are located in `/opt/alliedvision/eVision_26_10/include`

No linker settings are required when using the C++ version of **eVision**.

### Header Inclusion

#### Using Minimal Headers (most recommended)

Each type in **eVision** appears in a specific header that can be included using `#include <eVision/*.h>`.

The minimal header for each type is indicated in its corresponding page in the [C++ Api Documentation](../doxygen_cpp.html.md).

Example: the minimal include line for the [`Easy`](../doxygen_cpp/classeVision_1_1Easy.html) class is `#include <eVision/Easy/Easy.h>`.

Using minimal headers for each type is recommended for the best C++ compilation performances.

#### HINT
You can use the C++ samples as reference, as they include only the relevant headers.

#### Using Library-Focused Headers

It is also possible to include all the types of a given library within \**eVision*.

These headers are:

* `Easy.h`
* `Easy3D.h`
* `EasyBarCode.h`
* `EasyColor.h`
* `EasyDeepLearning.h`
* `EasyFind.h`
* `EasyGauge.h`
* `EasyImage.h`
* `EasyMatch.h`
* `EasyMatrixCode.h`
* `EasyObject.h`
* `EasyOcr.h`
* `EasyOcv.h`
* `EasyQRCode.h`

Just use, as example, `#include <Easy.h>` to get access to all the types in the **Easy** library.

#### Using the Global Header (least recommended)

Include the main **eVision** header (`eVision.h`) using `#include <eVision.h>`.

This includes **all** the types in **eVision**, which is convenient but not recommended for C++ compilation performances.

### Configuring the Compiler

#### On Windows

#### HINT
It is recommended to use **Microsoft Visual C++**.

The headers of **eVision** have a lot of content, and it is highly recommended:

* To include the headers into a precompiled header to avoid unnecessarily recompilations.
* When using **Visual C++**:
  * to use the following settings to avoid compilation issues:
    * `/bigobj`: allows the compiler to handle more code in the headers.
    * `/zm256` (or bigger): allows bigger precompiled headers.
  * To disable `Browse Information`, as it is superseded by **Intellisense** and it is known to crash when handling big projects.

#### On Linux

#### HINT
It is recommended to use the latest version of **GCC** available for the current **Linux** distribution.

### C++ Library Initialization and Termination

The C++ version of **eVision** requires a library initialization and termination process.

There are two possible modes for this initialization:

1. ***Automatic***: the library is automatically initialized when it is used for the first time and automatically terminated at the end of the process. This is the default mode.
2. ***Manual***: no automatic behavior occurs and the initialization and the termination must be done manually.

While the default automatic mode is suitable for most use cases, there are some specific cases where it is not fully functional, especially when is used inside a shared library. In these cases it is recommended to switch to the manual initialization and termination mode.

To perform the manual initialization and termination, use the following methods:

```c++
using namespace eVision;
// at start
Preconfiguration::SetInitializationMode(EInitializationMode_Manual);
Preconfiguration::Initialize();
// at end
Preconfiguration::Terminate();
```

<a id="first-steps-net"></a>

## First Steps in .NET

#### WARNING
The .NET version of **eVision** is available on **Windows** only.

To use **eVision** with .NET:

* Add a reference to the `eVision_NetApi.dll` file to your project in your development environment.

  That file is located in:

  `C:\Program Files\Allied Vision\eVision 26.10\Bin\eVision_NetApi.dll`

  #### NOTE
  You do not need to copy any other DLL.
* Declare the usage of **eVision** at the top of your source code files:
  ```cs
  using eVision;
  ```

<a id="first-steps-python"></a>

## First Steps in Python

### Installing Python

**Python** 3.11 or later is required to use the Python bindings for **eVision**.

#### NOTE
No other third party dependencies are necessary to use the Python bindings.

#### On Windows

The recommended way is to install Python is to download an installer from the official Python website:

`https://www.python.org/`

#### On Linux (Ubuntu/Debian example)

#### TIP
You can check your current Python version using `python3 --version`.

If your default Python version is **>= 3.11** (**Ubuntu >= 23.04** and **Debian >= 12**):

* That version of Python is sufficient to use the Python Bindings for **eVision**.
* You can ensure all necessary packages are installed with:
  ```bash
  sudo apt-get install python3 python3-venv
  ```

If your default Python version is **< 3.11** (**Ubuntu <= 22.10**):

* The default installed version of Python is not sufficient.
* You can install another version using [uv](https://docs.astral.sh/uv/)
* Example:
  ```bash
  # ensure curl is installed
  sudo apt-get update
  sudo apt-get install curl ca-certificates
  # install uv
  curl -LsSf https://astral.sh/uv/install.sh | sh
  source $HOME/.local/bin/env
  # install python 3.13
  uv python install 3.13 --default # python 3.11 minimum
  ```

  Then the `python3 --version` command should display the version you installed.

### Installing the Python Bindings

#### NOTE
While the direct installation of pip dependencies outside a [venv](https://docs.python.org/3/library/venv.html) is always possible and is fully supported by the eVision Python bindings, most recent Linux distributions forbid direct installation of those dependencies by default. As such, this guide exclusively recommends using a venv.

First initialize a [venv](https://docs.python.org/3/library/venv.html) using:

```bash
python3 -m venv ./venv
```

Then load it in the current CLI environment (must be done at each restart of the shell):

```bash
# linux bash
source ./venv/bin/activate
# windows Powershell
.\venv\Scripts\Activate.ps1
# windows git bash
source ./venv/Scripts/activate
```

To install the Python binding you must then type a `pip install` command.

* On **Windows**, the command is:
  ```bash
  pip install "C:\Program Files\Allied Vision\eVision 26.10\Python\ evision-26.10.0-beta.2.dev-PLATFORM.whl"
  ```
* On **Linux**, the command is:
  ```bash
  pip install /opt/alliedvision/eVision_26_10/Python/evision-26.10.0-beta.2.dev-PLATFORM.whl
  ```

The Python Bindings for eVision are installed in your venv. As example you can test it interactively using:

```bash
python3
```

Then:

```python
import eVision
help(eVision)
```

### Usage

In any Python environment where the Python bindings are properly installed, just use:

```python
import eVision
```

The various components of **eVision** are available directly under the `eVision` Python package. As example:

```python
import eVision
point = eVision.EPoint(10, 10)
```

If you are using a Python IDE, all the **eVision** API support auto-completion with type information and documentation.

#### HINT
The recommended IDE is [**Visual Studio Code**](https://code.visualstudio.com/) with the extensions that are automatically recommended by the editor when opening a `.py` file.

### Using the Sample Programs

The sample programs for the Python bindings for are available in `<evision_samples_folder>/Sample Programs/Python samples`

Please note that most samples have Python dependencies aside from `evision` in `requirements.txt` files.

To install those dependencies use the following command:

```bash
pip install –r ./requirements.txt
```