Planettool

planettool is a tool for working with textures for planets. Its main purpose is to convert equirectangular projection textures to cube map textures. It was developed for Oolite, but should work anywhere you need planet textures or cube maps. It is available from the GitHub. It comes in two forms: a cross-platform command line tool, and a graphical application for Mac OS X only.

. There are also a test suite with separate Reference Renderings

Overview

The basic function of planettool is to read a texture map for a sphere in one coordinate system, and write it out in a different coordinate system (or the same one, if you really want to). It does this using high-resolution sphere domain supersampling and floating-point, linear-space colour blending for high quality output.

While doing this, planettool can also mirror and rotate the texture in 3-space.

Usage (command line)

planettool --input <inType> <inFile> --output <outType> <outputFile> [options]
planettool --generator grid1 --output <outType> <outputFile> [options]
planettool --help

planettool takes either an input file and type or a generator, and produces and output file of the specified type. In this context, “type” refers to the projections listed below.

The additional options are:

• --size (-S): The size of the output file, in pixels. For cube and cubex types, this is the size of each edge. For the latlong type, it’s the height of the output file. For the Mercator and Gall-Peters projections, it is the width of the output file. Broadly speaking, a given size value for a cube type provides twice as much overall detail as for the latlong type. Note that textures should always have power-of-two sizes.
• --fast (-F): Use faster, lower-quality rendering. Useful for previewing options.
• --jitter (-J): Use stochastic supersampling. This makes rendering much slower, but can eliminate certain types of aliasing artefacts (at the cost of added noise). Try this if you see noticeable artefacts caused by repeating patterns in the input file.
• --flip (-L): Mirror the texture through the YZ plane of the projection sphere. This corresponds to mirroring a latlong texture horizontally:
  
  Oolite requires cube map textures to be flipped.
• --rotate <rx> <ry> <rz> (-R): Rotate the texture around the projection sphere. Rotations are applied in the following order: first around the X axis, then around the Z axis, and last around the Y axis. If this is inconvenient, you can supply any number of --rotate (and --flip) options, which will be chained together. The axes are assigned as follows:
  • The X axis corresponds to a line from 0° latitude 90° W longitude to 0° latitude 90° E longitude – on Earth, the Gálapagos Islands to the Indian Ocean west of Indonesia.
  • The Y axis corresponds to a line from 90° S latitude to 90° N latitude – that is, the planet’s axis of rotation.
  • The Z axis corresponds to a line from 0° latitude 180° longitude to 0° latitude 0° longitude – a rather boring bit of the Pacific to the Gulf of Guinea.
• --sixteen-bit: The output image is saved as a sixteen-bit-per-channel picture (that is, 64 bits per pixel).

Usage (Mac OS X)

Planet Tool 0.4.2 for Mac OS X

For Mac OS X 10.5 and later, the command line tool may be used as above, but a normal graphical application named Planet Tool is also included. The rendering functionality is identical to the command line tool, but it has an interactive user interface with a live preview. The Mac version does not work on the newer Macs (because it is for 32-bit Macs?).

To use, open a PNG image in the normal fashion, or select “New Grid Generator” from the File menu. Planet Tool will guess at appropriate settings based on the size and shape of the input file, but you can change these settings as you wish.

• Input Format and Output Format: select source and target projections.
• Output Size: select the desired size of the output image. The meaning of this value depends on the output projection, and is explained in the caption. The stepper control changes the size in power-of-two increments – note that textures should always have power-of-two sizes.
• Flip: select to mirror the texture through the YZ plane of the projection sphere. This corresponds to mirroring a latlong texture horizontally:
  
  Oolite requires cube map textures to be flipped.
• Rotate: specify rotation of the texture around the projection sphere. Rotations are applied in the following order: first around the X axis, then around the Z axis, and last around the Y axis. The axes are assigned as follows:
  • The X axis corresponds to a line from 0° latitude 90° W longitude to 0° latitude 90° E longitude – on Earth, the Gálapagos Islands to the Indian Ocean west of Indonesia.
  • The Y axis corresponds to a line from 90° S latitude to 90° N latitude – that is, the planet’s axis of rotation.
  • The Z axis corresponds to a line from 0° latitude 180° longitude to 0° latitude 0° longitude – a rather boring bit of the Pacific to the Gulf of Guinea.
• Fast: select to use faster, lower-quality rendering. Useful for previewing options.
• Jitter: select to use stochastic supersampling. This makes rendering much slower, but can eliminate certain types of aliasing artefacts (at the cost of added noise). Try this if you see noticeable artefacts caused by repeating patterns in the input file.
• Preview pane: shows a fast rendering of the current options.

Once the appropriate options are selected, press the “Render…” button (or select “Render…” from the File menu) to render the image.

Projections

Each projection is shown with the grid generator (a grid with lines at ten-degree intervals of latitude and longitude, each 0.5 degrees wide), an image of the Earth, and labels identifying the cardinal directions, with no rotation or flip options selected.

Equirectangular (Latitude/Longitude)

Command line name: latlong

In the equirectangular projection, the intervals between pixels are constant steps of latitude and longitude. This is conceptually simple, but inefficent; lots of pixels are crammed together tightly near the poles.

Cube

Command line name: cube

The surface is divided into six equal areas, which are projected onto squares. These are then stacked vertically, in the following order: +x, -x, +y, -y, +z, -z. This is the format Oolite requires for cube maps.

Note: cube maps can be used as input, but support is currently incomplete. Artefacts will appear at the seams between cube faces.

Cube (Cross)

Command line name: cubex

The same projection as cube, but the squares are rearranged into a more human-friendly layout (which can be printed and folded into a cube if you're bored).

Note: cross cube maps can be used as input, but support is currently incomplete. Artefacts will appear at the seams between cube faces.

Mercator

Command line name: mercator

The main feature of the Mercator projection is that it preserves angles, making it the traditional projection for sailors and people who can't be bothered to choose a more appropriate projection for whatever they're doing. Since it wastes even more pixels near the poles than the equirectangular projection and doesn’t actually reach the poles at all, it’s entirely unsuitable for texturing, but could be useful if you want a wall map.

Note: the Mercator projection can only be used for output.

Gall–Peters

Command line name: gall-peters

Another real-word map projection, the Gall–Peters projection is a variety of cylindric equal-area projection, in which the proportions between different areas are preserved. This is a somewhat popular projection among people who want to make political points about the sizes of different countries, but not so much among cartographers, who prefer maps that give some idea of the shapes of things and can be used for navigation.

Note: the Gall–Peters projection can only be used for output.

Links

• Planettool announcement thread on Oolite forum.
• The world map image used for examples (warning: 2.2 MiB, 5400 × 2700 pixels): world.topo.bathy.200410.3x5400x2700.jpg from NASA:s Visible Earth: Blue Marble collection.
• Planetinfo.plist - custom data for systems in Oolite.
• Materials_in_Oolite - further infos about textures in Oolite.
• Media:Planettool_1.0.1.zip.oxz - planettool v1.0.1 binary for Windows 64-bit. Once downloaded, remove the oxz extension and unzip normally.

Discussions

• Planet illumination user defined colors (Another_commander 2022)
• Planettool Question (2010): "LatLong" sizes vs Cube Sizes