https://web.archive.org/web/20081123094425/http://lc0277.nerim.net/whisplacer/import-tut.html
https://web.archive.org/web/20081123095233/http://lc0277.nerim.net/whisplacer/import-tut.pdf
"
Managing objects library with Whisplacer
This document covers the various steps needed to manage objects library used by Whisplacer. Whisplacer is an object placer that allows you to created Flight Simulator scenery by placing various 3D objects, effects and other scenery elements. Note that this document does not contain any information about object of library creation.
Whisplacer maintains a database of objects, which contains various informations about the size, the visual appearance and other data needed for the preview feature. 3D objects are usually packed into what is called a
library, that is a collection of objects reusable in different scenery. Flight simulator X is shipped with a default library set of around 3500 objects in a dozen categories. This set of objects is already configured in Whisplacer, but a lot of third-party objects library can be freely downloaded and they
must be configured in the Whisplacer library manager in order to be used by the software.
This document will use the following free libraries as demonstration :
Note that a lot of Pre-FS9 objects are available, called API or macros. These objects are incompatibles with Whisplacer and should not be used for creating FSX scenery, since they rely on backward-compatibility features and are not guaranteed to work on future versions of Flight Simulator.
Installation of the objects library in Flight Simulator
A third-party object library may have specific installation procedures, so you should refer to its documentation before configuring it. Generally a library comes with a set of one or more BGL files numerous textures, in either BMP or DDS format. The two sets of files are found in two directories, respectively the
scenery and the
texture folder.
The configuration of the library in Flight Simulator is an important step and depends on the distribution and folders organisation you're setting up. The general rule is to have the library base folder (containing both the scenery and texture subfolders) declared in the Flight Simulator scenery database.
This declaration is important, because if objects library cannot be found by Flight Simulator, the scenery may fail to display and the preview feature of Whisplacer can lead to FS crash.
Basic declaration of the library in Whisplacer
The basic declaration of the library is the essential step needed to use objects from a third-party library in Whisplacer.
First, open the library manager, by accessing the
library maintenance menu item :
This will display the library maintenance panel :
This dialog features a tree representation of all libraries actually configured in Whisplacer and a set of actions needed for the maintenance of the live preview feature (this will be treated later) .
The tree is a logical way to store and clevery organize library, for instance by type or author. It does not reflect the physical organization of files.
By default, there is a virtual folder called
“FSX Libraries” containing all default libraries. You could add third party libraries in this folder, but it's not recommended, so as to clearly identify stock libraries and non-default libraries. This distinction is necessary if you wish to redistribute your scenery, because you'll need to ship or provide a link to third-party libraries.
So let's use a different folder for storing libraries; the
“User libraries” folder could be used for that. We're going to add the complete Rwy12 libraries. Since there are numerous library files in this package, we'll create a subfolder for rwy12.
Select “
Add folder” and choose the parent folder, here the
“User libraries” folder :
And provide a name for your folder :
Now you've added a Rwy12 folder.
The next step is to import BGL files into the folder we've created. Select
“Add a library BGL” and choose the folder we created :
Next locate the folder where you decompressed the Rwy12 libraries. You can select multiples BGL files :
The import process can be very long, so if you're going to add a lot of files, you can go out and take a cup of coffee. The software will open every file and report errors at the end. If everything went fine , you'll see the following message :
If you tried to import old libraries containing incompatible objects, the program may report some error messages. Click on
details to see the causes :
If the program reports some error messages that is not related to the format of BGL files, it may be a bug and you should send the details of the error to the author.
Finally you'll see all BGL files you selected as child folders :
The tree elements can be expanded to see the objects. Now that the objects are imported into Whisplacer, they can be placed in the editor. Note that you only need to add libraries once.
As you can see, the objects are designated by their GUID (the hexadecimal numbers). Depending on the version of the Flight Simulator used to design objects, they can have a friendly name or not. Here you imported Rwy12 libraries, which were designed for FS9, so they don't have such informations.
Importing other library informations
It is generally easier to use friendly names rather than the numerical GUID for placing and displaying objects on name. FSX objects have names encoded in the library file (this name is set up by the object designer). For FS9 objects, Whisplacer can modify the displayed name to a more friendly string.
You can either modify each object manually, by clicking on the object name in the maintenance window, or import information from a description file.
Whisplacer can read information from two different types for description format introduced by two popular objects placer :
- Rwy12 XML object description format
- EZ-Scenery .TXT format
Some popular libraries come with description files in this format.
To import a set of description, select “Import infos”
And choose the location of the file containing objects descriptions. Now the objects have intelligible names :
Setting up thumbnails
Whisplacer can display a thumbnail image of each library object configured, to let you choose more easily appropriate objects for your scenery. The default Whisplacer installation contains thumbnails for the 3500+ objects of the default FSX library. If you installed and configured third-party libraries you could provide such images.
There are two types of thumbnails used by Whisplacer : the 3D
side thumbnail giving a general overview of the object and displayed when choosing a library element; and the
top thumbnail displayed on the top-down map view.
Thumbnails files must be named and located according to strict rules :
- Each object is uniquely referenced by its GUID using the bracket notation, ie {4773ABB6-391E-29F5-ABC5-38714BEBF49A}
- Side thumbnails are named {GUID}.thumb.EXT
- Top thumbnails are named {GUID}.top.EXT
- Valid file extensions are .GIF, .JPG and .PNG
- The thumbnail image file is placed in the “thumbnails” folder of your Whisplacer installation and in a file hierarchy following the folder tree in the library manager. The first level of nodes (“FSX Libraries”, “User libraries”) is not accounted.
Let's show how this works with an example. Suppose you installed Whisplacer in C:\FS\Whisplacer. You added Rwy12 objects library according to the procedures explained in this document : ie all Rwy12 bgl files were imported under a folder called “
Rwy12”, situated in the “
User libraries” collections.
Suppose there is an object called “
balloon_17” situated in the “
add_balloons.bgl” library. The object is not referenced using its name, but with its GUID: {7BE84CB7-5E3E-4D9A-91BE-067F2A26C3F8}.
Then a valid thumbnail file search path could be :
C:\FS\Whisplacer\thumbnails\Rwy12\add_balloons\{7BE84CB7-5E3E-4D9A-91BE-067F2A26C3F8}.thumb.gif
C:\FS\Whisplacer\thumbnails : it's the base path for searching thumbnails
Rwy12 : the name of the folder we created in the library manager.
Note that its parent folder “User libraries” is not used for calculating the path
add_balloons : the name of the library file without the .bgl extension
{7BE84CB7-5E3E-4D9A-91BE-067F2A26C3F8} : object's GUID
.thumb.gif : suffix for a side thumbnail. another valid name could (be) .top.png for a top view thumbnail
Creating thumbnails for the both views of each objects could be a painful task, but some popular packages may already have thumbnails.
'Side' thumbnail
'top thumbnail'.
You can save thumbnails with transparent colors so objects could be displayed over a background image.
Managing export status
An unique feature of Whisplacer is the ability to insert and modify objects in a live Flight Simulator session, without the need to compile scenery and restart FS.
This feature is performed using the SimConnect API of FSX to create AI (artificial intelligence) objects similar to AI aircraft, but representing objects currently edited.
To achieve this, all objects need to be exported as SimObject container, meaning that the library objects could be used as AI objects. This is necessary to use the live preview feature. In particular, it must be checked the first time you run Whisplacer.
The library maintenance dialog allows you to perform the different steps of this export. Fortunately, most of them are automatic.
The
“Refresh” button allows you to refresh the current export status of library objects. Objects showing a status in green are exported and usable for live preview. Objects in orange are not.
You change the export status by choosing a new state in appropriate column or clicking on one of the different export buttons. There exists different export modes because some objects may need special care when exporting. Generally the
Automatic mode will produce the best result. After you changed some state, click on apply to operation.
You must restart FS after you altered the export status of some objects. Also, you must re-export each objects that you insert into the library."