プラグイン開発者ガイド

はじめに

バージョン1.5以降、Sweet Home 3Dに新しい機能を追加することが可能になりました。プラグインファイルは、プラグインフォルダーに配置します。これにより、Javaプログラマーは、現在のバージョンのソースファイルを変更せずに（これは上位互換性にとって良いことです）、またプログラムのフルバージョンを提供せずに（これは配信サイズにとって良いことです）、Sweet Home 3D用の新しい機能を開発および配布できます。
このドキュメントでは、プラグインの作成に必要なツールについて説明し、次に、住宅に追加された可動家具の最大体積を計算するプラグインをプログラミングする方法を示し、最後に、さらに進むのに役立つ追加情報を提供します。

開発ツールのインストール

Sweet Home 3Dが一般的なユーザーを対象としている場合、プラグインの開発には特別なスキルが必要であり、さらに進む前に、IDEを使用してJavaでプログラミングする方法を知っておく必要があります。このガイドでは、Eclipseでプラグインを構築する方法を示しますが、任意のIDEを使用することも、IDEをまったく使用しないこともできます。

Eclipseのダウンロードとインストール

まず、https://www.eclipse.org/からEclipseをダウンロードします。Eclipse IDE for Java Developersという名前のバージョンは、プラグインを開発するのに十分ですが、Java開発用の任意のバージョンをダウンロードできます。
ダウンロードしたら、Eclipseのインストールは非常に簡単です。取得するアーカイブを解凍し、eclipseフォルダーを開き、システムに応じて、次の名前のファイルを実行します。 eclipse.exe （Windowsの場合） eclipse.app （Mac OS Xの場合） eclipse （Linuxの場合）。
最初の実行時に、Eclipseはワークスペースフォルダーを選択するように要求します。ここにプラグインプロジェクトが保存されます。
完了したら、メニューからファイル > 新規 > プロジェクトを選択して新しいプロジェクトを作成し、表示される新規プロジェクトウィザードでJava > Javaプロジェクトを選択し、プロジェクト名としてVolumePluginを入力して、完了ボタンをクリックします。最後に、図1に示すように、ようこそタブを閉じて、ワークスペースを確認します。

Sweet Home 3Dライブラリのダウンロードとインストール

プラグインの開発は、Eclipseがプロジェクトを構築できるように、Sweet Home 3Dのいくつかのクラスに基づいています。Sweet Home 3DクラスをEclipseに追加する最も簡単な方法は、https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/downloadで入手できるSweet Home 3DのJAR実行可能バージョンをダウンロードすることです。ダウンロードしたら、ファイルSweetHome3D-7.5.jarをEclipseのパッケージエクスプローラービューのVolumePluginプロジェクトアイコンにドラッグアンドドロップし、図2に示すように、SweetHome3D-7.5.jarファイルのコンテキストメニューでビルドパス > ビルドパスに追加アイテムを選択します。

プラグインのプログラミング

必要なツールをインストールしたので、Sweet Home 3D用の最初のプラグインをプログラミングする方法を見てみましょう。

プラグインクラスの作成

まず、Eclipseでファイル > 新規 > クラスメニュー項目を選択して、com.eteks.sweethome3d.plugin.Pluginの新しいサブクラスを作成します。

新規Javaクラスダイアログで、クラス名としてVolumePluginを入力し、パッケージを入力し（ここで選択したパッケージはcom.eteks.test）、VolumePluginのスーパークラスとしてcom.eteks.sweethome3d.plugin.Pluginを選択します。完了したら、完了をクリックします。Eclipseは、次の内容で新しいクラスのファイルを作成します。

package com.eteks.test;
import com.eteks.sweethome3d.plugin.Plugin;
import com.eteks.sweethome3d.plugin.PluginAction;
public class VolumePlugin extends Plugin {
 @Override
 public PluginAction[] getActions() {
 // TODO Auto-generated method stub
 return null;
 }
}

TODOコメントから推測できるように、可動家具の体積を計算できるプラグインアクションを返すように、getActionsメソッドの実装を変更する必要があります。return null;を次のステートメントに置き換えます。

  return new PluginAction [] {new VolumeAction()};

Eclipseメニューからエディション > クイックフィックスを選択して、図4に示すように、欠落しているクラスVolumeActionを作成します。

表示される新規Javaクラスダイアログで、外側の型チェックボックスを選択してVolumePluginの内部クラスを作成し、完了をクリックします。これにより、com.eteks.sweethome3d.plugin.PluginActionクラスから継承し、空のexecuteメソッドを含むクラスVolumeActionが作成されます。

  public class VolumeAction extends PluginAction {
 @Override
 public void execute() {
 // TODO Auto-generated method stub
 }
 }

このメソッドは、ユーザーがプラグインアクションを起動したときにSweet Home 3Dが呼び出すメソッドです。したがって、家具の体積を計算して表示する方法を実装する必要があります。

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Compute the sum of the volume of the bounding box of 
 // each movable piece of furniture in home
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Display the result in a message box (³ is for 3 in supercript)
 String message = String. format(
 "The maximum volume of the movable furniture in home is %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

プラグインに実行させたいことを指定したので、ユーザーがこの新しいアクションを起動する方法を記述する必要があります。メニューに新しいメニュー項目を追加するか、ツールバーに新しいボタンを追加するかを選択できます。この選択は、プラグインアクションの作成時に適切なプロパティを設定することによって行われます。たとえば、ユーザーがツールメニューにあるメニュー項目体積を計算を使用して体積アクションを起動するようにする場合は、次のコンストラクターをVolumnActionクラスに追加します。

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Compute volume");
           putPropertyValue(Property.MENU, "Tools");
 // Enables the action by default
           setEnabled(true);
 }

VolumePluginプラグインクラスがプログラムされ、Sweet Home 3Dでプラグインとして動作する準備がほぼ整いました。最後にやるべきことは2つあります。

ApplicationPlugin.properties記述ファイルの作成
JARファイルへのファイルのまとめ。

プラグイン記述ファイルの作成

ApplicationPlugin.propertiesファイルは、プラグイン名、そのクラス、サポートされているSweet Home 3DおよびJavaの最小バージョン、および法的情報について記述します。Eclipseメニューからファイル > 新規 > ファイルを選択し、ファイル名ApplicationPlugin.propertiesを入力して、図5に示すように完了をクリックします。

次に、新しいファイルに次の説明を入力して保存します。

name=可動家具の体積
class=com.eteks.test.VolumePlugin
description=住宅内の可動家具の体積を計算します
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

プラグインJARの作成

プラグインJARには、VolumePlugin.javaファイルのコンパイルから作成されたclassファイル、およびApplicationPlugin.propertiesファイルが含まれています。EclipseはJavaファイルを保存するとすぐにコンパイルするため、メニューからファイル > エクスポート…を選択し、表示されるエクスポートダイアログでJava > JARファイルを選択するだけです。Jarエクスポートウィザードが図6に示すように表示されたら、プロジェクトチェックボックスを選択し、Sweet Home 3Dプラグインフォルダーに配置されたJARファイルのパスを入力します。この適切なフォルダーは、次のようにシステムによって異なります。

Windows Vista / 7 / 8 / 10 / 11では、このフォルダーはC:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\pluginsです。
Windows XPおよび以前のバージョンのWindowsでは、このフォルダーはC:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\pluginsです。
macOSでは、これはユーザーフォルダーのサブフォルダーLibrary/Application Support/eTeks/Sweet Home 3D/pluginsです。
Linuxおよびその他のUnixでは、これはユーザーフォルダーのサブフォルダー.eteks/sweethome3d/pluginsです。

プラグインのテスト

開発したプラグインは、Java Web Startバージョン、インストーラーバージョン、または以前にダウンロードしたSweetHome3D-7.5.jarのいずれかでSweet Home 3Dで実行されます。最新のものは実行可能なJARであるため、ダブルクリックするか、次のコマンドで実行できます。

java -jar /path/to/SweetHome3D-7.5.jar

テスト中は、プラグインの実行中にスローされた例外のスタックトレースをコンソールで読み取ることができるように、このコマンドでSweet Home 3Dを実行することをお勧めします。

Sweet Home 3Dが起動すると、図7に示すように、新しいメニューとその項目が表示されます。

図7. プラグインメニュー

ユーザーガイドで作成されたホームの例の新しいメニュー項目を選択すると、次の結果が得られます。

プラグインのデバッグ

Eclipseからプラグインをデバッグする必要がある場合は、次の手順に従ってデバッグ構成を作成します。

メニューから実行 > デバッグ構成…を選択し、 デバッグ構成ダイアログボックスの使用可能な構成リストでJavaアプリケーション項目を選択し、左上の新規ボタンをクリックして、構成の名前を入力します。
メインクラステキストフィールドの右側にある検索…ボタンをクリックし、提案されたクラスの中からSweetHome3DBootstrapクラスをダブルクリックします。

クラスパスタブをクリックし、クラスパスリストのユーザーエントリ項目のVolumePlugin（デフォルトクラスパス）サブ項目を選択し、削除ボタンをクリックします。
クラスパスリストのユーザーエントリ項目をクリックし、JARの追加…ボタンをクリックし、SweetHome3D-7.5.jar項目を選択して、選択を確定します。

ソースタブを選択し、追加…ボタンをクリックし、ソースの追加ダイアログボックスのJavaプロジェクト項目をダブルクリックし、プロジェクトの選択ポップアップのVolumePlugin項目を選択して、選択を確定します。

最後に、デバッグボタンをクリックして、デバッグモードでSweet Home 3Dを起動します。プログラムが実行されたら、VolumePlugin.javaファイルを開き、 executeメソッドにブレークポイントを設定し、Sweet Home 3Dメニューからツール > 体積を計算を選択します。Eclipseは、選択したブレークポイントで停止し、プログラムをステップごとに実行して、変数の値を検査できるようにします。

プラグインのソースコードを変更するたびに、作成したデバッグ構成を起動する前に、プラグインJARを生成することを忘れないでください。eclipseでJARエクスポートプロセスを高速化するには、JARエクスポートウィザードの2番目のステップに進み、このJARの説明をワークスペースに保存するオプションを選択します。これにより、コンテキストJARの作成メニュー項目を持つ新しい項目がプロジェクトに追加されます。

プラグインのデプロイ

準備ができたら、プラグインフォルダーにコピーするだけで、他のSweet Home 3Dユーザーのコンピューターにプラグインをデプロイできます。バージョン1.6以降では、拡張子がSH3Pの場合、プラグインファイルをダブルクリックしてSweet Home 3Dのプラグインフォルダーにインストールすることもできます（ファイル拡張子を.zipから.sh3pに変更するだけです）。.sh3pファイルをダブルクリックしてもSweet Home 3Dが起動しない場合は（Linuxではほとんどの場合）、ターミナルウィンドウで次のコマンドを使用してプラグインをインストールすることもできます（ここでSweetHome3DはSweet Home 3Dインストーラーで提供される実行可能ファイルの名前です）。

/path/to/SweetHome3D /path/to/plugin.sh3p

プラグインの使用を停止するには、プラグインフォルダーからファイルを削除して、Sweet Home 3Dを再起動します。

このWebサイトで入手可能なすべてのSweet Home 3Dインストーラーでプラグインを実行できるようにする場合は、Eclipseのプロジェクト > プロパティメニュー項目で表示されるダイアログボックスのJavaコンパイラーセクションで使用可能なフィールドコンパイラー準拠レベルで1.5を選択して、Java 5との互換性を維持するように注意してください。
Java 1.5互換性が利用できなくなったJavaコンパイラーバージョンを使用する場合は、少なくともSweet Home 3Dの最新バージョンで使用されているJava 1.8をターゲットにし、それに応じてプラグインのApplicationPlugin.propertiesファイルでjavaMinimumVersionを設定してみてください。

さらに進む

最初のプラグインのプログラミングでは、全体像を示しました。さらに進むのに役立つ追加情報を次に示します。

Sweet Home 3D API – Javadoc

新しいプラグインを開発する上で最も役立つドキュメントは、javadocツールで生成されたSweet Home 3D API（アプリケーションプログラミングインターフェース）です。
Sweet Home 3Dの将来のバージョンとの上位互換性を維持したい場合は、プラグイン内でcom.eteks.sweethome3d.plugin、com.eteks.sweethome3d.model、com.eteks.sweethome3d.tools、com.eteks.sweethome3d.viewcontrollerパッケージのクラスのみを使用してください。これにより、Sweet Home 3Dで利用可能なホームデータ上で動作するあらゆるプラグインをプログラミングするのに十分な機能が提供されます。
プログラムの他のレイヤーに一致するパッケージは、情報提供のみを目的としてJavadocに含まれています。これらのAPIに依存しないでください。上位互換性の保証なしに将来変更される可能性があります（いずれにしても、上記のパッケージでは、com.eteks.sweethome3d.swing、com.eteks.sweethome3d.j3d、com.eteks.sweethome3d.io、またはcom.eteks.sweethome3dパッケージのクラスへの参照は表示されません）。

モデルクラスのアーキテクチャ

Sweet Home 3DはMVC（モデル・ビュー・コントローラー）アーキテクチャに基づいているため、そのモデルレイヤーがどのように構成されているかを理解することが不可欠です。図13（PDF形式でも入手可能）は、このモデルレイヤーに一致するcom.eteks.sweethome3d.modelパッケージのバージョン1.5で利用可能なほぼすべてのクラスとインターフェースを示しています。

[uml_diagram slug=”model-classes-diagram” map_name=”model-classes-diagram” caption=”Figure 13. UML diagram of com.eteks.sweethome3d.model package” caption_small=”(click on a class to view its javadoc)”]

モデルレイヤーの中心となるクラスは、HomeApplicationクラス（10）であり、SweetHome3Dアプリケーションのメインクラスの抽象スーパークラスです。このクラスのインスタンスは、現在編集中のHomeインスタンス（7）と、使用中の長さの単位（12）、家具カタログ（14）、およびユーザーが家具（17）とテクスチャ（18）を選択するテクスチャカタログ（15）を格納するUserPreferencesオブジェクト（11）へのアクセスを提供します。
Homeインスタンス（7）は、ユーザーがホームプランで作成したすべてのオブジェクトを格納します。

PieceOfFurnitureインターフェース（16）を実装するHomePieceOfFurnitureオブジェクト（13）のリスト。
Wallオブジェクト（9）のコレクション。
Roomオブジェクト（5）のリスト。
DimensionLineオブジェクト（2）のコレクション。
Labelオブジェクト（3）のコレクション。

これらのオブジェクトは、Selectableインターフェース（1）と、バーチャルビジターモードでカメラの位置を格納するObserverCameraオブジェクト（4）を実装します。家具（16）のアイコンや3Dモデル、またはテクスチャ（20）の画像など、モデルオブジェクトによって管理されるすべての外部情報には、URLContentクラスとcom.eteks.sweethome3d.toolsパッケージの他のクラスによって実装されるContentインターフェース（19）を介してアクセスされます。

このUML図は、Sweet Home 3Dモデルでどのクラスが利用可能で、それらにどのようにアクセスできるかを理解するのに役立つはずですが、コンストラクターもミューテーター（またはセッター）も記載されていないことに気づくでしょう。これは単にスペースが不足しているためですが、プラグインクラスで問題なく使用できます。また、モデルの既存のオブジェクトに対する変更は、PropertyChangeEvent、CollectionEvent（8）、またはSelectionEvent（6）によって表示されるコンポーネントに通知されるため、すべての変更が画面に即座に反映されます。

プラグインクラスのアーキテクチャ

プラグインクラスのアーキテクチャは、モデルレイヤーのものよりもはるかに理解しやすいです。com.eteks.sweethome3d.pluginパッケージには3つのクラスしか含まれておらず、そのうち図14（PDF形式でも入手可能）に示すように、PluginクラスとPluginActionクラスのみを使用することになっています。

[uml_diagram slug=”plugin-classes-diagram” map_name=”plugin-classes-diagram” caption=”Figure 14. UML diagram of com.eteks.sweethome3d.plugin package” caption_small=”(click on a class to view its javadoc)”]

PluginManagerインスタンス（1）は、アプリケーションの起動時に作成され、ユーザーのプラグインフォルダーにインストールされているプラグインを検索します。新しいホームが編集されるたびに、このマネージャーは、起動時に見つかった各プラグインに対してPluginオブジェクト（3）をインスタンス化して構成します。次に、getActionsメソッドを呼び出して、ホームウィンドウのメニュー項目やツールバーボタンとして追加されるすべてのアクション（4）を取得します。各アクションはPluginActionのインスタンスであり、Actionクラスのように、そのexecuteメソッドとその変更可能なプロパティ（2）を持っています。

Pluginクラスは、そのgetUndoableEditSupportメソッドを介してUndoableEditSupportインスタンスへのアクセスを提供することに注意してください。PluginActionインスタンスのexecuteメソッドでホームまたはそのオブジェクト（家具、壁など）を変更する場合は、getUndoableEditSupportメソッドによって返されるアンドゥ可能な編集サポートにUndoableEditオブジェクトもポストする必要があります。そうしないと、ユーザーは行った変更を正しく元に戻したり、やり直したりすることができません。

ローカリゼーション

Sweet Home 3Dユーザーコミュニティ向けのプラグインを開発する場合は、アクション名やメニュー、または作成するダイアログに表示される文字列をローカライズするか（少なくともローカライズを準備してください）。2つのPluginActionのコンストラクタークラスは、.propertiesファイルを使用したアクションプロパティの翻訳を整理するのに役立ちます。また、プラグインで他の文字列（テスト済みプラグインによって表示されるダイアログの文字列など）を翻訳する必要がある場合は、ResourceBundle Javaクラスでこれらの.propertiesファイルを再利用してください。
プロパティファイルの数を制限する場合は、プラグインのApplicationPlugin.properties 記述ファイルにアクションプロパティと他の文字列の値を記述することもできます。

このアーキテクチャを使用する例が必要な場合は、https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3pで入手可能なSH3Fへのエクスポートプラグインをダウンロードして解凍してください（このプラグインファイルには、プラグインのソースコードも含まれています）。
ヘルプフォーラムで説明されているように、このプラグインは、Sweet Home 3Dの家具カタログにインポートしたすべての家具を含むSH3Fファイルを作成します。

プラグインの投稿

プログラムしたプラグインをプラグインの投稿トラッキングシステムに投稿して、Sweet Home 3Dユーザーコミュニティと共有できます。
インポーターからエクスポーターまで、プラグインのおかげで多くの機能がSweet Home 3Dに追加できますが、Michel Mbemによって開発されたHome Rotatorプラグインや、Hans Dirkseによって書かれたプラグインと拡張機能のチュートリアル（PDF）およびプラグインとツールページにリストされている他のプラグインのように、ホームのデータを変更できるプラグインも追加できます。