{
    "mode": "man",
    "parameter": "ppmforge",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/ppmforge/1/json",
    "generated": "2026-09-10T23:19:15Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "ppmforge - fractal forgeries of clouds, planets, and starry skies\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": [
                {
                    "name": "ppmforge",
                    "content": "[-clouds]  [-night]  [-dimension  dimen] [-hour hour] [-inclination|-tilt angle] [-mesh size]\n[-power factor] [-glaciers level] [-ice level] [-saturation sat] [-seed seed]  [-stars  frac‐\ntion] [{-xsize|-width} width] [{-ysize|-height} height]\n\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "This program is part of Netpbm(1).\n\nppmforge generates three kinds of ``random fractal forgeries,'' the term coined by Richard F.\nVoss  of the IBM Thomas J. Watson Research Center for seemingly realistic pictures of natural\nobjects generated by simple algorithms embodying randomness and fractal self-similarity.  The\ntechniques used by ppmforge are essentially those given by Voss[1],  particularly  the  tech‐\nnique of spectral synthesis explained in more detail by Dietmar Saupe[2].\n\nThe program generates two varieties of pictures: planets and clouds, which are just different\nrenderings  of  data  generated in an identical manner, illustrating the unity of the fractal\nstructure of these very different objects.  A third type of picture, a starry sky, is synthe‐\nsised directly from pseudorandom numbers.\n\nThe generation of planets or clouds begins with the preparation of an array of random data in\nthe frequency domain.  The size of this array, the ``mesh size,'' can be set with  the  -mesh\noption; the larger the mesh the more realistic the pictures but the calculation time and mem‐\nory  requirement  increases as the square of the mesh size.  The fractal dimension, which you\ncan specify with the -dimension option, determines the roughness of the terrain on the planet\nor the scale of detail in the clouds.  As the fractal dimension is increased, more high  fre‐\nquency components are added into the random mesh.\n\nOnce  the  mesh  is generated, an inverse two dimensional Fourier transform is performed upon\nit.  This converts the original random frequency domain data  into  spatial  amplitudes.   We\nscale the real components that result from the Fourier transform into numbers from 0 to 1 as‐\nsociated  with  each  point  on  the  mesh.  You can further modify this number by applying a\n``power law scale'' to it with the -power option.  Unity scale leaves the numbers unmodified;\na power scale of 0.5 takes the square root of the numbers in the mesh, while a power scale of\n3 replaces the numbers in the mesh with their cubes.  Power law scaling is best envisioned by\nthinking of the data as representing the elevation of terrain; powers less than 1 yield land‐\nscapes with vertical scarps that look like glacially-carved valleys; powers greater than  one\nmake  fairy-castle  spires  (which  require large mesh sizes and high resolution for best re‐\nsults).\n\nAfter these calculations, we have a array of the specified size containing numbers that range\nfrom 0 to 1.  ppmforge generates as follows:\n\nThe randomness in the image is limited before Netpbm 10.37 (December 2006) -- if you run  the\nprogram twice in the same second, you may get identical output.\n\n\n\nClouds A  color  map  is  created that ranges from pure blue to white by increasing admixture\n(desaturation) of blue with white.  Numbers less than 0.5 are  colored  blue,  numbers\nbetween  0.5  and  1.0  are colored with corresponding levels of white, with 1.0 being\npure white.\n\n\nPlanet The mesh is projected onto a sphere.  Values less than 0.5 are treated  as  water  and\nvalues  between 0.5 and 1.0 as land.  The water areas are colored based upon the water\ndepth, and land based on its elevation.  The random depth  data  are  used  to  create\nclouds  over  the  oceans.  An atmosphere approximately like the Earth's is simulated;\nits light absorption is calculated to create a  blue  cast  around  the  limb  of  the\nplanet.  A function that rises from 0 to 1 based on latitude is modulated by the local\nelevation  to  generate polar ice caps--high altitude terrain carries glaciers farther\nfrom the pole.  Based on the position of the star with respect to  the  observer,  the\napparent  color of each pixel of the planet is calculated by ray-tracing from the star\nto the planet to the observer and applying a lighting model that  sums  ambient  light\nand  diffuse reflection (for most planets ambient light is zero, as their primary star\nis the only source of illumination).  Additional random  data  are  used  to  generate\nstars around the planet.\n\n\nNight  A  sequence  of  pseudorandom  numbers is used to generate stars with a user specified\ndensity.\n\n\nCloud pictures always contain 256 or fewer colors and may be displayed on most  color  mapped\ndevices  without further processing.  Planet pictures often contain tens of thousands of col‐\nors which must be compressed with pnmquant or ppmdither before encoding  in  a  color  mapped\nformat.   If the display resolution is high enough, ppmdither generally produces better look‐\ning planets.  pnmquant tends to create discrete color  bands,  particularly  in  the  oceans,\nwhich are unrealistic and distracting.  The number of colors in starry sky pictures generated\nwith  the  -night  option depends on the value specified for -saturation.  Small values limit\nthe color temperature distribution of the stars and reduce the number of colors in the image.\nIf the -saturation is set to 0, none of the stars will be colored  and  the  resulting  image\nwill  never contain more than 256 colors.  Night sky pictures with many different star colors\noften look best when color compressed by pamdepth rather than  pnmquant  or  ppmdither.   Try\nnewmaxval  settings of 63, 31, or 15 with pamdepth to reduce the number of colors in the pic‐\nture to 256 or fewer.\n\n\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "In addition to the options common to all programs based on libnetpbm  (most  notably  -quiet,\nsee \u001b]8;;index.html#commonoptions\u001b\\ Common Options\u001b]8;;\u001b\\ ), ppmforge recognizes the following command line options:\n\nYou can abbreviate any options to its shortest unique prefix.\n\n\n",
            "subsections": [
                {
                    "name": "-clouds",
                    "content": "Generate  clouds.  An image of fractal clouds is generated.  Selecting clouds sets the\ndefault for fractal dimension to 2.15 and power scale factor to 0.75.\n\n"
                },
                {
                    "name": "-dimension _",
                    "content": "Sets the fractal dimension to the specified dimen, which may be any real  number  be‐\ntween  0  and  5 inclusive.  Higher fractal dimensions create more ``chaotic'' images,\nwhich require higher resolution output and a larger FFT mesh size to look good.  If no\ndimension is specified, the program uses 2.4 when  generating  planets  and  2.15  for\nclouds.\n\n"
                },
                {
                    "name": "-glaciers _",
                    "content": "The floating point level setting controls the extent to which terrain elevation causes\nice  to appear at lower latitudes.  The default value of 0.75 makes the polar caps ex‐\ntend toward the equator across high terrain and forms glaciers in  the  highest  moun‐\ntains,  as  on  Earth.   Higher values make ice sheets that cover more and more of the\nland surface, simulating planets in the midst of an ice age.  Lower values tend to  be\nboring, resulting in unrealistic geometrically-precise ice cap boundaries.\n\n"
                },
                {
                    "name": "-hour _",
                    "content": "When  generating a planet, ppmforge uses hour as the \"hour angle at the central merid‐\nian.\"  If you specify -hour 12, for example, the planet  will  be  fully  illuminated,\ncorresponding  to  high  noon  at  the longitude at the center of the screen.  You can\nspecify any floating point value between 0 and 24 for hour,  but  values  which  place\nmost  of the planet in darkness (0 to 4 and 20 to 24) result in crescents which, while\npretty, don't give you many illuminated pixels for the amount of computing that's  re‐\nquired.   If  no  -hour  option is specified, a random hour angle is chosen, biased so\nthat only 25% of the images generated will be crescents.\n\n"
                },
                {
                    "name": "-ice _",
                    "content": "Sets the extent of the polar ice caps to the given floating point level.  The  default\nlevel  of  0.4 produces ice caps similar to those of the Earth.  Smaller values reduce\nthe amount of ice, while larger -ice settings create more prominent ice caps.   Suffi‐\nciently  large  values,  such  as  100 or more, in conjunction with small settings for\n-glaciers (try 0.1) create \"ice balls\" like Europa.\n\n"
                },
                {
                    "name": "-inclination|-tilt _",
                    "content": "The inclination angle of the planet with regard to its primary star is set  to  angle,\nwhich  can  be  any floating point value from -90 to 90.  The inclination angle can be\nthought of as specifying, in degrees, the ``season'' the planet is  currently  experi‐\nencing or, more precisely, the latitude at which the star transits the zenith at local\nnoon.   If  0, the planet is at equinox; the star is directly overhead at the equator.\nPositive values represent summer in the northern hemisphere, negative values summer in\nthe southern hemisphere.  The Earth's inclination angle, for example, is about 23.5 at\nthe June solstice, 0 at the equinoxes in March and September, and -23.5 at the  Decem‐\nber  solstice.  If no inclination angle is specified, a random value between -21.6 and\n21.6 degrees is chosen.\n\n"
                },
                {
                    "name": "-mesh _",
                    "content": "A mesh of size by size will be used for the fast Fourier transform (FFT).   Note  that\nmemory  requirements and computation speed increase as the square of size; if you dou‐\nble the mesh size, the program will use four times the memory and run  four  times  as\nlong.   The  default  mesh is 256x256, which produces reasonably good looking pictures\nwhile using half a megabyte for the 256x256 array of single precision complex  numbers\nrequired by the FFT.  On machines with limited memory capacity, you may have to reduce\nthe  mesh  size to avoid running out of RAM.  Increasing the mesh size produces better\nlooking pictures; the difference becomes particularly noticeable when generating  high\nresolution images with relatively high fractal dimensions (between 2.2 and 3).\n\n"
                },
                {
                    "name": "-night",
                    "content": "stars that surround planet pictures, but the output consists exclusively of stars.\n\n"
                },
                {
                    "name": "-power _",
                    "content": "Sets the \"power factor\" used to scale elevations synthesised from the FFT  to  factor,\nwhich can be any floating point number greater than zero.  If no factor is specified a\ndefault  of 1.2 is used if a planet is being generated, or 0.75 if clouds are selected\nby the -clouds option.  The result of the FFT image synthesis is an array of elevation\nvalues between 0 and 1.  A non-unity power factor exponentiates each of  these  eleva‐\ntions  to  the  specified power.  For example, a power factor of 2 squares each value,\nwhile a power factor of 0.5 replaces each with its square root.  (Note that exponenti‐\nating values between 0 and 1 yields values that remain within that range.)  Power fac‐\ntors less than 1 emphasise large-scale elevation changes at the expense of small vari‐\nations.  Power factors greater than 1 increase the roughness of the terrain and,  like\nhigh fractal dimensions, may require a larger FFT mesh size and/or higher screen reso‐\nlution to look good.\n\n"
                },
                {
                    "name": "-saturation _",
                    "content": "Controls the degree of color saturation of the stars that surround planet pictures and\nfill  starry  skies  created with the -night option.  The default value of 125 creates\nstars which resemble the sky as seen by the human eye from Earth's surface.  Stars are\ndim; only the brightest activate the cones in the human retina, causing  color  to  be\nperceived.  Higher values of sat approximate the appearance of stars from Earth orbit,\nwhere  better dark adaptation, absence of skyglow, and the concentration of light from\na given star onto a smaller area of the retina thanks to the lack of atmospheric  tur‐\nbulence  enhances  the  perception of color.  Values greater than 250 create ``science\nfiction'' skies that, while pretty, don't occur in this universe.\n\nThanks to the inverse square law combined with Nature's love of mediocrity, there  are\nmany, many dim stars for every bright one.  This population relationship is accurately\nreflected in the skies created by ppmforge.  Dim, low mass stars live much longer than\nbright  massive stars, consequently there are many reddish stars for every blue giant.\nThis relationship is preserved by ppmforge.  You can reverse the proportion,  simulat‐\ning the sky as seen in a starburst galaxy, by specifying a negative sat value.\n\n"
                },
                {
                    "name": "-seed _",
                    "content": "Sets  the  seed  for the random number generator to the integer num.  The seed used to\ncreate each picture is displayed on standard output (unless suppressed with the -quiet\noption).  Pictures generated with the same seed will be identical.   If  no  -seed  is\nspecified, a random seed derived from the date and time will be chosen.  Specifying an\nexplicit seed allows you to re-render a picture you particularly like at a higher res‐\nolution or with different viewing parameters.\n\n"
                },
                {
                    "name": "-stars _",
                    "content": "Specifies  the  percentage  of  pixels,  in  tenths of a percent, which will appear as\nstars, either surrounding a planet or filling the entire frame if -night is specified.\nThe default fraction is 100.\n\n"
                },
                {
                    "name": "-xsize|-width _",
                    "content": "Sets the width of the generated image to width pixels.  The default width is 256  pix‐\nels.   Images  must  be  at  least  as wide as they are high; if a width less than the\nheight is specified, it will be increased to equal the height.  If  you  must  have  a\nlong  skinny image, make a square one with ppmforge, then use pamcut to extract a por‐\ntion of the shape and size you require.\n\n"
                },
                {
                    "name": "-ysize|-height _",
                    "content": "Sets the height of the generated image to height pixels.  The default  height  is  256\npixels.   If  the  height  specified exceeds the width, the width will be increased to\nequal the height.\n\n\n\n"
                }
            ]
        },
        "LIMITATIONS": {
            "content": "The algorithms require the output image to be at least as wide as it is high, and  the  width\nto be an even number of pixels.  These constraints are enforced by increasing the size of the\nrequested image if necessary.\n\nYou  may  have  to  reduce  the  FFT mesh size on machines with 16 bit integers and segmented\npointer architectures.\n\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "pamcut(1), pamdepth(1), ppmdither(1), pnmquant(1), ppm(1)\n\n\n\n[1]    Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw et. al., Fundamental Algo‐\nrithms for Computer Graphics, Berlin: Springer-Verlag, 1985.\n\n\n[2]    Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, New York:  Springer\nVerlag, 1988.\n\n\n\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "John Walker\nAutodesk SA\nAvenue des Champs-Montants 14b\nCH-2074 MARIN\nSuisse/Schweiz/Svizzera/Svizra/Switzerland\nUsenet:kelvin@Autodesk.com\nFax:038/33 88 15\nVoice:038/33 76 33\n\n\nPermission  to  use, copy, modify, and distribute this software and its documentation for any\npurpose and without fee is hereby granted, without  any  conditions  or  restrictions.   This\nsoftware is provided ``as is'' without express or implied warranty.\n\n",
            "subsections": [
                {
                    "name": "PLUGWARE!",
                    "content": "If you like this kind of stuff, you may also enjoy ``James Gleick's Chaos--The Software'' for\nMS-DOS,  available for $59.95 from your local software store or directly from Autodesk, Inc.,\nAttn: Science Series, 2320  Marinship  Way,  Sausalito,  CA  94965,  USA.   Telephone:  (800)\n688-2344  toll-free  or,  outside  the  U.S.  (415)  332-2344 Ext 4886.  Fax: (415) 289-4718.\n``Chaos--The Software'' includes a more comprehensive fractal forgery generator which creates\nthree-dimensional landscapes as well as clouds and planets, plus five more modules which  ex‐\nplore other aspects of Chaos.  The user guide of more than 200 pages includes an introduction\nby  James  Gleick  and detailed explanations by Rudy Rucker of the mathematics and algorithms\nused by each program.\n"
                }
            ]
        },
        "DOCUMENT SOURCE": {
            "content": "This manual page was generated by the Netpbm tool 'makeman' from  HTML  source.   The  master\ndocumentation is at\n\nhttp://netpbm.sourceforge.net/doc/ppmforge.html\n\nnetpbm documentation                        27 March 2021                    Ppmforge User Manual(1)",
            "subsections": []
        }
    },
    "summary": "ppmforge - fractal forgeries of clouds, planets, and starry skies",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Generate clouds. An image of fractal clouds is generated. Selecting clouds sets the default for fractal dimension to 2.15 and power scale factor to 0.75."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the fractal dimension to the specified dimen, which may be any real number be‐ tween 0 and 5 inclusive. Higher fractal dimensions create more ``chaotic'' images, which require higher resolution output and a larger FFT mesh size to look good. If no dimension is specified, the program uses 2.4 when generating planets and 2.15 for clouds."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "The floating point level setting controls the extent to which terrain elevation causes ice to appear at lower latitudes. The default value of 0.75 makes the polar caps ex‐ tend toward the equator across high terrain and forms glaciers in the highest moun‐ tains, as on Earth. Higher values make ice sheets that cover more and more of the land surface, simulating planets in the midst of an ice age. Lower values tend to be boring, resulting in unrealistic geometrically-precise ice cap boundaries."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "When generating a planet, ppmforge uses hour as the \"hour angle at the central merid‐ ian.\" If you specify -hour 12, for example, the planet will be fully illuminated, corresponding to high noon at the longitude at the center of the screen. You can specify any floating point value between 0 and 24 for hour, but values which place most of the planet in darkness (0 to 4 and 20 to 24) result in crescents which, while pretty, don't give you many illuminated pixels for the amount of computing that's re‐ quired. If no -hour option is specified, a random hour angle is chosen, biased so that only 25% of the images generated will be crescents."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the extent of the polar ice caps to the given floating point level. The default level of 0.4 produces ice caps similar to those of the Earth. Smaller values reduce the amount of ice, while larger -ice settings create more prominent ice caps. Suffi‐ ciently large values, such as 100 or more, in conjunction with small settings for -glaciers (try 0.1) create \"ice balls\" like Europa."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "The inclination angle of the planet with regard to its primary star is set to angle, which can be any floating point value from -90 to 90. The inclination angle can be thought of as specifying, in degrees, the ``season'' the planet is currently experi‐ encing or, more precisely, the latitude at which the star transits the zenith at local noon. If 0, the planet is at equinox; the star is directly overhead at the equator. Positive values represent summer in the northern hemisphere, negative values summer in the southern hemisphere. The Earth's inclination angle, for example, is about 23.5 at the June solstice, 0 at the equinoxes in March and September, and -23.5 at the Decem‐ ber solstice. If no inclination angle is specified, a random value between -21.6 and 21.6 degrees is chosen."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "A mesh of size by size will be used for the fast Fourier transform (FFT). Note that memory requirements and computation speed increase as the square of size; if you dou‐ ble the mesh size, the program will use four times the memory and run four times as long. The default mesh is 256x256, which produces reasonably good looking pictures while using half a megabyte for the 256x256 array of single precision complex numbers required by the FFT. On machines with limited memory capacity, you may have to reduce the mesh size to avoid running out of RAM. Increasing the mesh size produces better looking pictures; the difference becomes particularly noticeable when generating high resolution images with relatively high fractal dimensions (between 2.2 and 3)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "stars that surround planet pictures, but the output consists exclusively of stars."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the \"power factor\" used to scale elevations synthesised from the FFT to factor, which can be any floating point number greater than zero. If no factor is specified a default of 1.2 is used if a planet is being generated, or 0.75 if clouds are selected by the -clouds option. The result of the FFT image synthesis is an array of elevation values between 0 and 1. A non-unity power factor exponentiates each of these eleva‐ tions to the specified power. For example, a power factor of 2 squares each value, while a power factor of 0.5 replaces each with its square root. (Note that exponenti‐ ating values between 0 and 1 yields values that remain within that range.) Power fac‐ tors less than 1 emphasise large-scale elevation changes at the expense of small vari‐ ations. Power factors greater than 1 increase the roughness of the terrain and, like high fractal dimensions, may require a larger FFT mesh size and/or higher screen reso‐ lution to look good."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Controls the degree of color saturation of the stars that surround planet pictures and fill starry skies created with the -night option. The default value of 125 creates stars which resemble the sky as seen by the human eye from Earth's surface. Stars are dim; only the brightest activate the cones in the human retina, causing color to be perceived. Higher values of sat approximate the appearance of stars from Earth orbit, where better dark adaptation, absence of skyglow, and the concentration of light from a given star onto a smaller area of the retina thanks to the lack of atmospheric tur‐ bulence enhances the perception of color. Values greater than 250 create ``science fiction'' skies that, while pretty, don't occur in this universe. Thanks to the inverse square law combined with Nature's love of mediocrity, there are many, many dim stars for every bright one. This population relationship is accurately reflected in the skies created by ppmforge. Dim, low mass stars live much longer than bright massive stars, consequently there are many reddish stars for every blue giant. This relationship is preserved by ppmforge. You can reverse the proportion, simulat‐ ing the sky as seen in a starburst galaxy, by specifying a negative sat value."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the seed for the random number generator to the integer num. The seed used to create each picture is displayed on standard output (unless suppressed with the -quiet option). Pictures generated with the same seed will be identical. If no -seed is specified, a random seed derived from the date and time will be chosen. Specifying an explicit seed allows you to re-render a picture you particularly like at a higher res‐ olution or with different viewing parameters."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Specifies the percentage of pixels, in tenths of a percent, which will appear as stars, either surrounding a planet or filling the entire frame if -night is specified. The default fraction is 100."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the width of the generated image to width pixels. The default width is 256 pix‐ els. Images must be at least as wide as they are high; if a width less than the height is specified, it will be increased to equal the height. If you must have a long skinny image, make a square one with ppmforge, then use pamcut to extract a por‐ tion of the shape and size you require."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Sets the height of the generated image to height pixels. The default height is 256 pixels. If the height specified exceeds the width, the width will be increased to equal the height."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "pamcut",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamcut/1/json"
        },
        {
            "name": "pamdepth",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamdepth/1/json"
        },
        {
            "name": "ppmdither",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmdither/1/json"
        },
        {
            "name": "pnmquant",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnmquant/1/json"
        },
        {
            "name": "ppm",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppm/1/json"
        }
    ],
    "tldr": {
        "source": "official",
        "description": "Generate fractals resembling clouds, planets, and starry skies.",
        "examples": [
            {
                "description": "Generate an image of a planet",
                "command": "ppmforge > {{path/to/image.ppm}}"
            },
            {
                "description": "Generate an image of clouds or the night sky",
                "command": "ppmforge -{{night|clouds}} > {{path/to/image.ppm}}"
            },
            {
                "description": "Use a custom mesh size and dimension for fractal generation and specify the dimensions of the output",
                "command": "ppmforge {{-m|-mesh}} {{512}} {{-d|-dimension}} {{2.5}} {{-x|-xsize}} {{1000}} {{-y|-ysize}} {{1000}} > {{path/to/image.ppm}}"
            },
            {
                "description": "Control the tilt and the angle from which the generated planet is illuminated",
                "command": "ppmforge {{-t|-tilt}} {{15}} {{-ho|-hour}} {{12}} > {{path/to/image.ppm}}"
            }
        ]
    }
}