プラグイン開発者ガイド

はじめに
開発ツールのインストール
プラグインのプログラミング
さらに進む

はじめに

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

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

Sweet Home 3Dは一般ユーザーを対象としていますが、プラグインの開発には特別なスキルが必要で、先に進む前にJavaをIDEでプログラミングする方法を知っている必要があります。このガイドでは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はプラグインプロジェクトが保存されるワークスペースフォルダの選択を求めます。
完了後、メニューからFile > New > Projectを選択して新しいプロジェクトを作成し、表示されるNew projectウィザードでJava > Java projectを選択し、プロジェクト名としてVolumePluginと入力し、Finishボタンをクリックしてください。最後に、Welcomeタブを閉じて、図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のPackage ExplorerビューのVolumePluginプロジェクトアイコンにドラッグアンドドロップし、図2に示すように、SweetHome3D-7.5.jarファイルのコンテキストメニューでBuild Path > Add to Build Path項目を選択してください。

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

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

プラグインクラスの作成

まず、EclipseでFile > New > Classメニュー項目を選択して、com.eteks.sweethome3d.plugin.Pluginの新しいサブクラスを作成してください。

New Java Classダイアログで、クラス名としてVolumePluginと入力し、パッケージを入力し（ここではcom.eteks.testパッケージが選択されました）、VolumePluginのスーパークラスとしてcom.eteks.sweethome3d.plugin.Pluginを選択してください。完了後、Finishをクリックしてください。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()};

図4に示すように、EclipseメニューからEdition > Quick Fixを選択して、不足しているクラスVolumeActionを作成してください。

表示されるNew Java Classダイアログで、Enclosing typeチェックボックスを選択してVolumePluginの内部クラスを作成し、Finishをクリックしてください。これにより、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);
  }
  }

プラグインに何をさせたいかを指定したので、ユーザーがこの新しいアクションを起動する方法を記述する必要があります。メニューに新しいメニュー項目を追加するか、ツールバーに新しいボタンを追加するかを選択できます。この選択は、プラグインアクションの作成時に適切なプロパティを設定することで行われます。例えば、ユーザーがToolsメニューにあるCompute volumeメニュー項目で体積アクションを起動したい場合、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メニューからFile > New > Fileを選択し、ファイル名ApplicationPlugin.propertiesを入力し、図5に示すようにFinishをクリックしてください。

次に、新しいファイルに以下の記述を入力して保存してください：

name=Movable furniture volume
class=com.eteks.test.VolumePlugin
description=Computes the volume of the movable furniture in home
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

プラグインJARの作成

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

Windows Vista / 7 / 8 / 10 / 11では、このフォルダはC:UsersuserAppDataRoamingeTeksSweet Home 3Dpluginsです、
Windows XPおよび以前のバージョンのWindowsでは、このフォルダはC:Documents and SettingsuserApplication DataeTeksSweet Home 3Dpluginsです、
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からプラグインをデバッグする必要がある場合は、次の手順に従ってデバッグ構成を作成してください：

メニューからRun > Debug Configurations…を選択し、 Debug configurationsダイアログボックスの利用可能な構成リストでJava Application項目を選択し、左上のNew ボタンをクリックして構成の名前を入力してください。
Main classテキストフィールドの右側にあるSearch…ボタンをクリックし、提案されたクラスの中からSweetHome3DBootstrapクラス
をダブルクリックしてください。

Classpathタブをクリックし、ClasspathリストのUser Entries項目のVolumePlugin (default classpath)サブ項目を選択し、Removeボタンをクリックしてください。
Classpathリストの User Entries項目をクリックし、Add JARs…ボタンをクリックし、SweetHome3D-7.5.jar項目を選択して選択を確認してください。

Sourceタブを選択し、Add…ボタンをクリックし、Add SourceダイアログボックスのJava Project項目をダブルクリックし、Project SelectionポップアップでVolumePlugin項目を選択して選択を確認してください。

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

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

プラグインの配布

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

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

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

プラグインがこのWebサイトで利用可能なすべてのSweet Home 3Dインストーラーで実行できるようにしたい場合は、EclipseのProject > Propertiesメニュー項目で表示されるダイアログボックスのJava Compilerセクションで利用可能なCompiler compliance levelフィールドで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（Model View Controller）アーキテクチャに基づいており、そのモデル層がどのように構成されているかを理解することが不可欠です。図13（PDF形式でも利用可能）は、このモデル層に一致するcom.eteks.sweethome3d.modelパッケージのバージョン1.5で利用可能なほとんどすべてのクラスとインターフェースを示しています。

UML Diagram model-classes-diagram — *Figure 13. UML diagram of com.eteks.sweethome3d.model package*
*(click on a class to view its javadoc)*

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

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

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

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

Sweet Home 3Dモデルは、パフォーマンス上の理由からスレッドセーフではありません。モデルに属するオブジェクトのすべての変更は、イベントディスパッチスレッドで行う必要があります。

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

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

UML Diagram plugin-classes-diagram — *Figure 14. UML diagram of com.eteks.sweethome3d.plugin package*
*(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ユーザーコミュニティ向けにプラグインを開発する予定がある場合は、アクション名やメニュー、または作成するダイアログに表示される文字列をローカライズする（または少なくともローカライズの準備をする）ようにしてください。PluginActionクラスの2つのコンストラクタは、.propertiesファイルを使用してアクションプロパティの翻訳を整理するのに役立ちます。プラグイン内の他の文字列（テスト済みプラグインによって表示されるダイアログ内のものなど）を翻訳する必要がある場合は、これらの.propertiesファイルをResourceBundle Javaクラスで再利用してください。
プロパティファイルの数を制限したい場合は、アクションプロパティの値やその他の文字列をプラグインのApplicationPlugin.properties 記述ファイルに記述することもできます。

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

プラグインの貢献

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


© Copyright 2025 Space Mushrooms - All rights reserved