Adobe Illustrator SDK 覚え書き / リリース・配布編

Adobe Illustrator SDK 覚え書きから分岐しました。

前書き(本編と重複)

Adobe Illustrator SDK (以下 Ai SDK) について、自分なりにハマったところなどを晒している記事です。きちんと構成すると大変というのと、自分自身もまだ認識不足の点が多々あるので、雑ネタという体裁で追記・更新していく予定です。

以下の内容は現時点での個人的覚え書きであり、勘違いを含む可能性があります。 お気づきの点があればご指摘ください( https://twitter.com/shspage など)。


はじめに

プラグインの作成ができて、便利なので他の人にも使って欲しいとか、収益化したいとかなったとき、 プラグインファイルをそのままネットにアップロードしても、他の人は使えない場合がある。 そのあたりのこと。

windows

リリースビルドのコード生成オプションが /MD, /MDd の場合、実行に依存DLLを必要とするため、 Visual Studio とか、Visual C++ 再頒布可能パッケージが入ってないPCでは動かない。 こういった環境を準備・確認する手間をかけて欲しくない場合、リリースでは /MT に変更する。

インストールは、~.aip を Plug-ins フォルダに入れればOK。(windows10)

mac

最近のmacOSは開発元が未確認のソフトウェアへの制限が厳しくなっているので、 ネットから野良プラグインをダウンロードして追加プラグインフォルダに入れてもエラーメッセージが出て読み込まれない。

一次的にセキュリティ設定を無効にして読み込ませる、という方法もあるようだが少々危なっかしいのは否めない。

ZXP 形式のファイルを作成し、インストール用プログラムでインストールすることでセキュリティ警告を回避できる。

詳細はこちら。これは CEP extension の場合だが手順はだいたい同じ。 https://github.com/Adobe-CEP/Getting-Started-guides/blob/master/Package%20Distribute%20Install/readme.md

  1. mxi ファイルを作成し、~.aip とともにフォルダ内に配置する。
    mxiファイルの例とフォルダ構造は以下参照。
    https://gist.github.com/shspage/406ae1b2e133b0d8e6cb2541a4975958

  2. ZXPSignCmd をダウンロードする。
    https://github.com/Adobe-CEP/CEP-Resources/tree/master/ZXPSignCMD

  3. パスワードを生成する。
    ZXPSignCmd -selfSignedCert <countryCode> <stateOrProvince> <organization> <commonName> <password> <outputPath.p12> [options]
    例:./ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName abc123 MyCert.p12

  4. ZXPファイルを作成する。他の人用に配布する場合、このZXPファイルを配布することになる。
    ZXPSignCmd -sign <inputDir> <outputZxp> <p12> <p12Password> [options]
    例:./ZXPSignCmd -sign myPlugin myPlugin.zxp MyCert.p12 abc123

  5. Anastasiy’s extension manager や ExManCmd でインストールする。
    それぞれのダウンロード先や操作方法は上記 Getting-Started-guides 参照。

Adobe Exchange に登録申請する場合、この構造のZXPファイルでよいのかはわからない。

Adobe Illustrator SDK 覚え書き / オブジェクト操作編

Adobe Illustrator SDK 覚え書きから分岐しました。


前書き(本編と重複)

Adobe Illustrator SDK (以下 Ai SDK) について、自分なりにハマったところなどを晒している記事です。きちんと構成すると大変というのと、自分自身もまだ認識不足の点が多々あるので、雑ネタという体裁で追記・更新していく予定です。

以下の内容は現時点での個人的覚え書きであり、勘違いを含む可能性があります。 お気づきの点があればご指摘ください( https://twitter.com/shspage など)。

以下で Ai SDK のバージョン記載がない場合は Illustrator 2020 SDK です。

もくじ

  • 簡単な図形を描く
  • 任意のパスを描く (※ ここから下の記事は有料です)
  • 選択範囲の取得
  • ロックする/不可視にする
  • GetFirstArtOfLayer はレイヤー自身を返す
  • オブジェクトを移動・回転する
  • GetArtBounds は線幅を含む
  • HitTest/HitTestExの検出範囲
  • パスの単純化
  • 座標の計算を楽にする

簡単な図形を描く

この記事は自分的にハマったことを主に書いているので、SDK どんなもんだろう?と思って覗いた人は、何をするにも癖があり無駄に面倒といった感想を抱くかもしれない。 なので、簡単目な使い方の例も紹介しておきたい。 (sAIShape は AIShapeConstructionSuite)

// 四角を描く
AIArtHandle rectangle1;
// top, left, bottom, right, reversed, *AIArtHandle
error = sAIShape->NewRect(-50, 50, -150, 150, false, &rectangle1);

// 円を描く(内接円)
AIArtHandle circle1;
// center-X, center-Y, height, width, reversed, *AIArtHandle
error = sAIShape->NewInscribedCenteredOval(200, -100, 100, 100, false, &circle1);

円を描くほうの関数名が長いが、他に外接円を描くのとかいろいろあるのである。

上のコードを新規書類で実行すると、アートボードの左上にこのような形が描画される。

簡単な図形を描く_実行結果

座標系について

描画で指定する座標について、新規書類の原点は既定ではアートボードの左上で、X軸は右がプラス、Y軸は上がプラスの向きになる。 上の例ではアートボード内に描画するためにY座標をマイナスにしている。

以前のIllustratorでは新規書類の原点はページ左下だったが、version.CS5 で左上が原点になり、Y座標の向きも下がプラスになった。 ただスクリプトSDKでは以前との互換性のために座標の向きは変更されなかった。 画面で表示されるY座標と逆になるので注意が必要。

reversed について

上の例の引数にある reversed は、アンカーポイントの順番の指定で、NewInscribedCenteredOval では false の場合、描画方向は時計回り。true の場合、反時計回り。開始点は左端のアンカーになる。

NewRect の引数にも reversed があるが、true を指定すると四角が正常に描画されない (2024 SDK Build 532)。 (他では NewCenteredRect も同様。NewPointPointRect では reversed に true を指定可能。)

アンカーの順番は引数の top, left, bottom, right の大小関係によって変えることもできるが、そこまでこだわるなら以下の「任意のパスを描く」の方法で頂点を指定して描いたほうが間違いないかもしれない。


以下の記事は有料です。
他の記事を含めた投げ銭としてもご検討をお願いします。

この続きを読むには
購入して全文を読む

Adobe Illustrator SDK 覚え書き

以下は以前Q*ita に載せていた記事の転載です。古い部分を一部更新または削除しています。


Adobe Illustrator SDK (以下 Ai SDK) について、自分なりにハマったところなどを晒している記事です。きちんと構成すると大変というのと、自分自身もまだ認識不足の点が多々あるので、雑ネタという体裁で追記・更新していく予定です。

以下の内容は現時点での個人的覚え書きであり、勘違いを含む可能性があります。

お気づきの点があればご指摘ください( https://twitter.com/shspage など)。

以下で Ai SDK のバージョン記載がない場合は Illustrator 2020 SDK です。

もくじ

  • SDK の入手
  • 開発環境
  • プラグインの仕組み
  • PIPL
  • Template
  • Suite の遅延読み込み
  • ai::UnicodeString の文字コード指定
  • ツールアイコンの色を自動調整させる
  • ツールカーソルのホットスポット設定
  • 例外処理
  • (Ai 2022 SDK) LiveEffect のサブメニューが表示されない
  • GPUパフォーマンスがONだとデバッグ時にエラーになる
  • (Ai 2024 SDK, Mac) Undefined symbol: _OBJC_CLASS_$_GCContoroller
  • (win, Visual Studio 2017) UTF-8ソースコードをビルドする
  • ImGuiによる設定用ダイアログの作成
  • ...
  • オブジェクト操作編
  • リリース・配布編

SDK の入手 (2024.02.04現在)

こちらから。Adobe Id でのログインが必要。https://www.adobe.io/

Ai SDK の使用許諾は同梱の EULAs.pdf にある。

開発環境

Ai SDK の利用に必要な開発環境と、プラグインの作成からデバッグまでの流れについては SDK 付属の getting-started-guide.pdf で説明されている。 ただ Creating a plug-in in Windows, Creating a plug-in in Mac OS の章については内容が古いので、samplecode を見ながら補足的に参照するのが良いと思う。

docs/references フォルダには関数等のリファレンス(index.chm)がある。 index.chmwindows用のHTMLヘルプファイルだが、検索して調べたりする用途にはたいへん使いやすい。 以前はこれを見るためだけにmacにもVirtualboxwindowsを入れていた。

index.chm を開いたとき空白のページが表示される場合は、index.chm を右クリックして「プロパティ」を開き、 「全般」画面の一番下の「セキュリティ」で「許可する」にチェックを入れる。

プラグインの仕組み

(サンプルコードをビルドできるのが確認できたら、実際どのような処理をしているのかを見ていく段階になると思う。その助けになるか混乱させるかは分からないが、自分なりに理解しているプラグインの仕組みについて少し触れておく。)

プラグインの処理の流れは以下のようになる。

これを踏まえて、プラグインの仕組みについて以下で説明する。

Plugin

プラグインは Plugin という機能の一種(継承クラス)として作成する。 ここでは MyTool という名前にする。 初期化に伴う決まりきった処理は Plugin にあらかじめ用意されているものに任せておき、MyTool では独自の処理の部分を作成することになる。 SDK のサンプルコードでは ~Plugin.cpp で MyTool 独自の処理にあたることを行っている。

イラレからの呼び出しは caller, selector, message で構成されている。

caller は呼び出し元。ツールなら kCallerAITool, メニューなら kCallerAIMenu といった名前で、言わばやりたい機能別の担当者である。

selector は呼び出し理由で、「ユーザーがクリックした」「ドラッグした」といったことである。

message は、担当者別に「やりたいこと」に役立ちそうな情報をセットにしてくれたもので、例えばマウスポインタの位置や、修飾キーの状態が含まれる。

Plugin には、呼び出しを受け取ると callerselector によって決まった名前の関数(例えばドラッグなら ToolMouseDrag )を実行する機能がある。 MyTool で同じ名前の関数を作っておくと(オーバーライド)、呼び出しに応じて実際の処理は MyTool が行うことになる。

プラグインの作成、少なくとも骨組みを作る部分は、この「同じ名前の関数」の中身を書く作業になると思う。 「やりたいこと...をイラレに教えておく」という部分も、Plugin の StartupPlugin という関数をオーバーライドして行う。

Plugin を定義するファイルは samplecode/common フォルダ以下にあり、サンプルコードはこのフォルダを相対パスで参照している。 SDK に付属するテンプレート(プロジェクトの雛形)も同様で、このためプロジェクトのフォルダは samplecode フォルダ直下に置いておく必要がある。

Suite

イラレの様々な機能を実行するために SDK では道具箱的な、関連する関数のセットが用意されており、これを Suite という。

Suite には機能別に数多くの種類がある。MyTool はその中から必要なものを取り込んで使用する。

取り込む処理は Plugin が行ってくれるので、MyTool は取り込みたいものの一覧を作っておけばいい。 サンプルコードの ~Suites.cpp にある gImportSuites がその一覧である。 何やら呪文のように同じような文言が並んでいるが、とりあえずこれはこういうものだと考えておけばいいと思う。~Version などの部分を変えるとプラグインの互換性を保全したりできる場合もあるらしい。

PIPL

Ai 2020 SDK ではビルド時に生成される PIPL(plug-in property list)について、SDK添付の python スクリプトでの生成を推奨している。

このため開発環境にpython (2.7) がなければ導入しておくことが必要。設定方法は getting-started-guide.pdf の p.32 にある。

Template

mac (Ai 2024 SDK)

Ai SDK付属の Xcode プロジェクトのテンプレートを使うには、 samplecode/template/Mac で端末を開き、

$ chmod u+x create_project.sh
$ ./create_project.sh HelloWorld

これで samplecode/HelloWorld フォルダが生成される。

HelloWorld.xcodeproj を開き、ビルドの前に Build Phases の3番目の Run Script にあるコマンドから、 ', {"entry_point" : "PluginMain"}' を削除する。 これがあるとプラグインの初期化が二重に行われるようで、 メニューに追加した項目がダブって表示されたりする。 必要なケースもあるんだろうか。

デバッグする際には、Xcode メニューの Product>Scheme>Edit Scheme... で開いたウィンドウで、Run>Executable にイラレ実行ファイルを設定する。 また、イラレの環境設定で追加プラグインフォルダとして、samplecode/output/mac/debug フォルダを設定しておく(ビルド後に生成される)。

Suite の遅延読み込み

Suite の中には、SartupPlugin で読み込むとエラーになるものがある。 デバッグ時、「プラグインの読み込みエラー」のダイアログも出ずにイラレが落ちる場合は、今のところまずこれを疑っている。

以下は gImportSuites とは別に gPostStartupSuites として、~Suite.cpp に設定する。

  • AICSXSExtensionSuite
  • AIArtConverterSuite

他にもありそうな気がする。あと他の suite との組み合わせによるのかなどは未検証。

gPostStartupSuites を acquire, release する処理は自分で用意しないといけない。 サンプルコードを gPostStartupSuites で検索すると処理例が見つけられる。

サンプルの SnippetRunnerSuites.cpp にも gPost~ の設定があるが、 これは必ずしも gPost~ に設定する必要がないものも含まれている。

ai::UnicodeString の文字コード指定

例えば AIUserSuite の MessageAlert の引数は ai::UnicodeString だが、mac ではエンコーディングを指定しないと文字化けする。

エンコーディングmac では kAIUTF8CharacterEncoding、win では kAIPlatformCharacterEncoding。 kAIPlatform... は既定値なので win では通常は指定が不要。

自分は以下のように環境ごとの値を設定している。

#ifdef MAC_ENV
const static AICharacterEncoding MY_MSG_ENC = kAIUTF8CharacterEncoding;
#else
const static AICharacterEncoding MY_MSG_ENC = kAIPlatformCharacterEncoding; 
#endif
// ...
    sAIUser->MessageAlert(ai::UnicodeString("ハローワールド", MY_MSG_ENC));

ただし win でソースコードUTF-8 にしている場合は kAIUTF8CharacterEncoding を指定する必要がある。

win でソースコードエンコーディングUTF-8 の場合のビルド設定は後述。 (#UTF-8 のソースコードをビルドする)

ツールアイコンの色を自動調整させる

ツールアイコンを SVG にする場合、SVGファイル中で style のクラス名を fill にすると、イラレの UI 背景色に合わせて色を変えてくれる。実例は samplecode 参照。

ツールカーソルのホットスポット設定

SVG (PNG) カーソルのホットスポットXML ファイルで設定できる。 設定しない場合は左上になる。

設定用の XML は Ai 2017 SDK のサンプル Annotator にある。 XML の中に size='32' とあるのはカーソル画像のサイズではなく固定値。 ホットスポットは 32x32 の中での x,y の位置を指定する。

SVG (PNG) と XML の ID は同じにする。

Xcode の Build Phases > Run Script での設定方法も上記サンプル参照。

例外処理

SDKの関数がエラーを返したとき例外を発生させたい場合は、AIErrorThrower クラスが利用できる。使用例はヘッダファイルにもあるが以下のような感じで、関数の実行ごとにエラー処理を書かなくてよいので楽。

#include "AIErrorHandler.h"

AIErr myFunction(){
    AIErrorThrower error = kNoErr;
    error = sAIDocument->RedrawDocument();
    error = kOutOfMemoryErr;  // エラー発生
    error = sAIDocument->Copy();  // 到達しない
    return error;
}

SDK付属のサンプルコードでは aisdk::check_ai_error を使用しているものもある。エラーが返ってきたとき、必ずしも例外を発生させたくない場合などはこちらを使う方法もある。使用するには SDKErrors.cpp をプロジェクトに加えたうえで SDKErrors.h を include する。

メソッド実行のたびにこれを書くとコードが読みにくくなるので、自分は以下のようにマクロにしている。この記事の他の項目でもコード例に CHKERR を用いている。

#include "SDKErrors.h"

#ifndef CHKERR
#define CHKERR aisdk::check_ai_error(error)
#endif

(Ai 2022 SDK) LiveEffect のサブメニューが表示されない

Ai 2022 SDK の AILiveEffectSuite::AddLiveEffectMenuItem では、引数 AddLiveEffectMenuData 構造体に対してメンバ options を設定しないと Ai 2022 のメニューに表示されない。有効な設定値はリファレンス参照。 Ai 2021 SDK でも同メンバ自体はあるが使われていなかった。(リファレンスには Not used の記載がある。)

GPUパフォーマンスがONだとデバッグ時にエラーになる

(2022.05.08 - MacBook Air M1, Ai 2022, Ai 2022 SDK, xcode 13.3.1, macOS Monterey 12.3.1) イラレの設定でGPUパフォーマンスをONにしている場合、プラグインデバッグ中に書類を開いた時点でエラーが発生して処理が停止する。(上記環境以外での挙動は不明。) xcodeのコンソールにはMTLDebugRenderCommandEncoder textureBarrierのassertionエラーとして表示される。 デバッグモード以外での当該プラグインの使用においては支障はないと思われる。 Templateから作成した単純なプラグインでも発生する。 今のところ回避方法は、デバッグ時にはGPUパフォーマンスをOFFにすること。ただしこの場合、GPUパフォーマンスがONの場合の動作検証はxcodeではできないことになる。

(Ai 2024 SDK, Mac) Undefined symbol: _OBJC_CLASS_$_GCContoroller

Ai 2024 SDK で以前のプロジェクトをビルドしようとしたら「Undefined symbol: _OBJC_CLASS_$_GCContoroller」というエラーが出た。Build Phases の Link Binary With Libraries に GameController.framework を追加することで解消された。

(win, Visual Studio 2017) UTF-8ソースコードをビルドする

諸般の事情で Visual StudioソースコードエンコーディングUTF-8 にした場合、ビルドのためにはプロジェクトのプロパティ画面で以下の設定が必要になる。

  • 全般 > 文字セット で、Unicode文字セットを使用する を設定。
  • C/C++コマンドライン > 追加のオプション に、/source-charset:utf-8 /execution-charset:utf-8 を追加する。

ImGuiによる設定用ダイアログの作成

SDK付属のサンプルコードにある「~UI」というフォルダは、「~」のフォルダにあるプラグイン用の設定ダイアログで、HTML拡張機能(エクステンション)で作られている。これは現状、プラグイン用にダイアログを自作する際の公式の解決策になる。

以前の、SDKにダイアログ機能が統合されていた頃(ADM)と比べて、HTMLとJavaScriptがベースなのでとっつきやすいのだが、新たに発生した問題もいろいろとある。

問題としては、まずモーダルダイアログ(ダイアログを閉じるまでメイン処理を待機させる)が作れないこと。 また、プラグイン本体(~.aip)とは別にインストールするので管理が面倒なこと。

このへんを解決したい場合は、C++で使えるUI用ライブラリを物色することになる。 私は現在、ImGui というライブラリを使っている。 これは特にAdobe向けということではない汎用的なもので、ゲーム関連のデバッグ画面によく使われているようだ。

ImGuiのよいところは、

  • サイズが小さい
  • さまざまなOSやバックエンド(DirectX, OpenGL, Metal, etc.)で利用でき、UIデザイン部分のコードはほぼ共通にできる。
  • UIデザイン部分のコードの書き方が直感的でわかりやすい。
  • フリー(MITライセンス)

一方でイラレプラグイン用としての懸案は、

  • macでは Objective-C++ を使う必要がある(研究中)
  • windowsでのモーダルダイアログの実現は力技感がある(研究中)

使い方については、私もまだよくわかっていない部分が多い。 以下の私のgithubリポジトリで使っているので、とりあえずこちらを見て頂くことにしたい。

... つづく


以下は別の日の記事に分岐しました。

オブジェクト操作編

https://shspage.hatenablog.com/entry/2024/02/10/125001

  • 簡単な図形を描く
  • 任意のパスを描く (※ ここから下の記事は有料です)
  • 選択範囲の取得
  • ロックする/不可視にする
  • GetFirstArtOfLayer はレイヤー自身を返す
  • オブジェクトを移動・回転する
  • GetArtBounds は線幅を含む
  • HitTest/HitTestExの検出範囲
  • パスの単純化
  • 座標の計算を楽にする
  • ...

リリース・配布編

https://shspage.hatenablog.com/entry/2024/02/12/040929
(無料記事)