ObPlacer XML

From FSDeveloper Wiki
Jump to: navigation, search

This article is the user manual for ObPlacer XML. This tool allows you to place objects while you slew through FS. It provides you a graphical user interface to the creation of an XML scenery file. You can place library objects, effects, generic buildings or MDL objects (exported from GMax).

You might think the features of this tool sound very similar to the Rwy12 Object Placer tool and that is true. After Rwy12 was released I have considered if I should continue developing ObPlacer XML. But because I think there are some difference between these tools I have continued the development (as you can see from this new version).

Rwy12 is a great tool if you are not really a scenery designer and want to place a few library objects around your favourite airport. But for a scenery designer who just wants to place an object he has made in GMax and which is unique for a certain airport I think Rwy12 is not really efficient, as you would have to make a special XML file for Rwy12 first, while ObPlacer XML is able to read your BGLComp library XML or add the MDL object directly.

If you feel you are more comfortable with placing objects from a predefined library, I advice you to take a look at Rwy12 instead. If you by now still think this could be the tool for you, please continue reading the rest of this manual.

Download

Installer version

Zipfile version

Installation

The installation procedure of ObPlacer XML depends on the version you have downloaded. If you have downloaded one of the installers, then you only need to run that installer and you are ready to go. If you have chosen to download the ZIP file version, you need to unzip the content of the file to a folder of your choice.

Before you can start using ObPlacer XML there are two things that you need to check. First you need to make sure that FSUIPC is installed on your computer. FSUIPC is the module that ObPlacer XML uses to communicate with Flight Simulator and to read or write the position of your aircraft. If you do not have FSUIPC installed yet, you can download it from the FSUIPC homepage

Without FSUIPC you can still use ObPlacer XML to place your objects, but you will have to type in the coordinates manually. So it is strongly adviced to use FSUIPC, as you can then just slew around in FS to get the correct coordinates.

To make use of the dynamic preview of the GenericBuilding objects, you will need to install the latest version of the graphical DLL files by Martin Wright as well. Without these files the dynamic preview will be disabled (but the rest of the tool is still working). You can get these DLL files from his homepage.

The first time you start ObPlacer XML a configuration file will be made. If you are updating ObPlacer XML and you get crashes at startup, please remove your current config.xml file and let ObPlacer XML create a new one for you.

To get preview pictures with most default library objects, it is also adviced that you install the additional picture pack that is available from FsDeveloper.com. Just unzip all these pictures to a subfolder called pics in your ObPlacer XML folder.

If you ever want to uninstall ObPlacer XML, you can run the uninstall program that is located in your ObPlacer XML folder. You can also start this uninstaller from the "Add or remove software" section of the control panel. If you used the ZIP file distribution you can just delete the folder you placed the files in.

Interface

This section describes the components of the graphical user interface. As the interface is totally new compared to the previous versions of ObPlacer XML it is advised that every user reads this section.

The interface consists of the following main elements:

  • A main form that contains a list of all objects placed in your XML file
  • A form with a tree view of all object available for placement
  • A form that shows the properties of the currently selected object
  • A form that can show a preview of the selected object

Below you find an image of how the interface of ObPlacer XML can look. Besides the main elements, which will be described in more detail later, the interface also contains a menu bar and a status bar.

Obp screen.jpg

The dockable forms

One of the main features of the new interface is that the forms are dockable. So you can arrange them in a way that suits you. The object tree, the object properties and the preview form can all three be placed either at the top, bottom, left or right side of the screen. You can also change their width and height. All other space is filled with the list of placed XML objects. Your current layout of the forms is saved when you export ObPlacer XML, so it will have been remembered the next time you start again.

For example, when placing library object I prefer to have the object properties and the preview form on the right, as you need quite some space to display the tree of available objects. When placing GenericBuildings on the other hand, you need a lot of space for the properties (as I hate to have to scroll through them). So in that case I prefer to have the preview on the left, together with the available object tree.

You can also undock the forms and use them as floating forms. If you have a multi monitor setup you could even place the preview form full screen on your second monitor.

Menu bar

File

Obp mfile.jpg

The file menu gives you access to the usual things you would expect there.

  • New XML Create a new XML file. You are asked to provide a name for the new XML file. If the file already exists you will be ask if you want to overwrite it.
  • Open XML Open an existing XML file.
  • Save XML Save the currently loaded XML file.
  • Save XML As Save the currently loaded XML file, where you get the chance to provide a new file name.
  • Compile BGL Compile the currently loaded XML to a BGL file. You will be asked to provide the location for this BGL file (the default location is in the same folder as your XML file). Your selected location will be remembered and used as default the next time you compile. This is done for each XML file separately. During the compilation you will be shown a form that displays any messages from the compiler.
  • Export as SHP file Save the current XML file as a shapefile((If you have no idea what I am talking about here, just skip this item, so will probably not need it in that case. This is more an advanced option if you want to export your XML data to another format.)). This option only works if you have installed the file shapelib.dll on your system (not provided with ObPlacer XML). In the database file belonging the to shape file, the GUID, name and the comment of the object are written.
  • Last opened files At the bottom of the menu you will find a maximum of 8 XML files that you have recently used. This allows you to reopen them faster.

Edit

Obp medit.jpg

The edit menu gives you the option to undo recent changes your made to the XML file. This can either be adding or removing an object, adding or removing a local MDL object or changing the parameters of an object.

Temporarily files are created in your ObPlacer XML folder for each undo state. So during runtime this could take a little harddisk space, but these files will be removed once your close ObPlacer XML.

The number of undo steps that you can perform is almost unlimited. The counter of the undo list has a maximum value of 32767, but I doubt someone will make that many changes to a single XML file.

Besides the undo functionality, the edit menu also gives you access to a Coordinate conversion tool and a SHP file import option. These two options only work correctly if you are using the Dutch RD coordinate system, so they are probably not of much use to most users.

Objects

The Object menu is also available as a right click menu in the available object tree, its functions will be described in more detail when that form is discussed.

View

Obp mview.jpg

The view menu allows you to enable or disable the display of the three dockable forms. So if you don't need the preview at the moment for example, you can hide it to get more space for the other forms. Clicking the option again will bring back the form at its last location.

Statusbar

Obp statusbar.jpg

At the bottom of the screen you find a statusbar. In the left side messages can be displayed, for example when you add new objects. On the right you find two buttons, each with a special function.

  • Dockable The dockable button indicates if the forms are dockable or not. If you click this button you will notice that the text becomes greyed out and now you can no longer dock or undock forms. This is to prevent trouble when you are moving a floating form and it keeps docking while you do not want it to do so. Or to make sure you do not undock a form by accident.
  • FSUIPC The last button indicates the connection status with FS. If no connection could be made using FSUIPC the label will show "FSUIPC failed" and when a connection could be made the label will read "FSUIPC OK". Clicking this button has no effect, ObPlacer XML tries to make the connection automatically.

Placed objects

The center part (this depends a bit on how you arranged the dockable forms) of your screen is reserved for the list of the objects you have placed in your XML file. When you click on an object in this list, its properties will be displayed in the object properties form (this form is discussed in more detail later) and the tree view will move to this object as well.

Obp mlist.jpg

If you right click on an object you will get the menu as shown above. This menu gives you access to the following functions:

  • Remove object (R) This removes the currently selected object from the XML file.
  • Move upwards (Z) This moved the currently selected object upwards in the list. This enables you to rearrange your objects in a logical way.
  • Move downwards (A) This moved the currently selected object downwards in the list. This enables you to rearrange your objects in a logical way.

The letters between brackets behind the function name are the keyboard shortcuts that you can also use the perform that function. So if you press the Z key, your selected object will be moved downwards.

Available objects

Obp objtree.jpg

The available objects tree gives an overview of all objects you can place in your XML file. This tree consists of the following categories:

  • Default library objects This category contains objects that are available in the default library that come with Flight Simulator. This list is certainly not complete, so if you have found other useful objects please let me know so that I can add them. When you have installed the picture pack for ObPlacer XML as well, most of these objects will get a preview image.
  • Effects This category contains all effect files you have installed in your Flight Simulator. They are read directly from the effects folder on your PC. Please remember that some of them are designed for aircraft and will not work in scenery.
  • User library objects When you add the XML source of your own object library, a new entry will be made in this category. Under this entry you can then find all the objects of this user library. When using these objects, you need to make sure that you distribute the library BGL together with your placement BGL.
  • MDL objects When you add a MDL object, created with GMax, to ObPlacer XML it will appear under this category. Please be aware that objects placed with this method are locked to a certain geographic location, so it is not advised to call them as library objects from another XML file.
  • Generic building This category allows you to create XML style GenericBuildings. The dynamic preview will help you to see how the building is going to look in Flight Simulator.
  • Misc This category contains miscelaneous XML object. At the moment only the Fuel Trigger object falls into this category (note: the Misc section is not shown in the screenshot).


Obp mobjects.jpg

Once you have selected an object in the tree list, you can right click to get a menu with functions you can perform. If you want you can also access these functions using the File, Objects menu. If a function is not valid for the object you have currently selected, it will be greyed out. The available functions are:

  • Add new object before selected (P) This will place the currently selected object from the tree list, before the currently selected object of your XML file. This allows you to group objects in a specific way. After you have added the object, you can adjust its properties if needed in the object properties form.
  • Add new object at end of list (E) This will place the currently selected object from the tree list, at the end of your XML file. After you have added the object, you can adjust its properties if needed in the object properties form.
  • Update selected object This will update the selected object in the XML list, to the object you have currently selected in the tree list. This allows you for example to replace one library object with another, without having to create a new one. All properties remain the same, only the object is changed. This option is only allowed if the objects you have selected are of the same type. So both must be effects or library objects.
  • Add user library This gives you the option to load a new user library XML file into ObPlacer XML. This user library is then stored in your config and loaded again the next time you start ObPlacer XML.
  • Add Rwy12 library Just like the option above this allows you to load a new library into ObPlacer XML. This option allows you to read Rwy12 XML files, while the preview one reads BGLComp source XML files.
  • Add local MDL This gives you the option to add a MDL files to your current XML file. As this object is stored in your XML file, it is only available in this file.
  • Remove local MDL This allows you to remove the currently selected local MDL file from your XML file. All placed instances of the object will then also be removed.
  • Mass add MDL folder This allows you to add all MDL objects in a certain folder to your XML file at once.
  • Rescan object tree This option rescans the object tree. This can be useful if you have installed a new effect or when you have updated a user library XML file. After rescanning these changes are also visible in ObPlacer XML.

The two placement functions also have a keyboard shortcut, which is indicated with the letter between brackets. And when you double click on an object in the tree view it will also be placed at the end of your object list.

Object properties

Obp properties.jpg

The object properties form allows you to change all the parameters of your object. For example its location or heading. When you click on a value you will enter the editing mode where you can change the value. Once you click on the next grid cell the new value is stored in the XML file (you can undo your change with the undo function if needed).

Some parameters will get a textbox to change the value, while others will have a dropdown list or a spinbox. In all cases you are limited in the characters you can enter. For example only numbers or a dot are allowed when you enter a heading. This makes sure you can only added a valid value.

There is also a faster way to navigate through the grid and that is by using the keyboard. If you press the Enter key you will enter the editing mode for the selected parameter. And if you press Enter again the new value is stored. By using Tab and Shift-Tab you can move to the next or previous grid. If you move to another field while still in editing mode, you will remain in editing mode in the new field as well.

Obp mprop.jpg

If you right click on either the latitude, longitude or the heading you will get the menu as shown above. This menu gives you some functions to read or write values from or to Flight Simulator using FSUIPC. So the connection with Flight Simulator should be active for these functions to work.

  • Read position from FS (R) This will read the total position from Flight Simulator (so latitude, longitude and heading).
  • Write position to FS (W) This will write the total position to Flight Simulator (so latitude, longitude and heading).
  • Read latitude from FS This will only read the selected parameter from Flight Simulator (in the image this is the latitude, but it could also be the longitude or the heading).
  • Write latitude to FS This will only write the selected parameter to Flight Simulator (in the image this is the latitude, but it could also be the longitude or the heading).

The functions to read and write the total position can also be access with a keyboard shortcut. The letters are given between brackets.

When you place a new object, ObPlacer XML will by default try to read the total position from Flight Simulator. If this is not the position you want, you can edit the values manually.

Preview

Obp preview.jpg

The preview form can give you a preview of the selected object (as the name already suggests). If you click on a library object, ObPlacer XML will try to load a JPG or BMP file with the GUID of the object as name from the pics subfolder. If such an image is found the preview is shown, else the preview forms remains empty. When you select a GenericBuilding, you will get a rotating dynamic preview of how the object will look in Flight Simulator. When you change the parameteres of your object, this preview will also adapt.

If you right click on the preview, you will get a popup menu where you can stop the rotation of the object. Sometimes this might make it easier to enter the correct parameters for your building.

Support

This last version of ObPlacer XML should be rather stable and it do no longer call it a beta version. But as the GUI has been totally reworked since the last version, there is always a chance that some problems are still there. That is the reason this version is (not yet) called v1.00. So if you found a problem, or if you have comments or suggestions on how to improve this tool, please let me know. You can reach me either by email or through the forums of my website FsDeveloper.com.

Thanks to

  • Nick Whittome for his suggestions and ideas that helped in shaping the concept of ObPlacer XML
  • Erwin Horjus for his suggestions to add new functionality to ObPlacer XML
  • Jon Patch for encouraging me to add the GenericBuilding feature and helping a lot with debugging this new feature
  • Pete Dowson for the FSUIPC module
  • Marco Pipino for the DOSOutputs class I used to compile the BGL file from ObPlacer XML
  • All other beta testers who helped to get as much bugs out of ObPlacer XML as possible
  • Everybody who gave me feedback about previous versions

Version history

v0.84 05/08/2007

  • Added the option to place Fuel triggers
  • If Fs2004 is not found on your system, ObPlacer XML will now also look for FsX
  • FSUIPC4 is now recognised as a valid FSUIPC version

v0.83 29/08/2006

  • Reversed texture mapping (X and Z axis) solved in the preview window
  • Added ability to read library information from Rwy12 XML files
  • When editing properties the spacebar is now also allowed, so that you can edit coordinates that are not in decimal form
  • Rotation of the preview can be stopped

v0.82 01/03/2006

  • Comma vs dot problem solved when reading heading with FSUIPC
  • Four additional roof textures available for GenericBuildings
  • Four colors available for the GenericBuildings to be used instead of textures
  • Double clicking in the tree view will also place the object at the end of your list
  • When opening new file you are asked if you want to save the current one
  • Other small changes I have forgotten about

v0.81 03/08/2005

  • Dynamic preview problems solved, should now work on each PC
  • Option between single and double buffering removed, double buffering is now default
  • Option add to change the object while keeping all other parameters (only allowed if new object is same type)
  • Properties are now stored correct if you click somewhere else
  • Object list can be exported as shapefile

v0.80 16/07/2005

  • Ability to place GenericBuildings
  • Dynamic preview of the GenericBuildings
  • Totally new GUI
  • Windows comma vs dot problem solved

0.14 beta 25/04/2005

  • Now using FSUIPC instead of FSConnect for communication with FS
  • Ability to write position to FS added
  • Preview pictures added
  • BGL path is remembered for each XML file
  • Available objects tree can be rescanned

v0.13 beta 10/01/2005

  • Now works with all decimal character settings of windows
  • Scale no longer reset when selecting new object

v0.12 beta 08/01/2005

  • Compilation problems solved
  • Position can also be edited
  • Position read from FS as option
  • Generic.xml updated
  • Other minor fixes

v0.11 beta 31/12/2004

  • When errors occur during saving the XML file, the less readable but still valid XML file is restored
  • Tabs in the XML file no longer give trouble
  • Crash solved when adding MDL objects with an empty object list
  • Compilation problems due to path in XML file solved
  • When you quit you are asked if you want to save the current XML file
  • Folder for the BGL file can be specified as well
  • Option to add all MDL objects in a certain folder at once
  • When adding/updating or deleting objects the focus of the object list works correct
  • The focus colour of the object list now works with all Windows colour themes
  • The produced XML file is more readable now
  • Last used XML and MDL folder are remembered separately

v0.10 beta 29/12/2004

  • First version available for testing.

Users license

(c) 2004-2006 SceneryDesign.org / Arno Gerretsen

This software program is distributed without charge to other scenery designers, redistribution of the original installer EXE file is allowed. You are NOT allowed to sell this software program or ask money for its distribution. BGL files created with this software program can be used in commercial scenery projects if you wish.

The copyright and any intellectual property relating to this program remain the property of the author.

The software distributed in this way may represent work in progress, and bears no warranty, either expressed or implied.