Sweet Home 3D is a free interior design application that helps you place your furniture on a house 2D plan, with a 3D preview.Available at http://www.sweethome3d.com/, this program is aimed at people who want to design their interior quickly, whether they are moving or they just want to redesign their existing home.
Numerous visual guides help you draw the plan of your home and layout furniture. You may draw the walls of your rooms upon the image of an existing plan, and then, drag and drop furniture onto the plan from a catalog organized by categories. Each change in the 2D plan is simultaneously updated in the 3D view, to show you a realistic rendering of your layout.
Introduction
From version 1.5, it's possible to add new features to Sweet Home 3D with plug-in files placed in your plug-ins folder. This allows Java programmers to develop and distribute new features for Sweet Home 3D without modifying the source files of the current version (which is good for upward compatibility), and without delivering a full version of the program (which is good for delivery size).
This document describes the tools required to create plug-ins, then shows how to program a plug-in that computes the maximum volume of the movable furniture added to a home, and finally gives some additional information that will help you to go further.
Installing development tools
If Sweet Home 3D targets a general audience, developing plug-ins requires special skills, and you should know how to program in Java with an IDE, before going further. This guide shows how to build a plug-in with Eclipse, but you can use the IDE of your choice, or no IDE at all.
Download and install Eclipse
First download Eclipse from http://www.eclipse.org/. The version named Eclipse IDE for Java Developers is enough to develop a plug-in, but you can download any version for Java development.
Once downloaded, installing Eclipse is very simple: just uncompress the archive you'll get, open the eclipse folder and depending on your system, run the file namedeclipse.exe(under Windows),eclipse.app(under Mac OS X) oreclipse(under Linux).
At the first run, Eclipse will require you to choose a workspace folder, where will be stored plug-in projects.
Once done, choose File > New > Project out of the menu to create a new project, select Java > Java project in the New project wizard that will be displayed, enter VolumePlugin as project name and click on Finish button. Finally, close the Welcome tab to discover your workspace as shown in figure 1.
Figure 1. Eclipse workspaceDownload and install Sweet Home 3D library
The development of a plug-in is based on some classes of Sweet Home 3D that Eclipse must know to be able to build your project. The easiest way to add Sweet Home 3D classes to Eclipse is to download the JAR executable version of Sweet Home 3D available at http://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-4.0/SweetHome3D-4.0.jar/download. Once downloaded, drag and drop the file SweetHome3D-4.0.jar on the VolumePlugin project icon in the Package Explorer view of Eclipse, and choose the item Build Path > Add to Build Path in the contextual menu of SweetHome3D-4.0.jar file, as shown in figure 2.
Figure 2. Adding SweetHome3D-4.0.jar to Build Path
Programming a plug-in
Now that you installed the required tools, let's see how you can program your first plug-in for Sweet Home 3D.
Creating the plug-in class
First, create a new subclass of com.eteks.sweethome3d.plugin.Plugin by choosing File > New > Class menu item in Eclipse.
Figure 3. Creating a new class
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; } }
As you can guess from the TODO comment, you must now change the implementation of the getActions method to return a plug-in action able to compute the volume of the movable furniture. Replace return null; by the following statement:
return new PluginAction [] {new VolumeAction()};
and choose Edition > Quick Fix out of Eclipse menu to create the missing class VolumeAction, as shown in figure 4.
Figure 4. Using Quick fix to generate a missing class
In the New Java Class dialog that appears, select the Enclosing type check box to create an inner class of VolumePlugin and click on Finish. This will create the class VolumeAction that inherits from com.eteks.sweethome3d.plugin.PluginAction class and contains an empty execute method:
public class VolumeAction extends PluginAction { @Override public void execute() { // TODO Auto-generated method stub } }
This method is the one that Sweet Home 3D will call when the user will launch the plug-in action ; thus this is the place where you must implement how to compute the volume of the furniture and display it:
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 (\u00b3 is for 3 in supercript) String message = String.format( "The maximum volume of the movable furniture in home is %.2f m\u00b3.", volumeInCm3 / 1000000); JOptionPane.showMessageDialog(null, message); } }
Now that you specified what you want the plug-in to do, you must describe how the user will launch this new action. You have the choice between adding a new menu item to a menu, and/or a new button to the tools bar. This choice is done by setting the appropriate properties of the plug-in action at its creation. For example, if you want the users to launch the volume action with the menu item Compute volume found in the Tools menu, you'll add the following constructor to VolumnAction class:
public VolumeAction() { putPropertyValue(Property.NAME, "Compute volume"); putPropertyValue(Property.MENU, "Tools"); // Enables the action by default setEnabled(true); }
The VolumePlugin plug-in class is now programmed, and almost ready to work as a plug-in in Sweet Home 3D. The two last things to do are:
- creating an ApplicationPlugin.properties description file,
- putting the files together in a JAR file.
Creating the plug-in description file
An ApplicationPlugin.properties file describes the plug-in name, its class, the Sweet Home 3D and Java minimum versions under which it is supported, and legal stuff. Choose File > New > File from Eclipse menu, enter the file name ApplicationPlugin.properties and click on Finish, as shown in figure 5.
Figure 5. Creating a new file
Then enter the following description in the new file and save it:
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 2008 eTeks applicationMinimumVersion=1.5 javaMinimumVersion=1.5Creating the plug-in JAR
The plug-in JAR contains the class files created from the compilation of the VolumePlugin.java file, and the ApplicationPlugin.properties file. As Eclipse compiles a Java file as soon as you save it, you just have to choose File > Export... from the menu and select Java > JAR file in the Export dialog that will be displayed. In the Jar Export wizard that appears as shown in figure 6, select the project check box and enter the path of a JAR file placed in the Sweet Home 3D plug-ins folder. This appropriate folder depends on your system as follows:
- under Windows Vista / 7 / 8, this folder is C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
- under Windows XP and previous versions of Windows, this folder is C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins,
- under Mac OS X, it's the subfolder Library/Application Support/eTeks/Sweet Home 3D/plugins of your user folder,
- under Linux and other Unix, it's the subfolder .eteks/sweethome3d/plugins of your user folder.
Figure 6. Exporting to a JAR file
Testing the plug-in
The plug-in you developed will run in Sweet Home 3D, either with the Java Web Start version, the installers version, or the SweetHome3D-4.0.jar you downloaded previously. As the latest one is an executable JAR, you can run it by double-clicking on it or with the following command:
java -jar /path/to/SweetHome3D-4.0.jar
As long as you're testing, you will probably prefer to run Sweet Home 3D with this command, to be able to read in the console the stack trace of the exceptions thrown during the execution of your plug-in.
Once Sweet Home 3D is launched, you'll see the new menu and its item appear as shown in figure 7:
Figure 7. Plug-in menu
If you choose the new menu item for the home example created in user's guide, you'll get the following result:
Figure 8. Plug-in in action
Debugging the plug-in
If you need to debug your plug-in from Eclipse, create a debug configuration by following these steps:
- Choose Run > Debug Configurations... from the menu, select Java Application item in the available configurations list of the Debug configurations dialog box, click on the New button at the top left and enter a name for the configuration.
- Click on the Search... button at the right of the Main class text field and double click on the SweetHome3DBootstrap class among the proposed classes.
Figure 9. Creating a debug configuration
- Click on the Classpath tab, select the VolumePlugin (default classpath) sub item of the User Entries item in the Classpath list and click on the Remove button.
- Click on the User Entries item in the Classpath list, click on the Add JARs... button, select SweetHome3D-4.0.jar item and confirm your choice.
Figure 10. Setting the classpath of the debug configuration
- Select the Source tab, click on the Add... button, double click on the Java Project item in the Add Source dialog box, select the VolumePlugin item in the Project Selection popup and confirm your choice.
Figure 11. Setting the source path of the debug configuration
- Finally, click on the Debug button to launch Sweet Home 3D in debug mode. Once the program is running, open the VolumePlugin.java file, set a breakpoint in the execute method and choose Tools > Compute volume from Sweet Home 3D menu. Eclipse will stop on the selected breakpoint to let you execute the program step by step and inspect variables value.
Figure 12. Eclipse debug perspective
Each time you modify the source code of your plug-in, don't forget to generate the plug-in JAR before launching the debug configuration you created. To speed up the JAR export process in eclipse, go to the second step of the JAR export wizard and select the option Save the description of this JAR in the workspace. This will add a new item in the project with a contextual Create JAR menu item.
Deploying the plug-in
Once ready, your plug-in may be deployed on the computer of other Sweet Home 3D users by simply copying it in their plug-ins folder. From version 1.6, a plug-in file may be also installed in the plug-ins folder of Sweet Home 3D by double-clicking on it, if its extension is SH3P (simply change the file extension from .zip to .sh3p). This may not work under Linux.
To stop using a plug-in, remove its file from the plug-ins folder and relaunch Sweet Home 3D.
Installing/uninstalling a plug-in by copying it in Sweet Home 3D plug-ins folder isn't very user-friendly. This will be probably improved In future versions of Sweet Home 3D with a pane dedicated to the management of plug-ins.
Going further
The programming of the first plug-in showed you the big picture. Here's some additional information that will help you to go further.
Sweet Home 3D API - Javadoc
The most useful documentation to develop a new plug-in is the Sweet Home 3D API (Application Programming Interface), generated with javadoc tool.
Use only the classes of com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools and com.eteks.sweethome3d.viewcontroller packages in your plug-in if you want it to be upward compatible with future versions of Sweet Home 3D. This will be largely enough to program any plug-in that works on the home data available in Sweet Home 3D.
The packages matching the other layers of the program are included in the Javadoc for information purpose only. Don't rely on their API, as it may still change in the future with no guarantee of upward compatibility (anyway you'll see no reference to a class of com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io or com.eteks.sweethome3d packages in the aforementioned packages).
Model classes architecture
Sweet Home 3D is based on a MVC (Model View Controller) architecture, so understanding how is organized its Model layer is essential. The figure 13 (available also at PDF format) presents almost all the classes and interfaces available in the version 1.5 of com.eteks.sweethome3d.model package that matches this Model layer.
Figure 13. UML diagram of com.eteks.sweethome3d.model package
(click on a class to view its javadoc)
The central class in the Model layer is the HomeApplication class (10), the abstract super class of SweetHome3D application main class. The instance of this class gives access to the Home instances (7) currently edited, and to the UserPreferences object (11) that stores the length unit in use (12), the furniture catalog (14) and the textures catalog (15) from which the user chooses pieces of furniture (17) and textures (18).
A Home instance (7) stores all the objects the user created in the home plan:
These objects implement the Selectable interface (1) as well as the ObserverCamera object (4), that stores the location of the camera in the Virtual visitor mode. All the external information managed by Model objects, like the icon and the 3D model of a piece of furniture (16), or the image of a texture (20) is accessed through the Content interface (19), implemented by the URLContent class and other classes of the com.eteks.sweethome3d.tools package.
- the list of HomePieceOfFurniture objects (13) which implement the interface PieceOfFurniture (16),
- the collection of Wall objects (9),
- the list of Room objects (5),
- the collection of DimensionLine objects (2),
- the collection of Label objects (3).
This UML diagram should help you understand which classes are available in the Sweet Home 3D model and how you can access to them, but you'll probably notice that no constructors and no mutators (or setters if you prefer) are cited in it. It's just by lack of room but you can use them with no problem in a plug-in class. Note also that any modification of an existing object of the model will be notified to the displayed components either with PropertyChangeEvents, with CollectionEvents (8) or with SelectionEvents (6), thus allowing all changes to be reflected immediately on screen.
Sweet Home 3D model isn't thread safe for performance reasons. All modifications of an object belonging to the model should be done in the Event Dispatch Thread.
Plug-in classes architecture
The architecture of plug-in classes is much more simple to understand than the Model layer's one. The com.eteks.sweethome3d.plugin package contains only three classes among which you're supposed to use only Plugin and PluginAction classes, as shown in figure 14 (also available at PDF format).
Figure 14. UML diagram of com.eteks.sweethome3d.plugin package
(click on a class to view its javadoc)
A PluginManager instance (1) is created at application launch and searchs the plug-ins installed in user's plug-ins folder. Each time a new home is edited, this manager instanciates and configures a Plugin object (3) for each plug-in found at launch time. Then, it calls the getActions method to retrieve all the actions (4) that will be added as menu items and/or tool bar buttons in the home window. Each action is an instance of PluginAction, which looks like Action class, with its execute method and its modifiable properties (2).
Note that the Plugin class gives you access to an UndoableEditSupport instance through its getUndoableEditSupport method. As soon as you modify a home or its objects (furniture, walls...) in the execute method of a PluginAction instance, you should also post an UndoableEdit object to the undoable edit support returned by getUndoableEditSupport method, otherwise users won't be able to undo/redo correctly the changes you made.
Localization
If you plan to develop a plug-in for Sweet Home 3D users community, try to localize the strings it displays either in actions name and menu or in dialogs you'll create (or at least prepare its localization). Two constructors of the PluginAction class will help you to organize the translation of actions properties with .properties files, and if you need to translate other strings in your plug-in (like the one in the dialog shown by the tested plug-in) reuse these .properties files with ResourceBundle Java class.
If you prefer to limit the number of properties files, you might even write the values of the action properties and other strings in the ApplicationPlugin.properties description file of your plug-in.
If you want an example that uses this architecture, download the Export to SH3F plug-in available at http://sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, and unzip it (this plug-in file contains also the source code of the plug-in).
As described in Help forum, this plug-in creates a SH3F file that contains all the furniture you imported in the furniture catalog of Sweet Home 3D.
Contributing plug-ins
You can post the plug-ins you programmed in Plug-ins Contributions Tracking System to share them with Sweet Home 3D users community.
Many features can be added to Sweet Home 3D thanks to plug-ins, from importers to exporters, but also plug-ins able to modify the data of a home like the Home Rotator Plug-in developed by Michel Mbem.
Custom Search
If you liked this article, subscribe to the feed by clicking the image below to keep informed about new contents of the blog:
0 commenti:
Post a Comment