Imagery

#summary Imagery

The imagery we use in the WhirlyGlobe examples is derived from the [http://earthobservatory.nasa.gov/Features/BlueMarble/ Blue Marble Next Generation] data set. There are a variety of interesting data sets available, comprising different seasons, sizes, and a few different themes. These are good examples to start with, but you can use just about any imagery that falls within certain criteria.

Here's what your source image needs to be usable in WhirlGlobe.

• It needs to extend from -180 degrees to +180 in longitude (horizontal).
• Extend from -90 to +90 in latitude (vertical)
• Be sufficient resolution to match your use. Don't oversample.
• Degrees in either direction need to be square. For instance, halfway up the image is 0 degrees latitude.

If you can meet those requirements, you can put whatever you like on a globe. It doesn't have to be a real imagery. Fake maps work, night time imagery. Whatever.

WhirlyGlobe doesn't take just an image, though. It's expecting the data to be processed into an optimized form and organized with a plist. There's a program included in the source tree to do this for you.

==ImageChopper==

WhirlyGlobe is expecting imagery to be chopped up into uniform square units and various optimizations and preprocessing to be performed.

The optimal image format for OpenGL ES on ios devices is pvrtc. We just use the tex tool provided by Apple (which their vendor provides them) to convert. You can have ImageChopper do the conversion automatically.

To work around an odd edge condition with compressed imagery we create a border around each chopped image and make use of only the internal pixels. We do this by tweaking the texture coordinates deep within WhirlyGlobe, but we need to take it into account in processing the imagery.

The syntax of ImageChopper is like so: {{{ syntax: ./ImageChopper <in.img> [-outSize ] [-borderSize ] [-texTool ] }}}

The input image is whatever you've decided to use on your globe, adhering to the constraints above. There's no requirements on image size. We'll resample and that should turn out reasonably in most cases.

OutX and outY are the number of pieces to chop the input image into. The outSize parameter is the side size of the output images. This must always be a power of two and should be no more than 1024. Your input image should be at least (outX X outSize, outY X outSize) in pixels. If it's not, it will oversample.

The outName and outDir control the names of the output files and where the program puts them, respectively.

The border size controls the number of pixels around each output image used to deal with the compression issue. Obviously this affects how the input image is sampled, but if you're not doing something weird, don't worry about it.

Lastly, texTool is the path to the texture tool used for pvrtc compression. If you don't set this you'll get something non-optimal, so use it. This value would typically be: /Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/texturetool

Here's a typical example, from one of the sample apps: {{{ ../../ImageChopper/build/Debug/ImageChopper world.topo.bathy.200408.3_full.png 5 2 testImg testImg -outSize 512 -borderSize 16 -texTool /Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/texturetool }}}

That will get you a group of 5x2 images at 512 pixels each, with a border size of 16. It will invoke the texture compression tool and produce pvrtc files. In addition, you'll get a plist describing the data set.

To use these, add all the pvrtc files and the info plist to the resources for your app. You can ignore the regular image files. Give the name of the info file to WhirlyGlobe when constructing the spherical earth layer. It will do the rest.

==Imagery Info Format==

ImageChopper produces a plist file describing the processed imagery data set. We use a fairly simple set of key/value pairs. ImageChopper should do what you need, but if not feel free to write these yourself.

• baseName: The base name used in constructing image file names. We just tack on an _X_Y as needed.
• borderSize: The number of pixels we used to work around the edge compression problem. WhirlyGlobe needs this for setting texture coordinates.
• format: Ideally, this is pvrtc. If you need some other format, we can read anything UIImage can handle.
• pixelsSquare: Size of each size in an output image. Will always be square (obviously) and must be a power of two.
• tilesInX: Number of tiles (e.g. files) in longitude.
• tilesInY: Number of tiles in latitude.

== Future ==

We may do a replacement image scheme. We'll probably allow for images to be fetched remotely. We may even do image pyramids. In any case, we'll add fields to the info plist to govern all of that.