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


-- | Algorithms using the Repa array library.
--   
--   Reusable algorithms using the Repa array library.
@package repa-algorithms
@version 3.2.2.3

module Data.Array.Repa.Algorithms.Randomish

-- | Use the ''minimal standard'' Lehmer generator to quickly generate some
--   random numbers with reasonable statistical properties. By
--   ''reasonable'' we mean good enough for games and test data, but not
--   cryptography or anything where the quality of the randomness really
--   matters.
--   
--   By nature of the algorithm, the maximum value in the output is clipped
--   to (valMin + 2^31 - 1)
--   
--   From ''Random Number Generators: Good ones are hard to find'' Stephen
--   K. Park and Keith W. Miller. Communications of the ACM, Oct 1988,
--   Volume 31, Number 10.
randomishIntArray :: Shape sh => sh -> Int -> Int -> Int -> Array U sh Int
randomishIntVector :: Int -> Int -> Int -> Int -> Vector Int

-- | Generate some randomish doubles with terrible statistical properties.
--   This just takes randomish ints then scales them, so there's not much
--   randomness in low-order bits.
randomishDoubleArray :: Shape sh => sh -> Double -> Double -> Int -> Array U sh Double

-- | Generate some randomish doubles with terrible statistical properties.
--   This just takes randmish ints then scales them, so there's not much
--   randomness in low-order bits.
randomishDoubleVector :: Int -> Double -> Double -> Int -> Vector Double


-- | Utilities for converting pixel color values.
--   
--   NOTE: These functions are not polymorphic in the Float type because
--   without assisatance, GHC does a bad job of converting Word8s to and
--   from floats.
module Data.Array.Repa.Algorithms.Pixel

-- | Compute the root mean square of an RGB color. Result is in the range
--   [0..1].
floatRmsOfRGB8 :: (Word8, Word8, Word8) -> Float

-- | Compute the root mean square of an RGB color. Result is in the range
--   [0..1].
doubleRmsOfRGB8 :: (Word8, Word8, Word8) -> Float

-- | Convert an RGB color to its luminance value. Result in the range
--   [0..1].
floatLuminanceOfRGB8 :: (Word8, Word8, Word8) -> Float

-- | Convert an RGB color to its luminance value. Result in the range
--   [0..1].
doubleLuminanceOfRGB8 :: (Word8, Word8, Word8) -> Double

-- | Promote a value in the range [0..1] to a grey RGB8 color.
rgb8OfGreyFloat :: Float -> (Word8, Word8, Word8)

-- | Promote a value in the range [0..1] to a grey RGB8 color.
rgb8OfGreyDouble :: Double -> (Word8, Word8, Word8)

-- | Promote a tuple of color components to a RGB8 color. Each of the
--   source components should be in the range [0..1].
rgb8OfFloat :: (Float, Float, Float) -> (Word8, Word8, Word8)

-- | Promote a tuple of color components to a RGB8 color. Each of the
--   source components should be in the range [0..1].
rgb8OfDouble :: (Double, Double, Double) -> (Word8, Word8, Word8)


-- | Algorithms operating on matrices.
--   
--   These functions should give performance comparable with nested loop C
--   implementations.
--   
--   If you care deeply about runtime performance then you may be better
--   off using a binding to LAPACK, such as hvector.
module Data.Array.Repa.Algorithms.Matrix

-- | Take the row number of a rank-2 index.
row :: DIM2 -> Int

-- | Take the column number of a rank-2 index.
col :: DIM2 -> Int

-- | Matrix matrix multiply, in parallel.
mmultP :: Monad m => Array U DIM2 Double -> Array U DIM2 Double -> m (Array U DIM2 Double)

-- | Matrix matrix multiply, sequentially.
mmultS :: Array U DIM2 Double -> Array U DIM2 Double -> Array U DIM2 Double

-- | Transpose a 2D matrix, in parallel.
transpose2P :: Monad m => Array U DIM2 Double -> m (Array U DIM2 Double)

-- | Transpose a 2D matrix, sequentially.
transpose2S :: Array U DIM2 Double -> Array U DIM2 Double


-- | Generic stencil based convolutions.
--   
--   If your stencil fits within a 7x7 tile and is known at compile-time
--   then using then using the built-in stencil support provided by the
--   main Repa package will be 5-10x faster.
--   
--   If you have a larger stencil, the coefficients are not statically
--   known, or need more complex boundary handling than provided by the
--   built-in functions, then use this version instead.
module Data.Array.Repa.Algorithms.Convolve

-- | Image-kernel convolution, which takes a function specifying what value
--   to return when the kernel doesn't apply.
convolveP :: (Num a, Unbox a, Monad m) => (DIM2 -> a) -> Array U DIM2 a -> Array U DIM2 a -> m (Array U DIM2 a)

-- | A function that gets out of range elements from an image.
type GetOut a = (DIM2 -> a) -> DIM2 -> DIM2 -> a

-- | Use the provided value for every out-of-range element.
outAs :: a -> GetOut a

-- | If the requested element is out of range use the closest one from the
--   real image.
outClamp :: GetOut a

-- | Image-kernel convolution, which takes a function specifying what value
--   to use for out-of-range elements.
convolveOutP :: (Num a, Unbox a, Monad m) => GetOut a -> Array U DIM2 a -> Array U DIM2 a -> m (Array U DIM2 a)


-- | Hyprometric color ramps, for making pretty images from scalar data.
module Data.Array.Repa.Algorithms.ColorRamp

-- | Standard Hot to Cold hypsometric color ramp. Color sequence is red,
--   yellow, green, cyan, blue.
rampColorHotToCold :: (Ord a, Floating a) => a -> a -> a -> (a, a, a)


-- | Strict complex doubles.
module Data.Array.Repa.Algorithms.Complex

-- | Complex doubles.
type Complex = (Double, Double)

-- | Take the magnitude of a complex number.
mag :: Complex -> Double

-- | Take the argument (phase) of a complex number, in the range [-pi ..
--   pi].
arg :: Complex -> Double
instance [overlap ok] Fractional Complex
instance [overlap ok] Num Complex


-- | Calculation of roots of unity for the forward and inverse DFT/FFT.
module Data.Array.Repa.Algorithms.DFT.Roots

-- | Calculate roots of unity for the forward transform.
calcRootsOfUnityP :: (Shape sh, Monad m) => (sh :. Int) -> m (Array U (sh :. Int) Complex)

-- | Calculate roots of unity for the inverse transform.
calcInverseRootsOfUnityP :: (Shape sh, Monad m) => (sh :. Int) -> m (Array U (sh :. Int) Complex)


-- | Fast computation of Discrete Fourier Transforms using the
--   Cooley-Tuckey algorithm. Time complexity is O(n log n) in the size of
--   the input.
--   
--   This uses a naive divide-and-conquer algorithm, the absolute
--   performance is about 50x slower than FFTW in estimate mode.
module Data.Array.Repa.Algorithms.FFT
data Mode
Forward :: Mode
Reverse :: Mode
Inverse :: Mode

-- | Check if an <a>Int</a> is a power of two.
isPowerOfTwo :: Int -> Bool

-- | Compute the DFT of a 3d array. Array dimensions must be powers of two
--   else <a>error</a>.
fft3dP :: (Source r Complex, Monad m) => Mode -> Array r DIM3 Complex -> m (Array U DIM3 Complex)

-- | Compute the DFT of a matrix. Array dimensions must be powers of two
--   else <a>error</a>.
fft2dP :: (Source r Complex, Monad m) => Mode -> Array r DIM2 Complex -> m (Array U DIM2 Complex)

-- | Compute the DFT of a vector. Array dimensions must be powers of two
--   else <a>error</a>.
fft1dP :: (Source r Complex, Monad m) => Mode -> Array r DIM1 Complex -> m (Array U DIM1 Complex)
instance [overlap ok] Show Mode
instance [overlap ok] Eq Mode


-- | Applying these transforms to the input of a DFT causes the output to
--   be centered so that the zero frequency is in the middle.
module Data.Array.Repa.Algorithms.DFT.Center

-- | Apply the centering transform to a vector.
center1d :: Source r Complex => Array r DIM1 Complex -> Array D DIM1 Complex

-- | Apply the centering transform to a matrix.
center2d :: Source r Complex => Array r DIM2 Complex -> Array D DIM2 Complex

-- | Apply the centering transform to a 3d array.
center3d :: Source r Complex => Array r DIM3 Complex -> Array D DIM3 Complex


-- | Compute the Discrete Fourier Transform (DFT) along the low order
--   dimension of an array.
--   
--   This uses the naive algorithm and takes O(n^2) time. However, you can
--   transform an array with an arbitray extent, unlike with FFT which
--   requires each dimension to be a power of two.
--   
--   The <tt>dft</tt> and <tt>idft</tt> functions also compute the roots of
--   unity needed. If you need to transform several arrays with the same
--   extent then it is faster to compute the roots once using
--   <tt>calcRootsOfUnity</tt> or <tt>calcInverseRootsOfUnity</tt>, then
--   call <tt>dftWithRoots</tt> directly.
--   
--   You can also compute single values of the transform using
--   <tt>dftWithRootsSingle</tt>.
module Data.Array.Repa.Algorithms.DFT

-- | Compute the DFT along the low order dimension of an array.
dftP :: (Shape sh, Monad m) => Array U (sh :. Int) Complex -> m (Array U (sh :. Int) Complex)

-- | Compute the inverse DFT along the low order dimension of an array.
idftP :: (Shape sh, Monad m) => Array U (sh :. Int) Complex -> m (Array U (sh :. Int) Complex)

-- | Generic function for computation of forward or inverse DFT. This
--   function is also useful if you transform many arrays with the same
--   extent, and don't want to recompute the roots for each one. The extent
--   of the given roots must match that of the input array, else
--   <a>error</a>.
dftWithRootsP :: (Shape sh, Monad m) => Array U (sh :. Int) Complex -> Array U (sh :. Int) Complex -> m (Array U (sh :. Int) Complex)

-- | Compute a single value of the DFT. The extent of the given roots must
--   match that of the input array, else <a>error</a>.
dftWithRootsSingleS :: Shape sh => Array U (sh :. Int) Complex -> Array U (sh :. Int) Complex -> (sh :. Int) -> Complex