Howto:Add shared models manually: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(→‎.STG file format: Updates to be consistent with Docs/README.scenery)
 
(18 intermediate revisions by one other user not shown)
Line 1: Line 1:
You can add your own objects, known as "shared models" to FlightGear's world.  This howto explains a few ways to do so.  It assumes that you already have a model. There are many that come standard with FG; they are stored in the <tt>[[$FG_ROOT]]/Models</tt> directory.
You can add objects to FlightGear's world by making use of "models" of those objects.  This howto explains one way to do so, especially with the shared models that are distributed with FlightGearThese models are called "shared" because they are used to define many objects in different places. (There are also "static models" which represent unique objects, such as famous buildings, that only exist in one place, but we won't have much to say about them.)  Shared models are stored in the <code>[[$FG_ROOT]]/Models</code> directory.


You can also create one using a suitable modeling program such as [http://www.blender.org/ blender].  You may use any format that PLIB supports. Currently, this means in addition to the 3ds models mentioned below, you may use AC3D and other formats.  
You can also create your own models; see [[Modeling - Getting Started]].  Most Flightgear models are in the .ac (AC3D) format.




== Adding Shared Models to FlightGear's World ==
== Using Shared Models to Add Objects to FlightGear's World ==


=== Step 1 ===
=== Step 1 ===
If you plan to use one of the standard FG models, skip to step 4.
If you plan to use one of the standard FG shared models, skip to step 4.


If you have created your own model, create a directory under <tt>[[$FG_ROOT]]/Models</tt>. We'll use <tt>$FG_ROOT/Models/MyModels</tt> as an example.
If you have created your own model, create a new directory for it under <code>[[$FG_ROOT]]/Models</code> (to keep your models separate from the standard ones). We'll use <code>$FG_ROOT/Models/MyModels</code> as an example.


=== Step 2 ===
=== Step 2 ===
Save your .ac file containing the model into the <tt>$FG_ROOT/Models/MyModels</tt> directory. We'll use <tt>MyModel.ac</tt> as the name of that file.
Copy the file (usually has an .ac extension) containing your model into the <code>$FG_ROOT/Models/MyModels</code> directory. We'll use <code>MyModel.ac</code> as the name of that file.


=== Step 3 (optional) ===
=== Step 3 (optional) ===
If you intend to include animation, create an XML file called <tt>MyModel.xml</tt> inside the <tt>$FG_ROOT/Models/MyModels</tt> directory with the following contents:
If you intend to include animation, create an XML file called <code>MyModel.xml</code> inside the <code>$FG_ROOT/Models/MyModels</code> directory with the following contents:


  <?xml version="1.0"?>
  <?xml version="1.0"?>
Line 27: Line 27:
  </PropertyList>
  </PropertyList>


This xml file references the .ac model file and tells FlightGear that it must be visible from 0 meters up to 20 km.
This file references the .ac model file and tells FlightGear that it must be visible from 0 meters up to 20 km.


An XML file is only necessary if you are intending to include animation; it is not required to render a model at a fixed location in FlightGear.  
An XML file is only necessary if you are intending to include animation; it is not required to render a model at a fixed location in FlightGear.  


=== Step 4 ===
=== Step 4 ===
Next, you have to determine where to place the model in FG's world.
Next, you have to determine where to place your object in FG's world.


A really useful resource at this stage is [http://www.terraserver.com TerraServer].  Enter a street name, city, and state. Then you can choose from several types of public-domain aerial photography from the US Geological Survey. When you get a good photo of your feature, click on the Info link. Your image will be broken into tiles with latitude and longitude of the edges of the tiles. This is good way to get close to the position you want. Google Earth is also a good way to obtain position information, and there are other websites that will provide it also.
Useful resources at this stage are websites that allow you to get the coordinates of a point from aerial photographs.  One such is [http://itouchmap.com/ itouchmap.com], which relies on Google Maps.  Enter a street name, city, and state. When you get a good photo of your feature, click on map to place a marker there, then read the displayed coordinates. Google Earth is also a good way to obtain position information, and there are other websites that will provide it also, or you can get it from a GPS.  (Coordinates of real-world locations are not copyrightable, so there is no legal problem with using these tools to find coordinates, but don't copy other content, such as images or models.)


Then, you need to place the object precisely. An easy way do this is with the [[UFO]] model, which allows you to place objects and see what they look like there; see [[Howto: Place 3D objects with the UFO]].  It calculates the positioning details for you and writes them out in the correct format, but for completeness I'll continue by describing a manual way to do it, for people who may need or want to know the inside details.
Once you've got at least a rough idea of the coordinates, you need to place the object visually.  


Start FG and fly to the location where you want to place the model. Open up the property browser in FG (File->Browse Internal Properties), and the <tt>/position</tt> keyWrite down the values for <tt>latitude-deg</tt>, <tt>longitude-deg</tt>, and <tt>ground-elev-m</tt>. (If you want to place the object above ground level, then you'll have to add the appropriate number of meters yourself.) Then, go to the <tt>/environment</tt> key and write down the tile number (current-tile-id).  
One easy way do this is with the [[UFO]]. In addition to making it easy to move around (or hover), it allows you to place objects and see what they look like thereSee [[Howto: Place 3D objects with the UFO]]. Another easy way is with the [[FlightGear Scenery Designer]]Both tools calculate the positioning details for you and write them out in the correct format.


An alternate way to get the tile number is with a perl program in [[Git]] called calc-tile.pl that works out what stg file a geodetic coordinate falls in. You can get it here if you don't feel like playing with Git and don't have the Git branch installed: http://gitorious.org/fg/flightgear/blobs/raw/next/scripts/perl/scenery/calc-tile.pl. Run the perl script in a terminal window, passing it the longitude and latitude that you wrote down in step 4. You'll probably have to install perl first if you run on a MS OS's. Example :
Here, though, we'll continue by describing a manual way to do it, for people who may need or want to know the inside details.


$ ''./calc-tile.pl -55.5 30.3''
Start FG and fly to the location where you want to place the object (or use [[command line options]] to start in that location). Open up the property browser in FG (File->Browse Internal Properties), and the <code>/position</code> key.  Check that the values for <code>latitude-deg</code> and <code>longitude-deg</code> are what you want, or write them down if you're positioning things visually, and also note the <code>ground-elev-m</code>. If you want to place the object above ground level (or partially bury it), then adjust the number appropriatelyThen, go to the <code>/environment</code> key and write down the tile number (current-tile-id) for that location.
Longitude: -55.5
Latitude: 30.3
  Tile: 2039314
Path: "w060n30/w056n30/2039314.stg"
 
Finally, you can use FGSD for steps 4 to 6.


=== Step 5 ===
=== Step 5 ===
Next locate a .stg file into which you will place a reference to the new model and its position.  
Locate a .stg file into which you will place a reference to the object's model and its location and orientation.  


There is more information about .stg files, below, but in brief:  The .stg files are named according to tile number and stored under the scenery directories.  The default installation places a limited amount of scenery (for the area around San Francisco) in <tt>[[$FG_ROOT]]/scenery</tt> but you may have scenery in other directories, as specified in <tt>[[$FG_SCENERY]]</tt>.  (See [[Howto: Install scenery]].) Under each scenery directory, you will find directories called <tt>Objects</tt> and <tt>Terrain</tt>, and under them directories that group tiles into larger and smaller quadrants.  Thus, if the tile number is 942058, you will find <tt>942058.stg</tt> under <tt>$FG_ROOT</tt> as <tt>$FG_Root/Scenery/Objects/w130n30/w123n37/942058.stg</tt>.
The .stg files are named according to tile number and stored under the scenery directories.  The default installation places a limited amount of scenery (for the area around San Francisco) in <code>[[$FG_ROOT]]/Scenery</code> but you may have scenery in other directories and listed in the scenery path (<code>[[$FG_SCENERY]]</code>; see [[Howto: Install scenery]]).  Under each scenery directory, you will find directories called <code>Objects</code> and <code>Terrain</code>.  Objects associated with airports are usually listed in a .stg file under "Terrain"; other objects are put under "Objects".  The files under Objects and Terrain are organized in directories that group tiles into larger and smaller quadrants.  Thus, if the tile number is 942058, you will find a file called <code>942058.stg</code> in the directory <code>$FG_Root/Scenery/Objects/w130n30/w123n37/</code>.


There is generally more than one .stg file for a given tile, in different directories.  It's important to edit one that will actually be read by flightgear (see below).  One thing you can do is create a personal customized scenery directory separate from the standard installation.  That way, if you upgrade FG your customizations won't get overwritten.  (If you create such a directory, add it first in <tt>[[$FG_SCENERY]]</tt>, create a directory structure inside it parallel to the one in the standard scenery story, and create a .stg file in the appropriate place.) For the same reason, it is best not to edit the .stg files in the folder where TerraSync stores the scenery it has fetched, since TerraSync may overwrite them with newer versions.  Objects associated with airports are usually put into a .stg file under a "Terrain" directory; other objects are put under "Objects".
There is generally more than one .stg file for a given tile, in different directories, because scenery can be stored in more than one place.  It's important to describe your new object in a .stg file that will actually be read by flightgear (see [[#STG files|below]]).  It is recommended that you create a personal customized scenery directory separate from the standard installed scenery.  That way, when you upgrade FG your customizations won't get overwritten.  If you create such a directory, list it first in <code>[[$FG_SCENERY]]</code>, create a directory structure inside it parallel to the one in the standard scenery directory, and create a .stg file in the appropriate place. Similarly, it is best not to edit the .stg files in the folder where [[TerraSync]] stores the scenery it has fetched, since TerraSync may overwrite them with newer versions.


=== Step 6 ===
=== Step 6 ===
Add the following lines to the stg file you've chosen, replacing the parameters with your own :
Add a line like the following to the .stg file you've chosen, replacing the parameters with your own :


  OBJECT_SHARED Models/MyModels/MyModel.xml -55.5 30.3 1000.0 0.00  
  OBJECT_SHARED Models/MyModels/MyModel.xml -55.5 30.3 1000.0 0.00  


In brief,the format is :
In brief, the format is :
  OBJECT_SHARED relative_path_to_model_file longitude latitude altitude_above_sea_level_(meters) ellipsoid_ROTATION
  type path longitude latitude elevation heading
 
The path is relative to the $FG_ROOT directory.  If you have an XML file for the model, specify it here, otherwise specify the .ac file.
 
There are more details on the .stg file format below.


Alternately, there is a way to include this same information in XML configuration files that are loaded at runtime; see [[Howto: Place 3D objects with the UFO]] for more details.  This approach has the advantage of keeping your new scenery clearly separate from the standard scenery files without having to create your own custom scenery directory structure. However it requires either manually loading the config file from the command line or mentioning it in one of the standard startup files (such as [[.fgfsrc]]) and having it loaded every time you start FG, whether or not you are going to be flying in the area.  If you place the scenery information in .stg files, it is only loaded when needed.
There are more details on the .stg file format [[#STG files|below]].


=== Step 7 ===
=== Step 7 ===
Restart FG and fly to where you added the model; it should be there.
Restart FG and fly to where you added the model (or use [[command line options]] to start it with that location as the initial location); it should be there.  Check its location and orientation, make any necessary changes in the .stg file, then exit and restart FG to check it again.


== STG file format ==
== STG files ==
There is documention for the .stg files used by FlightGear in <tt>$FG_ROOT/Docs/README.scenery</tt>.  Only information relevant for placing shared objects is included here.
There is documention for the .stg files used by FlightGear in <code>$FG_ROOT/Docs/README.scenery</code>.  Only information relevant for placing shared objects is included here.


Scenery files are loaded by default from <tt>[[$FG_ROOT]]/Scenery</tt>.  Alternate locations (a "scenery path") can be specified in <tt>[[$FG_SCENERY]]</tt> (or from the command line); the first-named directories have highest priority.  Thus, if you create a local directory for storing custom scenery you create, include it first in the scenery path.
Scenery files are loaded by default from <code>[[$FG_ROOT]]/Scenery</code>.  Alternate locations (a "scenery path") can be specified in <code>[[$FG_SCENERY]]</code> (or from the command line); the first-named directories have highest priority.  Thus, if you create a local directory for storing custom scenery you create, include it first in the scenery path.


Lines for shared objects in the STG file look like this:
Lines in a .stg file which describe shared objects look like this:


{| class="prettytable" border="1" cellspacing="0" bordercolor="black">
{| class="prettytable" border="1" cellspacing="0" bordercolor="black">
Line 89: Line 79:
|20
|20
|-  
|-  
|Type
|type
|filename path
|filename path
|Longitude
|longitude
|Latitude
|latitude
|Elevation
|elevation
|Heading
|heading
|}
|}


The filename path is relative to <tt>$FG_ROOT</tt>Longitude and latitude are expressed as decimal numbers (not degrees/minutes/seconds), with negative values representing west and south. Elevation is in meters above mean sea-level.  Heading is in degrees, *counter-clockwise* from North as 0.0 (i.e. when looking from above).  Note that this is opposite from headings in other places in FlightGear, which are clockwise.
* Most of the time you'll use OBJECT_SHARED for a shared model.  (If you have a one-of-a-kind object, you should use OBJECT_STATIC instead; see an explanation of it in <code>$FG_ROOT/Docs/README.scenery</code>.)
* The filename path points to the file that contains the model; for the OBJECT_SHARED type, this is relative to the $FG_ROOT directory. Specify the XML file for the model if there is one, otherwise the .ac file.   
* Latitude and longitude are expressed as decimal numbers (not degrees/minutes/seconds), with negative values representing west and south.
* Elevation is in meters above mean sea level ('''not''' feet, as is stated in some other places in the wiki)
* Rotation is '''counter-clockwise''' from north (not clockwise as in the rest of FG).


Some examples:
Some more examples:


  OBJECT_SHARED Models/MidAtl/cape-may-light.ac  -74.959970 38.933332 -93.0 0.00
  OBJECT_SHARED Models/MidAtl/cape-may-light.ac  -74.959970 38.933332 -93.0 0.00
  OBJECT_SHARED Models/Airport/windsock.xml -122.360843 37.613877 1 0
  OBJECT_SHARED Models/Airport/windsock.xml -122.360843 37.613877 1 0
  OBJECT_SHARED Models/Structures/vordme.xml -122.37389 37.61948 -0.404 0
  OBJECT_SHARED Models/Structures/vordme.xml -122.37389 37.61948 -0.404 0
== XML files ==
Alternately, there is a way to specify this same information in XML configuration files that are loaded at runtime; see [[Howto: Place 3D objects with the UFO]] or <code>$FG_ROOT/Docs/README.scenery</code> for more details.  This approach has the advantage of keeping your new scenery clearly separate from the standard scenery files without having to create your own custom scenery directory structure.  Further, you can then manually control whether or not to load it at run-time, using the --config option on the command line. You can also include it in one of the standard startup files (such as [[Fgfsrc|.fgfsrc]]) but this will load it into memory every time you start FG, whether or not you are flying in the area.  If you place the scenery information in .stg files, it is only loaded into memory when needed.


[[Category:Howto|Add shared models manually]]
[[Category:Howto|Add shared models manually]]
[[Category:Scenery enhancement|Add shared models manually]]
[[Category:Scenery enhancement|Add shared models manually]]

Latest revision as of 16:28, 6 May 2012

You can add objects to FlightGear's world by making use of "models" of those objects. This howto explains one way to do so, especially with the shared models that are distributed with FlightGear. These models are called "shared" because they are used to define many objects in different places. (There are also "static models" which represent unique objects, such as famous buildings, that only exist in one place, but we won't have much to say about them.) Shared models are stored in the $FG_ROOT/Models directory.

You can also create your own models; see Modeling - Getting Started. Most Flightgear models are in the .ac (AC3D) format.


Using Shared Models to Add Objects to FlightGear's World

Step 1

If you plan to use one of the standard FG shared models, skip to step 4.

If you have created your own model, create a new directory for it under $FG_ROOT/Models (to keep your models separate from the standard ones). We'll use $FG_ROOT/Models/MyModels as an example.

Step 2

Copy the file (usually has an .ac extension) containing your model into the $FG_ROOT/Models/MyModels directory. We'll use MyModel.ac as the name of that file.

Step 3 (optional)

If you intend to include animation, create an XML file called MyModel.xml inside the $FG_ROOT/Models/MyModels directory with the following contents:

<?xml version="1.0"?>
<PropertyList>
 <path>MyModel.ac</path>
 <animation>
  <type>range</type>
  <min-m>0</min-m>
  <max-m>20000</max-m>
 </animation>
</PropertyList>

This file references the .ac model file and tells FlightGear that it must be visible from 0 meters up to 20 km.

An XML file is only necessary if you are intending to include animation; it is not required to render a model at a fixed location in FlightGear.

Step 4

Next, you have to determine where to place your object in FG's world.

Useful resources at this stage are websites that allow you to get the coordinates of a point from aerial photographs. One such is itouchmap.com, which relies on Google Maps. Enter a street name, city, and state. When you get a good photo of your feature, click on map to place a marker there, then read the displayed coordinates. Google Earth is also a good way to obtain position information, and there are other websites that will provide it also, or you can get it from a GPS. (Coordinates of real-world locations are not copyrightable, so there is no legal problem with using these tools to find coordinates, but don't copy other content, such as images or models.)

Once you've got at least a rough idea of the coordinates, you need to place the object visually.

One easy way do this is with the UFO. In addition to making it easy to move around (or hover), it allows you to place objects and see what they look like there. See Howto: Place 3D objects with the UFO. Another easy way is with the FlightGear Scenery Designer. Both tools calculate the positioning details for you and write them out in the correct format.

Here, though, we'll continue by describing a manual way to do it, for people who may need or want to know the inside details.

Start FG and fly to the location where you want to place the object (or use command line options to start in that location). Open up the property browser in FG (File->Browse Internal Properties), and the /position key. Check that the values for latitude-deg and longitude-deg are what you want, or write them down if you're positioning things visually, and also note the ground-elev-m. If you want to place the object above ground level (or partially bury it), then adjust the number appropriately. Then, go to the /environment key and write down the tile number (current-tile-id) for that location.

Step 5

Locate a .stg file into which you will place a reference to the object's model and its location and orientation.

The .stg files are named according to tile number and stored under the scenery directories. The default installation places a limited amount of scenery (for the area around San Francisco) in $FG_ROOT/Scenery but you may have scenery in other directories and listed in the scenery path ($FG_SCENERY; see Howto: Install scenery). Under each scenery directory, you will find directories called Objects and Terrain. Objects associated with airports are usually listed in a .stg file under "Terrain"; other objects are put under "Objects". The files under Objects and Terrain are organized in directories that group tiles into larger and smaller quadrants. Thus, if the tile number is 942058, you will find a file called 942058.stg in the directory $FG_Root/Scenery/Objects/w130n30/w123n37/.

There is generally more than one .stg file for a given tile, in different directories, because scenery can be stored in more than one place. It's important to describe your new object in a .stg file that will actually be read by flightgear (see below). It is recommended that you create a personal customized scenery directory separate from the standard installed scenery. That way, when you upgrade FG your customizations won't get overwritten. If you create such a directory, list it first in $FG_SCENERY, create a directory structure inside it parallel to the one in the standard scenery directory, and create a .stg file in the appropriate place. Similarly, it is best not to edit the .stg files in the folder where TerraSync stores the scenery it has fetched, since TerraSync may overwrite them with newer versions.

Step 6

Add a line like the following to the .stg file you've chosen, replacing the parameters with your own :

OBJECT_SHARED Models/MyModels/MyModel.xml -55.5 30.3 1000.0 0.00 

In brief, the format is :

type path longitude latitude elevation heading

There are more details on the .stg file format below.

Step 7

Restart FG and fly to where you added the model (or use command line options to start it with that location as the initial location); it should be there. Check its location and orientation, make any necessary changes in the .stg file, then exit and restart FG to check it again.

STG files

There is documention for the .stg files used by FlightGear in $FG_ROOT/Docs/README.scenery. Only information relevant for placing shared objects is included here.

Scenery files are loaded by default from $FG_ROOT/Scenery. Alternate locations (a "scenery path") can be specified in $FG_SCENERY (or from the command line); the first-named directories have highest priority. Thus, if you create a local directory for storing custom scenery you create, include it first in the scenery path.

Lines in a .stg file which describe shared objects look like this:

OBJECT_SHARED Models/Misc/trigpoint.xml -122.377127 37.71570833 1.756719854 20
type filename path longitude latitude elevation heading
  • Most of the time you'll use OBJECT_SHARED for a shared model. (If you have a one-of-a-kind object, you should use OBJECT_STATIC instead; see an explanation of it in $FG_ROOT/Docs/README.scenery.)
  • The filename path points to the file that contains the model; for the OBJECT_SHARED type, this is relative to the $FG_ROOT directory. Specify the XML file for the model if there is one, otherwise the .ac file.
  • Latitude and longitude are expressed as decimal numbers (not degrees/minutes/seconds), with negative values representing west and south.
  • Elevation is in meters above mean sea level (not feet, as is stated in some other places in the wiki)
  • Rotation is counter-clockwise from north (not clockwise as in the rest of FG).

Some more examples:

OBJECT_SHARED Models/MidAtl/cape-may-light.ac   -74.959970 38.933332 -93.0 0.00
OBJECT_SHARED Models/Airport/windsock.xml -122.360843 37.613877 1 0
OBJECT_SHARED Models/Structures/vordme.xml -122.37389 37.61948 -0.404 0

XML files

Alternately, there is a way to specify this same information in XML configuration files that are loaded at runtime; see Howto: Place 3D objects with the UFO or $FG_ROOT/Docs/README.scenery for more details. This approach has the advantage of keeping your new scenery clearly separate from the standard scenery files without having to create your own custom scenery directory structure. Further, you can then manually control whether or not to load it at run-time, using the --config option on the command line. You can also include it in one of the standard startup files (such as .fgfsrc) but this will load it into memory every time you start FG, whether or not you are flying in the area. If you place the scenery information in .stg files, it is only loaded into memory when needed.