アバールデータ のAcaPyとは？基本機能と始め方

アバールデータ社が提供する画像入力ライブラリ**AcapLib2のPython版であるAcaPy** について、その基本的な使い方から応用的な機能までを解説していきます。今回は、AcaPyの概要、インストール方法、そして基本的な画像の取り込み方についてご紹介します。

## AcaPyとは

**AcaPy (エーキャッパイ)** は、アバールデータ製の**画像入力ボード**や**カメラ**をPython環境で制御するためのライブラリです。従来のC/C++で開発されてきたAcapLib2の関数をクラスにまとめ、Pythonから手軽に利用できるため、画像処理や計測などのアプリケーション開発を効率的に行うことができます。AcaPyは**Windows版のみ**に対応しています。

## AcaPyのインストール

AcaPyを利用するためには、まずPython環境にAcaPyをインストールする必要があります。以下の手順に従ってください。

1. pipのアップデート

   : コマンドプロンプトまたはターミナルを開き、以下のコマンドを実行してpipを最新の状態にアップデートします。

   ```
   py -m pip install --upgrade pip
   ```

2. AcaPyのインストール

   : 続いて、以下のコマンドを実行してAcaPyをインストールします。

   ```
   py -m pip install acapy
   ```

### バージョン依存関係について

AcaPyは内部でAcapLib2の関数を使用しているため、**AcaPyとAcapLib2の間にはバージョン依存関係が存在します**。ご使用のAcaPyのバージョンに合わせて、適切なAcapLib2をインストールする必要があります。

| AcaPyバージョン | AcapLib2バージョン | 備考                               |
| --------------- | ------------------ | ---------------------------------- |
| Ver.1.2.0       | Ver.8.3.1以降      | アバールデータ製GigEカメラ対応追加 |
| Ver.1.1.0       | Ver.8.2.0以降      | CoaXPressボード対応追加            |
| Ver.1.0.0       | Ver.7.3.0のみ      | CameraLinkボードのみ対応           |

詳細は、PyPIのAcaPyのページ (https://pypi.org/project/acapy/) のDependenciesをご確認ください。

## AcaPyの基本的な使い方

AcaPyを使った基本的な画像の取り込み方を見ていきましょう。

初めに画像を一枚撮影し、OpenCVで画像を表示するプログラムを示します。

```Python
import acapy
import cv2

# AcaPyクラスのインスタンス
# CameraLink, CoaXPressボードのBoardID=0, カメラCh=1の場合
capture = acapy.AcaPy(board_id = 0, ch = 1)
# AVALDATA製GigEカメラの場合
#capture = acapy.AcaPy("GigE")

# 画像入力ボードの設定
# GigEカメラのとき、load_inifile()は不要です。
capture.load_inifile("./AreaSensor_mono.ini")

# 画像取込
ret, frame = capture.snap()

# 画像表示
cv2.imshow("Image", frame)
cv2.waitKey()

# 解放
capture.release()
```



### AcaPyクラスのインスタンス化

まず、AcaPyを操作するための**AcaPyクラスのインスタンス**を作成します。画像入力ボードを使用する場合と、GigEカメラを使用する場合でインスタンス化の方法が異なります。

#### 画像入力ボード（CameraLink, CoaXPressなど）を使用する場合

ボードのID（`board_id`）とチャンネル番号（`ch`）を指定してインスタンスを作成します。初期値は `board_id = 0`, `ch = 1` です。

```Python
import acapy

# Board ID 0, チャンネル 1 でインスタンスを作成
capture = acapy.AcaPy(board_id=0, ch=1)

# 必要に応じて board_id や ch を変更します
# capture = acapy.AcaPy(board_id=1, ch=2)
```

使用するカメラに合わせて、**設定.iniファイル**を読み込む必要があります。
iniファイルはAcapLib2で使用されているファイルを指定します。
GigEカメラの場合は不要です。

```python
# iniファイルの読み込み (GigEカメラの場合は不要)
capture.load_inifile("./AreaSensor_mono.ini")
```

#### アバールデータ製GigEカメラを使用する場合

コンストラクタに **`"GigE"`** という文字列を指定してインスタンスを作成します。これにより、最初に見つかったGigEカメラが使用されます。複数のGigEカメラを使用する場合は、`"GigE"` の後にインデックス番号（1, 2, 3...）を指定するか、IPアドレスの文字列を指定します。

```python
import acapy

# 最初に見つかったGigEカメラを使用
capture_gige = acapy.AcaPy("GigE")

# インデックス番号を指定 (例: 2番目のカメラ)
# capture_gige = acapy.AcaPy("GigE", 2)

# IPアドレスを指定
# capture_gige = acapy.AcaPy('169.254.7.40')

# 接続されているGigEカメラの一覧を取得して指定することも可能です
cameras = acapy.AcaPy.get_camera_list()
print(cameras)
# [('169.254.7.40', 1, 'ABA-001IR-GE', 1234568790), ('169.254.7.41', 2, 'ABA-001IR-GE', 1234568791)]
# capture_gige = acapy.AcaPy(cameras)
```

GigEカメラを使用する際は、**ファイアウォールを無効にするか、アプリケーションの許可**を行ってください。

### 画像の取り込み

AcaPyで画像を一枚取り込むには、**`snap()`** メソッドを使用します。

```python
# 画像を１枚取得
ret, frame = capture.snap()

if ret == 1:
    print("画像を正常に取得しました")
    # frame にOpenCVと同等の画像データ（NumPyのndarray形式）が格納されます
else:
    print("画像の取得に失敗しました")
```

連続して画像を取り込む場合は、**`grab_start()`** メソッドで取り込みを開始し、**`read_frames()`** メソッドで画像データを取得、**`grab_stop()`** メソッドで停止します。

```python
# 画像取込開始
capture.grab_start()

while True:
    ret, frames, count, frame_no = capture.read_frames()
    if ret == 0:
        capture.print_last_error()
        break
    if frames is not None:
        # 前回取得した画像の次の画像から今回までの画像をリスト(frames)で取得
        print(f"取得フレーム数: {count}, 総フレーム数: {frame_no}")
        # ここで取得した画像 のframes[0]～frames[count - 1]) に対して処理します

    # 何らかの終了条件、キー入力など
    #　ここでは画像を100枚撮影したら終了
    if frame_no > 100:
        break

# 画像取込停止
capture.grab_stop()
```

### リソースの解放

AcaPyクラスのオブジェクトを使用しなくなったら、**`release()`** メソッドでリソースを解放する必要があります。

```python
# リソースの解放
capture.release()
```

## AcaPyの主な機能

AcaPyは、基本的な画像の取り込み以外にも様々な機能を提供しています。

- **多様なインターフェース**: CameraLink, CoaXPress, 10GigEといった様々なカメラインターフェースに対応。
- **画像入力ボード制御**: 画像のサイズ、ビット深度などのボードパラメータを設定可能。
- **GigEカメラ制御**: IPアドレスによる指定や、接続されたカメラリストからの選択が可能。
- **カメラパラメータ制御**: 露光時間、ゲインなど、カメラ固有のパラメータを制御するための **CameraControlクラス** を提供。
- **連続画像取り込み (Grab)**: バッファリングやコールバック機能を利用した効率的な連続画像取得。
- **コールバック機能**: 特定のイベント（フレーム終了、アラーム発生など）発生時にユーザー定義の関数を呼び出すことが可能。
- **複数ボード・複数カメラ対応**: 複数の画像入力ボードやカメラを同時に制御可能。

## サンプルプログラム

AcaPyのより具体的な使用方法については、アバールデータのウェブサイトで**サンプルプログラム**が提供されています。シンプルなスナップショットや連続画像取り込み、コールバック関数の利用など、様々なサンプルコードが用意されていますので、ぜひご参照ください。

- **サンプルプログラムダウンロード**: https://faq-avaldata.dga.jp/faq_detail.html?id=462

これらのサンプルプログラムは、AcaPyの理解を深める上で非常に役立ちます。



AcaPyを活用して、あなたの画像処理アプリケーション開発をさらに加速させてください。