1FAQ
2===
3
4**Sections:**
5
6* `Common Usage`_
7* `Other Terrain Formats`_
8* `Community and Support`_
9* `Licensing`_
10
11
12----
13
14Common Usage
15------------
16
17How do I place a 3D model on the map?
18.....................................
19
20    The ``osgEarth::GeoTransform`` class inherits from ``osg::Transform``
21    and will convert map coordinates into OSG world coordinates for you.
22    Place an object at a geospatial position like this::
23
24        GeoTransform* xform = new GeoTransform();
25        GeoPoint point(srs, -121.0, 34.0, 1000.0);
26        xform->setPosition(point);
27
28    If you want your object to automatically clamp to the terrain surface,
29    assign a terrain and leave off the altitude::
30
31        GeoTransform* xform = new GeoTransform();
32        xform->setTerrain(mapNode->getTerrain());
33        GeoPoint point(srs, -121.0, 34.0);
34        xform->setPosition(point);
35
36
37I loaded a model, but it has no texture/lighting/etc. in osgEarth. Why?
38.....................................................................
39
40    Everything under an osgEarth scene graph is rendered with shaders.
41    So, when using your own models (or creating geometry by hand) you
42    need to create shader components in order for them to render properly.
43
44    osgEarth has a built-in shader generator for this purpose. Run the
45    shader generator on your node like so::
46
47        osgEarth::Registry::shaderGenerator().run( myNode );
48
49    After that, your node will contain shader snippets that allows osgEarth
50    to render it properly and for it to work with other osgEarth features
51    like sky lighting.
52
53
54Lines or Annotations (FeatureNode, etc.) are not rendering. Why?
55................................................................
56
57    Lines render using a shader that requires some initial state to be set.
58    You can apply this state to your top-level camera (or anywhere else
59    above the geometry) like so:
60
61        #include <osgEarth/GLUtils>
62        ...
63        GLUtils::setGlobalDefaults(camera->getOrCreateStateSet());
64
65    For Annotations (FeatureNodes, PlaceNodes, etc.) best practice is to place
66    an Annotation node as a descendant of the MapNode in your scene graph.
67    You can also add them to an AnnotationLayer and add that layer to the Map.
68
69    Annotations need access to the MapNode in order to render properly. If you
70    cannot place them under the MapNode, you will have to manually install a few
71    things to make them work::
72
73        #include <osgEarth/CullingUtils>
74        #include <osgEarth/GLUtils>
75        ...
76
77        // Manully assign the MapNode to your annotation
78        annotationNode->setMapNode(mapNode);
79
80        // In some group above the annotation, install this callback
81        group->addCullCallback(new InstallViewportSizeUniform());
82
83        // In some group above the annotation, set the GL defaults
84        GLUtils::setGlobalDefaults(group->getOrCreateStateSet());
85
86    Again: MapNode does all this automatically so this is only necessary if you do
87    not place your annotations as descendants of the MapNode.
88
89
90How do make the terrain transparent?
91....................................
92
93    By default, the globe will be opaque white when there are no image layers, or when all the image
94    layers have their opacities set to zero. To make the underlying globe transparent, set the
95    base color of the terrain to a transparent color like so::
96
97        <map>
98            <options>
99                <terrain color="#ffffff00" ...
100
101    In code, this option is found in the ``RexTerrainEngineOptions`` class::
102
103        #include <osgEarthDrivers/engine_mp/RexTerrainEngineOptions>
104        using namespace osgEarth::Drivers::RexTerrainEngine;
105        ...
106        RexTerrainEngineOptions options;
107        options.color() = osg::Vec4(1,1,1,0);
108
109
110How do I set the resolution of terrain tiles?
111.............................................
112
113    Each tile is a grid of vertices. The number of vertices can vary depending on source data
114    and settings. By default (when you have no elevation data) it is an 17x17 grid, tessellated
115    into triangles.
116
117    You can expressly set the terrain's tile size by using the Map options.
118    osgEarth will then resample all elevation data to the size you specify.
119    You will get best results from a tile size that is a power of 2 plus 1::
120
121        <map>
122            <options>
123                <terrain>
124                    <tile_size>9</tile_size>
125                    ...
126
127
128----
129
130Other Terrain Formats
131---------------------
132
133Does osgEarth work with VirtualPlanetBuilder?
134.............................................
135
136	VirtualPlanetBuilder_ (VPB) is a command-line terrain generation tool. Before osgEarth
137	came along, VPB	was probably the most-used open source tool for building terrains for
138	OSG appliations. We	mention is here because many people ask questions about loading
139	VPB models or transitioning from VPB to osgEarth.
140
141	osgEarth differs from VPB in that:
142
143	* VPB builds static terrain models and saves them to disk. osgEarth generates terrain on
144	  demand as your application runs; you do not (and cannot) save a model to disk.
145	* Changing a VPB terrain generally requires that you rebuild the model. osgEarth does not
146	  require a preprocessing step since it builds the terrain at run time.
147	* osgEarth and VPB both use *GDAL* to read many types of imagery and elevation data from
148	  the local file system. osgEarth also supports network-based data sources through its
149	  plug-in framework.
150
151	osgEarth has a *VPB driver* for "scraping" elevation and imagery tiles from a VPB model.
152    Confiugration of this driver is quite tricky and requires you to understand the details
153    of how VPB models are organized. You're on your own.
154
155	**Please Note** that this driver only exists as a **last resort** for people that have a VPB
156	model but no longer have access to the source data from which it was built. If at all
157	possible you should feed your source data directly into osgEarth instead of using the VPB
158	driver.
159
160
161Can osgEarth load TerraPage or MetaFlight?
162..........................................
163
164	osgEarth cannot load TerraPage (TXP) or MetaFlight. However, osgEarth does have a
165	"bring your own terrain" plugin that allows you to load an external model and use it as your
166	terrain. The caveat is that since osgEarth doesn't know anything about your terrain model, you
167	will not be able to use some of the features of osgEarth (like being able to add or remove layers).
168
169	For usage formation, please refer to the ``byo.earth`` example in the repo.
170
171.. _VirtualPlanetBuilder:	http://www.openscenegraph.com/index.php/documentation/tools/virtual-planet-builder
172
173
174----
175
176Community and Support
177---------------------
178
179What is the best practice for using GitHub?
180...........................................
181
182	The best way to work with the osgEarth repository is to make your own clone on GitHub
183	and to work from that clone. Why not work directly against the main repository? You
184	can, but if you need to make changes, bug fixes, etc., you will need your own clone
185	in order to issue Pull Requests.
186
187	1. Create your own GitHub account and log in.
188	2. Clone the osgEarth repo.
189	3. Work from your clone. Sync it to the main repository periodically to get the
190	   latest changes.
191
192
193How do I submit changes to osgEarth?
194....................................
195
196	We accept contributions and bug fixes through GitHub's `Pull Request`_ mechanism.
197
198	First you need your own GitHub account and a fork of the repo (see above). Next,
199	follow these guidelines:
200
201	1. Create a *branch* in which to make your changes.
202	2. Make the change.
203	3. Issue a *pull request* against the main osgEarth repository.
204	4. We will review the *PR* for inclusion.
205
206	If we decide NOT to include your submission, you can still keep it in your cloned
207	repository and use it yourself. Doing so maintains compliance with the osgEarth
208	license since your changes are still available to the public - even if they are
209	not merged into the master repository.
210
211.. _Pull Request:   https://help.github.com/articles/using-pull-requests
212
213
214Can I hire someone to help me with osgEarth?
215............................................
216
217    Of course! We at Pelican Mapping are in the business of supporting users of
218    the osgEarth SDK and are available for contracting, training, and integration
219    services. The easiest way to get in touch with us is through our web site
220    `contact form`_.
221
222    Pelican also offers a `Priority Support`_ package that is a good fit for
223    companies that prefer to do most of their development in-house.
224
225.. _contact form:     http://pelicanmapping.com/?page_id=2
226.. _Priority Support: http://web.pelicanmapping.com/priority-support/
227
228
229----
230
231Licensing
232---------
233
234Can I use osgEarth in a commercial product?
235...........................................
236
237	Yes. The license permits use in a commercial product. The only requirement is that
238	any changes you make to the actual osgEarth library *itself* be made available
239	under the same license as osgEarth. You do *not* need to make other parts of your
240	application public.
241
242
243Can I use osgEarth in an iOS app?
244.................................
245
246	Yes. Apple's policy requires only statically linked libraries. Technically, the
247	LGPL does not support static linking, but we grant an exception in this case.
248