-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Generates mountainous terrain using a random walk algorithm.
--   
--   Provides functions for generating mountain-like terrain structure
--   using a random walk algorithm. Inspired by Pickover's 1998 article
--   "Vacation on Mars". The data can be output as an ascii-format PLY
--   file, or viewed "overhead" as an intensity graph. The PLY file can be
--   loaded into a 3D modeling program such as Blender.
@package mars
@version 0.2.1.0


-- | Provides functions to convert an array of floats into a Surface
--   structure containing vertices and faces, and then into PLY format
--   text, which can be loaded into a modeling program like Blender.
module Graphics.Mars.Ply

-- | Converts a 2D array of floats into a sheet of polygons, which can be
--   processed by <a>toPly</a>.
surface :: UArray (Int, Int) Float -> Surface Array
data Surface a

-- | Converts a Surface data structure, which is a sheet of polygons, into
--   an ascii-format PLY file.
toPly :: Surface Array -> String


-- | Use the <a>graph</a> function here to generate the raw graph array
--   data based on various parameters.
module Graphics.Mars.Graph

-- | Beginning in the center, follows a random walk path, and stamps a
--   circle shape onto the array at each step. Internally uses a mutable
--   unboxed array for efficiency, but returns the results in a frozen
--   array.
graph :: Int -> Int -> Float -> Float -> Int -> Int -> Float -> (Float, Float) -> IO (UArray (Int, Int) Float)

-- | Adjust each float value in a UArray by some random value between
--   negative <tt>delta</tt> and <tt>delta</tt>.
zRandomize :: Float -> Int -> UArray (Int, Int) Float -> UArray (Int, Int) Float

-- | From each pair of corresponding points on the two input UArrays,
--   select the the higher point, to create a new UArray. The two arrays
--   must have the same bounds, or an error is thrown.
meldGraphs :: UArray (Int, Int) Float -> UArray (Int, Int) Float -> UArray (Int, Int) Float


module Graphics.Mars.Paint

-- | A type of function converting a floating point data value into a
--   color's ByteString
type Interpretation = Float -> ByteString

-- | Determines the minimum and maximum values in a data structure
minMax :: (Num a, Ord a, Foldable t) => t a -> (a, a)

-- | Color interpretation of data as a variation of on the lightness of a
--   single hue
lightnessInt :: Float -> (Float, Float) -> Interpretation

-- | Converts an array of floating point values into a Gloss Picture, using
--   a color Interpretation
toImage :: UArray (Int, Int) Float -> Interpretation -> Picture


module Graphics.Mars.Display2D

-- | Displays a <a>Picture</a> in a window on the screen.
displayWindow :: (Int, Int) -> Color -> String -> Picture -> IO ()

-- | Display a <a>Picture</a> on the screen, in full-screen mode
displayFullscreen :: (Int, Int) -> Color -> Picture -> IO ()


-- | Run an example function to view an image, or study the function source
--   code for to see how the library can be used.
--   
--   Please be aware that breaking API changes to the Example functions
--   will not be tracked in library version numbering. It is recommended
--   that you do not link to these functions from any production code.
module Graphics.Mars.Example

-- | Generates an example random walk array and displays it as a
--   2-dimensional intensity graph
--   
--   <pre>
--   example2D :: IO()
--   example2D = do putStrLn "Generating the graph. This may take a minute or two."
--                  a &lt;- graph height width radius walkfactor
--                             seed iterations scalefactor startingpoint
--                  displayWindow (width, height) black "Mars"
--                    (toImage a (lightnessInt hue (minMax (elems a))))
--     where (width, height) = (300, 300)
--           radius = 30
--           walkfactor = 30
--           seed = 54844
--           hue = 272
--           iterations = 300
--           scalefactor = 1
--           startingpoint = (0, -80)
--   </pre>
example2D :: IO ()

-- | Generates a random walk array, converts it PLY ascii format, and
--   output the PLY to a file called "out.ply".
--   
--   <pre>
--   examplePly :: IO ()
--   examplePly = do putStrLn "Generating the graph. This may take a minute or two."
--                   a &lt;- graph height width radius walkfactor
--                              seed iterations scalefactor startingpoint
--                   writeFile "out.ply" $ (toPly . surface) a
--                   putStrLn "The file 'out.ply' has been created in the current \
--                            \working directory."
--     where (width, height) = (300, 300)
--           radius = 30
--           walkfactor = 30
--           seed = 54844
--           iterations = 300
--           scalefactor = 1
--           startingpoint = (0, -80)
--   </pre>
examplePly :: IO ()

-- | Similar to examplePly2, but generates two graphs and merges them
--   together.
--   
--   <pre>
--   examplePly2 :: IO ()
--   examplePly2 = do putStrLn "Generating two graphs and merging them. This may \
--                             \take a few minutes."
--                    a1 &lt;- graph height width radius walkfactor
--                                seed1 iterations scalefactor startingpoint1
--                    a2 &lt;- graph height width radius walkfactor
--                                seed2 iterations scalefactor startingpoint2
--                    let a3 = meldGraphs a1 a2
--                    let a4 = zRandomize 0.5 seed3 a3
--                    writeFile "out2.ply" $ (toPly . surface) a4
--                    putStrLn "The file 'out2.ply' has been created in the current \
--                             \working directory."
--     where (width, height) = (300, 300)
--           radius = 30
--           walkfactor = 30
--           iterations = 200
--           scalefactor = 1
--           seed1 = 3939423948
--           startingpoint1 = (0, 0)
--           seed2 = 34209809
--           startingpoint2 = (100, 100)
--           seed3 = 87484853049
--   </pre>
examplePly2 :: IO ()