Planettool - Revision history

Another commander: /* Links */

2020-04-23T14:35:51Z

‎Links

Another commander: /* Links */

2020-04-23T14:34:26Z

‎Links

Svengali: /* Links */

2012-06-05T20:39:12Z

‎Links

Svengali: added category -> Oolite_utilities

2012-02-08T19:34:18Z

added category -> Oolite_utilities

Ahruman: /* Projections */ Added XYZ label images.

2010-05-02T18:38:12Z

‎Projections: Added XYZ label images.

Ahruman at 22:24, 28 April 2010

2010-04-28T22:24:01Z

Ahruman at 22:04, 28 April 2010

2010-04-28T22:04:05Z

Ahruman: Created page with ''''planettool''' is a tool for working with textures for planets. Its main purpose is to convert {{wp2|Equirectangular_projection|equirectangular projection}} textures to {{wp2|C…'

2010-04-28T21:57:48Z

Created page with ''''planettool''' is a tool for working with textures for planets. Its main purpose is to convert {{wp2|Equirectangular_projection|equirectangular projection}} textures to {{wp2|C…'

New page

'''planettool''' is a tool for working with textures for planets. Its main purpose is to convert {{wp2|Equirectangular_projection|equirectangular projection}} textures to {{wp2|Cube_mapping|cube map}} textures. It was developed for Oolite, but should work anywhere you need planet textures or cube maps. It is available from [http://developer.berlios.de/project/showfiles.php?group_id=3577 the Oolite file repository]. It comes in two forms: a cross-platform command line tool, and a graphical application for Mac OS X only.

== 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 {{wp|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|projections]] listed below.

The additional options are:
* <code>--size (-S)</code>: The size of the output file, in pixels. For <code>cube</code> and <code>cubex</code> types, this is the size of each edge. For the <code>latlong</code> 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.
* <code>--fast (-F)</code>: Use faster, lower-quality rendering. Useful for previewing options.
* <code>--jitter (-J)</code>: 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.
* <code>--flip (-L)</code>: Mirror the texture through the YZ plane of the projection sphere. This corresponds to mirroring a latlong texture horizontally:<br />[[Image:planettool-flip.png]]<br />Oolite requires cube map textures to be flipped.
* <code>--rotate <rx> <ry> <rz> (-R)</code>: 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° E longitude to 0° latitude 90° W longitude. – on Earth, [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia] to [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands].
** The Y axis corresponds to a line from 90° N latitude to 90° S latitude – that is, the planet’s axis of rotation.
** The Z axis corresponds to a line from 0° latitude 0° longitude to 0° latitude 180° longitude – [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 the Gulf of Guinea] to [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific].
* <code>--sixteen-bit</code>: The output image is saved as a sixteen-bit-per-channel picture (that is, 64 bits per pixel).

== Usage (Mac OS X) ==
[[Image:planettool-mac-gui-0.4.2.png|thumb]]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.

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|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:<br />[[Image:planettool-flip.png]]<br />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. 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° E longitude to 0° latitude 90° W longitude. – on Earth, [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia] to [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands].
** The Y axis corresponds to a line from 90° N latitude to 90° S latitude – that is, the planet’s axis of rotation.
** The Z axis corresponds to a line from 0° latitude 0° longitude to 0° latitude 180° longitude – [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 the Gulf of Guinea] to [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific].
* 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 ==
=== Equirectangular (Latitude/Longitude) ===
[[Image:planettool-grid-latlong.png|128x64px]] [[Image:planettool-world-latlong.jpg|128x64px]]

Command line name: <code>latlong</code>

In the {{wp2|Equirectangular_projection|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 ===
[[Image:planettool-grid-cube.png|32x192px]] [[Image:planettool-world-cube.jpg|32x192px]]

Command line name: <code>cube</code>

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) ===
[[Image:planettool-grid-cubex.png|128x96px]] [[Image:planettool-world-cubex.jpg|128x96px]]

Command line name: <code>cubex</code>

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 ===
[[Image:planettool-grid-mercator.png|128x128px]] [[Image:planettool-world-mercator.jpg|128x128px]]

Command line name: <code>mercator</code>

The main feature of the {{wp2|Mercator_projection|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 ===
[[Image:planettool-grid-gall-peters.png|128x81px]] [[Image:planettool-world-gall-peters.jpg| 128x81px]]

Command line name: <code>gall-peters</code>

Another real-word map projection, the {{wp2|Gall–Peters_projection|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.

[[Category:Oolite]]

@@ Line 91: / Line 91: @@
 * [[Planetinfo.plist]] - custom data for systems in Oolite.
 * [[Materials_in_Oolite]] - further infos about textures in Oolite.
-* [[File:Planettool_1.0.1.zip.oxz]] - planettool v1.0.1 binary for Windows 64-bit. Once downloaded, remove the oxz extension and unzip normally.
+* [[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.
 [[Category:Oolite]] [[Category:Oolite_utilities]]

@@ Line 91: / Line 91: @@
 * [[Planetinfo.plist]] - custom data for systems in Oolite.
 * [[Materials_in_Oolite]] - further infos about textures in Oolite.
 [[Category:Oolite]] [[Category:Oolite_utilities]]

@@ Line 89: / Line 89: @@
 * [http://www.aegidian.org/bb/viewtopic.php?t=7843 Planettool announcement thread] on Oolite forum.
 * The world map image used for examples (warning: 2.2 MiB, 5400 × 2700 pixels): [http://veimages.gsfc.nasa.gov/7109/world.topo.bathy.200410.3x5400x2700.jpg world.topo.bathy.200410.3x5400x2700.jpg] from NASA:s [http://visibleearth.nasa.gov/view_set.php?categoryID=2363 Visible Earth: Blue Marble] collection.
 [[Category:Oolite]] [[Category:Oolite_utilities]]

← Older revision		Revision as of 19:34, 8 February 2012
Line 90:		Line 90:
	* The world map image used for examples (warning: 2.2 MiB, 5400 × 2700 pixels): [http://veimages.gsfc.nasa.gov/7109/world.topo.bathy.200410.3x5400x2700.jpg world.topo.bathy.200410.3x5400x2700.jpg] from NASA:s [http://visibleearth.nasa.gov/view_set.php?categoryID=2363 Visible Earth: Blue Marble] collection.		* The world map image used for examples (warning: 2.2 MiB, 5400 × 2700 pixels): [http://veimages.gsfc.nasa.gov/7109/world.topo.bathy.200410.3x5400x2700.jpg world.topo.bathy.200410.3x5400x2700.jpg] from NASA:s [http://visibleearth.nasa.gov/view_set.php?categoryID=2363 Visible Earth: Blue Marble] collection.

−	[[Category:Oolite]]	+	[[Category:Oolite]] [[Category:Oolite_utilities]]

@@ Line 41: / Line 41: @@
 == 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) and an image of the Earth, with no rotation or flip options selected.
+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) ===
-[[Image:planettool-grid-latlong.png|128x64px]]  [[Image:planettool-world-latlong.jpg|128x64px]]
+[[Image:planettool-grid-latlong.png|128x64px]]  [[Image:planettool-world-latlong.jpg|128x64px]]  [[Image:planettool-xyz-latlong.png|128x64px]]
 Command line name: <code>latlong</code>
@@ Line 51: / Line 51: @@
 === Cube ===
-[[Image:planettool-grid-cube.png|32x192px]]  [[Image:planettool-world-cube.jpg|32x192px]]
+[[Image:planettool-grid-cube.png|32x192px]]  [[Image:planettool-world-cube.jpg|32x192px]]  [[Image:planettool-xyz-cube.png|32x192px]]
 Command line name: <code>cube</code>
@@ Line 60: / Line 60: @@
 === Cube (Cross) ===
-[[Image:planettool-grid-cubex.png|128x96px]]  [[Image:planettool-world-cubex.jpg|128x96px]]
+[[Image:planettool-grid-cubex.png|128x96px]]  [[Image:planettool-world-cubex.jpg|128x96px]]  [[Image:planettool-xyz-cubex.png|128x96px]]
 Command line name: <code>cubex</code>
@@ Line 69: / Line 69: @@
 === Mercator ===
-[[Image:planettool-grid-mercator.png|128x128px]]  [[Image:planettool-world-mercator.jpg|128x128px]]
+[[Image:planettool-grid-mercator.png|128x128px]]  [[Image:planettool-world-mercator.jpg|128x128px]]  [[Image:planettool-xyz-mercator.png|128x128px]]
 Command line name: <code>mercator</code>
@@ Line 78: / Line 78: @@
 === Gall–Peters ===
-[[Image:planettool-grid-gall-peters.png|128x81px]]  [[Image:planettool-world-gall-peters.jpg| 128x81px]]
+[[Image:planettool-grid-gall-peters.png|128x81px]]  [[Image:planettool-world-gall-peters.jpg| 128x81px]]  [[Image:planettool-xyz-gall-peters.png| 128x81px]]
 Command line name: <code>gall-peters</code>

@@ Line 18: / Line 18: @@
 * <code>--flip (-L)</code>: Mirror the texture through the YZ plane of the projection sphere. This corresponds to mirroring a latlong texture horizontally:<br />[[Image:planettool-flip.png]]<br />Oolite requires cube map textures to be flipped.
 * <code>--rotate <rx> <ry> <rz> (-R)</code>: 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° E longitude to 0° latitude 90° W longitude. – on Earth, [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia] to [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands].
+** The X axis corresponds to a line from 0° latitude 90° W longitude to 0° latitude 90° E longitude – on Earth, [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands] to [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia].
-** The Y axis corresponds to a line from 90° N latitude to 90° S latitude – that is, the planet’s axis of rotation.
+** 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 0° longitude to 0° latitude 180° longitude – [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 the Gulf of Guinea] to [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific].
+** The Z axis corresponds to a line from 0° latitude 180° longitude to 0° latitude 0° longitude – [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific] to [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 the Gulf of Guinea].
 * <code>--sixteen-bit</code>: The output image is saved as a sixteen-bit-per-channel picture (that is, 64 bits per pixel).
 == Usage (Mac OS X) ==
-[[Image:planettool-mac-gui-0.4.2.png|thumb]]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.
+[[Image:planettool-mac-gui-0.4.2.png|thumb|alt=Screen shot of Planet Tool 0.4.2 for Mac OS X, showing a Mercator projection of the Earth taken at a 45° angle.|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.
 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.
@@ Line 30: / Line 30: @@
 * 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:<br />[[Image:planettool-flip.png]]<br />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. 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:
+* 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° E longitude to 0° latitude 90° W longitude. – on Earth, [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia] to [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands].
+** The X axis corresponds to a line from 0° latitude 90° W longitude to 0° latitude 90° E longitude – on Earth, [http://maps.google.com/maps?ll=0,-90&q=0,-90&z=4 the Gálapagos Islands] to [http://maps.google.com/maps?ll=0,90&q=0,90&z=4 the Indian Ocean west of Indonesia].
-** The Y axis corresponds to a line from 90° N latitude to 90° S latitude – that is, the planet’s axis of rotation.
+** 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 0° longitude to 0° latitude 180° longitude – [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 the Gulf of Guinea] to [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific].
+** The Z axis corresponds to a line from 0° latitude 180° longitude to 0° latitude 0° longitude – [http://maps.google.com/maps?ll=0,180&q=0,180&z=4 a rather boring bit of the Pacific] to [http://maps.google.com/maps?ll=0,0&q=0,0&z=4 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.
@@ Line 41: / Line 41: @@
 == 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) and the same image of the Earth, with no rotation or flip options selected.
+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) and an image of the Earth, with no rotation or flip options selected.
 === Equirectangular (Latitude/Longitude) ===