GetImage

GetImage is a program that fetches and manipulates orthophotos for X-Plane scenery.  An orthophoto is a picture of the Earth that is aligned to tile well on a terrain mesh.

Warning

GetImage is really a random pile of utilities that have been useful in developing Logan Airport scenery; it is not as easy to use or well-thought-out as the other tools.   I am distributing GetImage to save people time, but I do not specifically endorse Orthophoto-based scenery as the best way to create scenery.  I believe that for the best future compatibility authors should focus on custom objects.

Using GetImage - The Worlds Worst User Interface

To put it bluntly, GetImage may have the worst user interface I have ever written in my life.  GetImage is basically a cheap way for me to access library code I've written for X-Plane, but since I do not believe that working with .env files and orthophotos represents the future of x-plane scenery, I have not invested any time in the UI.  Here is what you need to know to survive using GetImage:
To use GetImage, you drag a text script file (.txt) with commands and optionally a .env file into the GetImage window at the same time.  GetImage will go through the script file running each command.  See the end of this document for examples of using the commands.

GetImage will read either PNG, BMP or TIF files.  To control what kind of files GtImage creates, pick either PNG or BMP from the GetImage settings menu.

Image File Format Notes

GetImage can read three file formats: BMP, PNG and TIFF.  In order to identify the file formats, the files extensions must be .bmp, .png, or .tif respectively.  GetImage can write two file formats, BMP and PNG, based on a menu selection.  All bitmaps must be 24-bit Windows-style bitmaps, just like in X-Plane.

PNG and TIF files may have an alpha channel.  In X-Plane 7 custom scenery textures with alpha show water through the alpha channel.  Magenta is not turned into alpha in a .BMP file, so if you need to cut out water from scenery, use PNG.  (PNG is probably a better file format anyway because it takes less space on disk.)

GetImage can also use GeoTIFF files.  A GeoTIFF file is a regular TIFF file with additional metadata indicating where on the earth the image is from. Some orthophotos and satelite imagery (for example, LandSat imagery) come as GeoTIFF files.  When working with GeoTIFF files, you can apply them to scenery without knowing their corner locations; GetImage will extract and use this information automatically.

Warning: Photoshop and other programs may strip GeoTIFF information from a TIFF file.  If you edit a GeoTIFF file and can no longer apply it without providing coordinates manually, you can use the third syntax of the USE_IMAGE command to use coordinate data from one GeoTIFF file and image data from another.

GetImage Commands

The GetImage command file has one command per line, and comments starting with the number sign ('#').  

GetImage keeps the .env file you drag onto it in memory.  Some commands modify this in-memory version; the file is only read into memory when you use the READ command or written back when you use the WRITE command.  If you try to manipulate the in-memory version without a former READ command, GetImage will not work.

For commands that download orthophotos, they are always black and white, must be 1 or 4 pixels per meter, and are only available for the US.  If an orthophoto is out of bounds for the database, no file will be created.  You may need to reduce rectangles to not feature too much oceanic area since this area is not in the database.

READ

The read command consists of the following line.
READ
This instructs GetImage to copy the env file into memory.  This file is provided explicitly so you can read the file into memory, alter it (creating bitmaps in the process), and then read it again, undoing the in-memory changes you made.  Generally it is a good idea to start any script file with a READ command.

SQUARE

The square command changes the shape of the grid to be perfectly square.  You specify the area in vertex numbers as follows:
SQUARE <west> <south> <east> <north>
East-west squares are numbered 0 to 150, south-north squares are numbered 0 to 200.  Since this command works on vertices, the command SQUARE 50 20 51 21 squarifies exactly one square (since the top right vertex is one more than the bottom left, surrounding one square).

Use the square command to normalize a mesh before applying textures to it; the apply commands can stretch bitmaps to match a mesh, but this process often creates problems.  It is better to squarify the mesh first.

Example:
SQUARE 50 100 150 150
This command squarifies an area on the East side of the env in the north-south center.

FETCH

The fetch command downloads an orthophoto that at least covers the bounds specified. The format is:
FETCH <filename> <south> <west> <north> <east> <scale> [<max dimensions>]
The scale is meters per pixel, either 1 or 4.  The bounds are specified in latitude and longitude.  Two files are created.  A bitmap file contains the actual image; a .geo file is created.  This is a text file specifying the actual coordinates of the image.  Since the image is made of complete orthophoto tiles, the corners will not be aligned to latitude or longitude lines and the bounds will be slightly larger than what you specify.
Example:
FETCH KBOS   42.34819 -71.03394 42.38163 -70.97947 4
This file downloads an area surrounding Logan airport at 4 ppm to a file called KBOS.bmp.  The max dimensions parameter is optional and restricts the size of the bitmap.  If the bitmap is larger, it will be scaled.  Uset his parameter to keep bitmaps <= 1024 pixels for WorldMaker.  If this parameter is missing, the bitmap will be at its true pixels-per-meter scale.

APPLY

The apply command downloads orthophotos, crops and stretches them, saves them to disk and applies them to the current scenery.  The format of the apply command is:
APPLY <ppm> <x> <y> <stretch> <file name> <texture_size>
The pixels per meter is the resolution of the original photo before cropping stretching and scaling.  This can be 1 or 4 ppm.  By picking low res (4 pixels per meter) the download will be faster, but make sure you download a high enough resolution to stretch or crop properly.  The X and Y are the numbers of the lower left quad to apply the texture to; stretch is the stretch factor (1 applies to a single quad, 2 to a 2x2).  Texture size is the size of the final texture in pixels; it must be a power of 2 between 4 and 1024.

Example:
APPLY 4 145 68 5 tex1 256
This line applies the texture "tex1" to a 5x5 area starting at 145, 68 in the current .env file.  The original texture will be 5 mpp, and the final texture will be 256x256.

The texture is aligned to the quads that are specified; by squaring those quads you will get better texture stretching, so the above line could be preceded by a square command:
SQUARE 145 68 150 73
The following table shows what resolutions to use:


 Final Bitmap Size
Terrain Stretch Factor
 4
 8
 16
 32
 64
 128
 256
 512
 1024
1
 4
 4
 4
 4
 4
 1
 1
 1
 1*
2
 4
 4
 4
 4
 4
 4
 1
 1
 1
3
 4
 4
 4
 4
 4
 4
 4
 1
 1
4
 4
 4
 4
 4
 4
 4
 4
 1
 1
5
 4
 4
 4
 4
 4
 4
 4
 1
 1
6
 4
 4
 4
 4
 4
 4
 4
 4
 1
7
 4
 4
 4
 4
 4
 4
 4
 4
 1
8
 4
 4
 4
 4
 4
 4
 4
 4
 1
9
 4
 4
 4
 4
 4
 4
 4
 4
 4
10
 4
 4
 4
 4
 4
 4
 4
 4
 4

Apply will also take the square of tiles that the textures are applied to and straighten their internal lines.

AUTO_APPLY

The auto-apply command is similar to the apply command except auto-apply names the files automatically and picks the source resolution for you.  The syntax is:
AUTO_APPLY <x> <y> <stretch_factor> <final texture pixel size>
Example: the above command could have been done:
AUTO_APPLY 145 68 5 256
The texture would be named 145_68.bmp.  Tip: you can rename all of the textures in bulk using Env2CVS.

USE_IMAGE

The use-image command allows you to place one large orthophoto into your scenery file as many custom bitmaps.  The orthophoto must be in .bmp or .png format, and must be in the same directory as the script file.  The format of the USE_IMAGE command is one of:
USE_IMAGE <filename> <sw_lat> <sw_lon> <nw_lat> <nw_lon> <ne_lat> <ne_lon> <se_lat> <se_lon>
USE_IMAGE <filename>
USE_IMAGE <filename> <ref filename>
The fileanme must be a bitmap, TIFF or PNG file (without the extension) in the same directory as the script file.  There are three ways to specify the coordinates of the reference image:
  1. In the first syntax with 9 parameters, the four corners of the image are specified as latitude and longitude.  This overrides any referencing information written into the filename itself, and works with any file format (PNG, TIFF or BMP).
  2. In the second syntax, only a filename is given; the file must be a GeoTIFF image.  The image will be placed at the proper location based on its georeferencing information when it is chopped.  This is ideal when working with GeoTIFF images.
  3. In the third syntax, the first file is used for its image, and the second file is used for its location.  The second file must be a GeoTIFF file.  If the files are not the same size, the first file is effectively stretched so that its corners are anchored at the corners of the second file.  Since PhotoShop strips GeoTIFF information when it resaves a TIFF file, this allows you to edit a GeoTIFF file (for example, to apply color correction) but then use the original file's information to align the image.
If you use the Fetch command to get an orthophoto, these coordinate swill be saved in a .geo file that you can copy.  For other image formats you must determine the coordinates yourself.  Some examples:
USE_IMAGE KBOS 42.340527 -71.039421 42.383728 -71.040817 42.384918 -70.972832 42.341717 -70.971481
USE_IMAGE MyGeoTiffFile
USE_IMAGE LandSatColorCorrected LandSatOriginal
This first command would align the bitmap KBOS.png or KBOS.bmp over KBOS (Boston Logan Airport).  The second and third would apply GeoTIFF files.

APPLY_IMAGE

Once you have specified an image file and its' alignment using the USE_IMAGE command, use the APPLY_IMAGE command to create custom textures out of pieces of the reference image.  Each APPLY_IMAGE command creates one custom terrain texture bitmap (covering anywhere from 1x1 to 10x10 scenery tiles) out of a part of the reference image.  The reference image is automatically cut based on the location of the reference image (from the USE_IMAGE) command and the location of the actual scenery quads, producing aligned custom scenery textures.  The format is:
APPLY_IMAGE <x> <y> <stretch> <filename> <resolution>
where x and y are the number of the lower left quad to apply the texture to, stretch is the number of quads in each direction, file name is the name of the bitmap to be created (without extension - png or bmp is added depending on your menu settings) and resolution is the size of the final bitmap in pixels, which must be a power of 2.  For Example:
APPLY_IMAGE 147 68 3 test1 256
This example will put a custom texture over the south end of KBOS (assuming that a READ and USE_IMAGE have been applied and you've dragged the KBOS .env file onto GetImage):

MERGE

IMPORTANT: It is very easy to create very very very big bitmaps with the MERGE command.  If you need to contiguously edit or colorize a discontinuous area (for example, the river banks of a winding set of rivers), use multiple MERGE commands to create a few large bitmaps and then hand-place the few bitmaps in photoshop, rather than creating one large merged bitmap with "unused space" in the middle.

The merge command combines all of the custom bitmaps from an area of an .env file into one large bitmap.  The syntax is:
MERGE <west> <south> <east> <north> <resolution_per_quad> <file name>
The dimensions of the merge area are specified as quad numbers, just like the SQUARE command.  You can merge any area; the final created bitmap does not have to be a power of 2.  The resolution per quad should be the resolution of each custom texture.  Merge copies each of the custom textures from the specified area to the larger bitmap.  Areas that have land use textures are left black.

Example:
MERGE 145 68 149 72 256 combined_logan.bmp
This would take all of the custom textures in a 5x5 area and make one big 1024x1024 texture.
You can use the merge command to create a single large bitmap that can be easily edited with photoshop.

UNMERGE

The unmerge command takes the same syntax as the merge command, but performs the opposite action.  Sections of the large bitmap are copied into the smaller bitmaps used in the .env file.  WARNING: this command will alter the bitmaps used in the .env file; make backups before using this command to prevent a loss of data.  The syntax is:
UNMERGE <west> <south> <east> <north> <resolution_per_quad> <file name>

WRITE

The write command writes the changes to the .env file (mostly changes in the mesh shape) back to a new .env file.  Without using the WRITE command, no new .env file is created, and the application of textures is not stored.  The format is:
WRITE
The write command produces an env file with the phrase _new inserted.

Typical Uses for GetImage

Here are a few possible uses for GetImage:

Creating Reference Orthophoto Scenery

Sometimes it is desirable to see what is on the ground in real life while working on scenery, for example, while editing an airport taxiway layout or placing objects.  Use the READ, SQUARIFY, AUTO_APPLY, and WRITE commands to download black and white satelite images into your scenery.

Use this scenery to work in WorldMaker while seeing the satelite photos, then throw out the scenery later when done with work, or replace the textures with other image data.  If you have placed objects, you can use Env2CSV to copy the object placements from this scenery to your master version.

The idea of this scenery is that by having the satelite image as terrain textures in WorldMaker, the satelite image stays aligned at any zoom level and scrolling position in WorldMaker while you place objects or edit runways.

Creating Satelite Photo Scenery

If you want to create satelite-photo-based scenery, use the READ, SQUARIFY, USE_IMAGE, APPLY_IMAGE and WRITE commands to chop up a bitmap and apply it to scenery.  If you do not have satelite-based images to start with, use the FETCH command to download one, then colorize or edit it yourself.

Editing Already-Made Orthophoto Scenery

If you already have orthophoto scenery, you can use the READ, MERGE, and then READ, UNMERGE commands to combine the bitmaps into one large bitmap for easy color correction or editing in photoshop, then copy the results back into the individual bitmaps.