Difference between revisions of "Planettool"
(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…') |
Cholmondely (talk | contribs) (Tagged as an External Programme) |
||
(13 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | '''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 [ | + | '''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 [https://github.com/OoliteProject/planettool the GitHub]. It comes in two forms: a cross-platform command line tool, and a graphical application for Mac OS X only. |
+ | [[File:Planettool.png|right]]. There are also a test suite with separate Reference Renderings | ||
== Overview == | == Overview == | ||
Line 18: | Line 19: | ||
* <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>--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: | * <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 | + | ** 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 | + | ** 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 | + | ** 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). | * <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) == | == 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. 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. | 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 31: | ||
* 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. | * 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. | * 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 | + | * 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° | + | ** 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° | + | ** 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 | + | ** 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. | * 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. | * 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 42: | ||
== Projections == | == 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) === | === 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> | Command line name: <code>latlong</code> | ||
Line 49: | Line 52: | ||
=== Cube === | === 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> | Command line name: <code>cube</code> | ||
Line 58: | Line 61: | ||
=== Cube (Cross) === | === 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> | Command line name: <code>cubex</code> | ||
Line 67: | Line 70: | ||
=== Mercator === | === 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> | Command line name: <code>mercator</code> | ||
Line 76: | Line 79: | ||
=== Gall–Peters === | === 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> | Command line name: <code>gall-peters</code> | ||
Line 84: | Line 87: | ||
'''Note:''' the Gall–Peters projection can only be used for output. | '''Note:''' the Gall–Peters projection can only be used for output. | ||
− | [[Category:Oolite]] | + | == Links == |
+ | * [https://bb.oolite.space/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. | ||
+ | * [[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 === | ||
+ | *[https://bb.oolite.space/viewtopic.php?f=2&t=21259 Planet illumination user defined colors] ([[User:Another_commander|Another_commander]] 2022) | ||
+ | *[https://bb.oolite.space/viewtopic.php?f=2&t=8222 Planettool Question] (2010): "LatLong" sizes vs Cube Sizes | ||
+ | [[Category:Oolite]] [[Category:Oolite_utilities]] [[Category:Oolite External Programmes]] |
Latest revision as of 21:16, 25 July 2024
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
Contents
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. Forcube
andcubex
types, this is the size of each edge. For thelatlong
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)
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