Example.hs

{-|
Module      : Graphics.Mars.Example
Description : Provides code examples which can be studied or executed.
Copyright   : (c) Christopher Howard, 2016
License     : GPL-3
Maintainer  : ch.howard@zoho.com

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 where

import Prelude(IO, (.), ($), writeFile, return, putStrLn)
import Graphics.Gloss (black)
import Data.Array.Unboxed (elems)
import Graphics.Mars.Paint
import Graphics.Mars.Graph
import Graphics.Mars.Display2D
import Graphics.Mars.Ply

-- |Generates an example random walk array and displays it as a 2-dimensional
-- intensity graph
--
-- @
-- example2D :: IO()
-- example2D = do putStrLn \"Generating the graph. This may take a minute or two.\"
--                a <- 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)
-- @
example2D :: IO()
example2D = do putStrLn "Generating the graph. This may take a minute or two."
               a <- 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)

-- |Generates a random walk array, converts it PLY ascii format, and output the
-- PLY to a file called \"out.ply\".
--
-- @
-- examplePly :: IO ()
-- examplePly = do putStrLn \"Generating the graph. This may take a minute or two.\"
--                 a <- 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)
-- @
examplePly :: IO ()
examplePly = do putStrLn "Generating the graph. This may take a minute or two."
                a <- 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)

-- |Similar to examplePly2, but generates two graphs and merges them together.
--
-- @
-- examplePly2 :: IO ()
-- examplePly2 = do putStrLn \"Generating two graphs and merging them. This may \\
--                           \\take a few minutes.\"
--                  a1 <- graph height width radius walkfactor
--                              seed1 iterations scalefactor startingpoint1
--                  a2 <- 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
-- @
examplePly2 :: IO ()
examplePly2 = do putStrLn "Generating two graphs and merging them. This may \
                          \take a few minutes."
                 a1 <- graph height width radius walkfactor
                             seed1 iterations scalefactor startingpoint1
                 a2 <- 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