Difference between revisions of "FieldTrip"
(Adding Curve2, and improving wording about FRP.) 
m (→Basic types: formatting) 

(32 intermediate revisions by 10 users not shown)  
Line 1:  Line 1:  
−  [[Category: 
+  [[Category:Graphics]] 
+  [[Category:3D]] 

+  [[Category:Packages]] 

−  Field Trip is a library for describing 3D scenes declaratively. It is intended 

+  == Abstract == 

−  as an open technology independent API for building animations as well as still life pictures. We also supply a bridge to use the OpenGL rendering engine, but other technologies are envisioned, for example a raytracing based renderer. 

−  It is in active development by Conal Elliott and Andy Gill. 

+  [[Image:Toruspairdshadowed.pngrightthumb300pxTorus pair modeled and rendered in FieldTrip]] 

+  '''FieldTrip''' is a library for functional 3D graphics, intended for building static, animated, and interactive 3D geometry, efficient 

+  enough for realtime synthesis and display. 

+  Our first renderer uses OpenGL, with the usual visual limitations. 

+  Since FieldTrip is functional, it is about ''being'' rather than ''doing''. 

+  One describes what models are, not how to render them. 

−  == Architecture == 

+  FieldTrip is workinprogress. 

+  It's being released to show what's going on and see who's interested in collaborating on developing it further. 

−  The basic purpose of the core FieldTrip library is to allow a user build a 3D scene. The principal types are as follows. 

+  Besides this wiki page, here are more ways to find out about and get involved with FieldTrip: 

+  * Join the [http://www.haskell.org/mailman/listinfo/FieldTrip FieldTrip mailing list]. 

+  * Visit the [http://hackage.haskell.org/cgibin/hackagescripts/package/FieldTrip Hackage page] for library documentation and to download & install. 

+  * Or install with <tt>cabal install FieldTrip</tt>. See [[#Installation dependenciesInstallation dependencies]] below. 

+  * Get the code repository: <tt>darcs get http://code.haskell.org/FieldTrip</tt> 

+  <! * See the [[FieldTrip/Versions version history]]. > 

+  * Report bugs and request features on [http://trac.haskell.org/FieldTrip/ the tracker]. 

−  <dl> 

+  == Basic types == 

−  <dt><b>data</b> Geometry3</dt> 

−  <dd>A abstract type describing a number of objects in 3D space. These objects can be scaled, rotated or translated in space, as well as grouped. 

−  </dd> 

−  <dt><b>type</b> Surf a = (a,a) > (a,a,a)</dt> 

+  The basic purpose of the core FieldTrip library is to allow a user build 3D geometry, from individual simple shapes to full 3D scenes. 

−  <dd> 

+  The principal types are as follows. 

−  Primitive Geometry3's are build from surfaces, which represented as a function from R2 to R3  so this function maps every point on the (2D) surface onto a point in 3D. 

−  </dd> 

−  <dt>Normal and Derivatives</dt> 

+  ; <hask>Geometry3</hask> 

−  <dd>One novel feature of FieldTrip is the automation of derivative computation. We represent our surfaces using (more text) .. This design allows us to perform functions over surfaces, adding ripples and other deformities. 

+  : 3D geometry. These values can be spatially transformed in space (affinely: scale, rotate, translate) and combined (union). 

−  </dd> 

+  ; <hask>Surf a = (a,a) > (a,a,a)</hask> 

+  : Parametric surfaces, i.e., mappings from 2D to 3D. Normals are constructed automatically and exactly via derivatives, thanks to the [[vectorspace]] library. These normals are used for shading. For simplicity and composability, ''surfaces are curved'', not faceted. 

+  : Surface ''rendering'' tessellates adaptively, caching tessellations in an efficient, infinite data structure for reuse. The mechanism for choosing tessellation is a very primitive placeholder. FieldTrip provides some basic shapes of surfaces (spheres, torus, cubes, etc) and many functions for manipulating surfaces, colors, etc. 

−  <dt><b>type</b> ImageC = (Float,Float) > Color</dt> 

+  ; <hask>Geometry2</hask> 

−  <dd>We represent all 2D images as straightforward functions from location (in 2D) to color (including an alpha component). We use [http://en.wikipedia.org/wiki/Bilinear_interpolation bilinear interpolation] to sample imported image data. Fonts are also supported via our ImageC idiom. 

+  : 2D geometry. There's a function (<hask>flatG</hask>) to embed 2D into 3D. 

−  <dd> 

−  </dl> 

+  ; <hask>Image o = (R,R) > o</hask> 

+  : A primitive placeholder for functional imagery in the spirit of [http://conal.net/Pan Pan]. The intention is to use this type or 

+  something like it for texture mapping. Much design and implementation work to be done. 

−  The standard way of creating basic Geometry3 uses all these architectural features, using Surf and ImageC to realize a Geometry3, as well as the derivative mechanism to compute normals for realistic lighting. 

+  == Example == 

−  In FieldTrip we provide some basic shapes of surfaces (spheres, torus, cubes, etc) and many functions for manipulating surfaces, colors, etc. 

+  The code for the static torus pair shown above: 

+  <haskell> 

+  torusPair :: Geometry3 

+  torusPair = f red (1/2) `mappend` pivot3X (f green (1/2)) 

+  where 

+  tor = torus 1 (2/5) 

+  f :: Col > R > Geometry3 

+  f col dx = materialG (plastic col) (move3X dx tor) 

+  </haskell> 

+  where <hask>pivot3X</hask> and <hask>move3X</hask> are simple helper shorthands for 3D transformation. 

−  We combine a Geometry3 with lights, fog, and other effects, as well as a camera location, and give this combination (the details are still in flux) to the renderer. 

+  The <code>[http://hackage.haskell.org/packages/archive/FieldTrip/0.2.2/doc/html/GraphicsFieldTripGeometry3.html#v%3Atorus torus]</code> function used here is a 

+  simple wrapper around a parametric surface defined as follows: 

+  <haskell> 

+    Torus, given radius of sweep circle and cross section 

+  torus :: (Floating s, VectorSpace s, Scalar s ~ s) => s > s > Surf s 

+  torus sr cr = revolve (const (sr,0) ^+^ cr *^ circle) 

+  </haskell> 

+  where <hask>revolve</hask> and <hask>circle</hask> are defined in 

+  [http://hackage.haskell.org/packages/archive/FieldTrip/latest/doc/html/GraphicsFieldTripParamSurf.html Graphics.FieldTrip.ParamSurf], along with other tools for shape generation. 

−  === Other Features === 

+  The trick to turning this polymorphic <hask>torus</hask> function into a <hask>Geometry3</hask> is to use a derivative tower (from 

+  [[vectorspace]]) for the type parameter <hask>s</hask>. 

+  <haskell> 

+  surfG :: Surf (Vector2 R :> R) > Geometry3 

−  There is a 2D analogue of Geometry3, called Geometry2. Lines are drawn using Curve2, which are defined using 

+  torus :: R > R > Geometry3 

+  torus sr cr = surfG (P.torus (pureD sr) (pureD cr)) 

+  </haskell> 

−  <b>type</b> Curve2 a = a > (a,a) 

+  ''[fill in more examples]'' 

+  == FieldTrip meets Reactive == 

+  FieldTrip contains no support for animation, because we intend it to be used with the [[Reactive]] functional reactive programming 

+  ([[FRP]]) library (and possibly other animation frameworks). 

+  By design, FieldTrip is completely orthogonal to any formulation or implementation of FRP. 

−  == FieldTrip for Animation using OpenGL == 

+  The [[reactivefieldtrip]] project connects [[Reactive]] and FieldTrip. 

−  Our first renderer uses OpenGL. 

+  The picture above comes from an animation in [[reactivefieldtrip]]. 

−  FieldTrip is intended to be efficient enough for real time image generation. 

+  Load <code>src/Test.hs</code>, as follows: 

−  We do not draw shadows or reflections when rendering, and inherit the OpenGL antialiasing policy. 

+  <pre> 

+  ~/Haskell$ cd reactivefieldtrip/src 

+  ~/Haskell/reactivefieldtrip/src$ ghci 

+  GHCi, version 6.10.1: http://www.haskell.org/ghc/ :? for help 

+  Loading package ghcprim ... linking ... done. 

+  Loading package integer ... linking ... done. 

+  Loading package base ... linking ... done. 

+  Prelude> :l Test 

+  :l Test 

+  [1 of 2] Compiling FRP.Reactive.FieldTrip.Adapter ( FRP/Reactive/FieldTrip/Adapter.hs, interpreted ) 

+  [2 of 2] Compiling Test ( Test.hs, interpreted ) 

+  Ok, modules loaded: FRP.Reactive.FieldTrip.Adapter, Test. 

+  </pre> 

+  Then run the example: 

+  <pre> 

+  *Test> anim3 (const (spinningG torusPair)) 

+  Loading package OpenGL2.2.1.1 ... linking ... done. 

+  Loading package syb ... linking ... done. 

+  Loading package base3.0.3.0 ... linking ... done. 

+  [...] 

+  Loading package reactive0.9.0 ... linking ... done. 

+  Loading package FieldTrip0.2.2 ... linking ... done. 

+  Loading package reactiveglut0.0.5 ... linking ... done. 

+  </pre> 

−  Towards efficiency we have a dynamic accuracy graphics context internally, which uses less triangles when [http://en.wikipedia.org/wiki/Tessellation tessellating] a surface when performance is needed. When finished this will allow us to automatically use less triangle for distance objects, for example. 

+  == Some videos == 

−  We want our library to be usable in real time by FRPbased code, though FieldTrip is by design completely orthogonal to any implementation of FRP. 

+  * [http://www.youtube.com/watch?v=ulPsJzUCQi8 Texturemapped Earth.] 

+  * [http://www.youtube.com/watch?v=WNB5V9Z7Obc The torus demo running in GHCi.] 

−  == The FieldTrip Universe == 

+  == Problems and solutions == 

−  Field trip has a number of packages. 

+  === Installation dependencies === 

−  <dl> 

+  ==== Haskell packages ==== 

−  <dt>FieldTrip</td> 

−  <dd>The basic library of combinators for building 3D scenes. 

−  </dd> 

−  <dt>FieldTripOpenGL</td> 

+  You'll need the OpenGL and GLUT packages. If you are using synaptics/aptget, those are called libghc6opengldev and libghc6glutdev. If you're using cabalinstall, it will take care of the dependencies for you (see "NonHaskell libraries" below though). 

−  <dd>The library for rendering a scene in real time, using the OpenGL library. 

−  </dd> 

−  <dt>FieldTripGLUT</td> 

+  ==== NonHaskell libraries ==== 

−  <dd>The library for opening a viewer into a FieldTrip OpenGL based scene. 

−  </dd> 

−  <dt>FieldTripGLFW</td> 

+  Make sure that you have the opengldev and glutdev libraries installed. If you don't have them, there are two ways to fail: Either on the installation of the corresponding Haskell libraries, like this: 

−  <dd> Same, for GLFW. 

−  </dd> 

−  <dt>FieldTripOSX</td> 

+  <pre> 

−  <dd>An alternative version of GLUT/GLFW that provides access the the OSX extensions, for example .mov file capture. 

+  configure: error: no GLUT header found, so this package cannot be built 

−  </dd> 

+  See `config.log' for more details. 

−  </dl> 

+  cabal: Error: some packages failed to install: 

+  GLUT2.1.1.2 failed during the configure step. The exception was: 

+  exit: ExitFailure 1 

+  </pre> 

−  There will be more! 

+  Or, if you do have the Haskell packages and C libraries, but accidentally removed the opengldev and glutdev libraries, you can end up with FieldTrip just producing black windows. 

+  
+  ===== Linking problems on Debian Lenny ===== 

+  
+  You may experience linker problems on Debian Lenny. Running: 

+  
+  > ghc make mainis Test Test.hs 

+  
+  can give you: 

+  
+  <pre> 

+  Linking Test ... 

+  /home/ghc/.cabal/lib/reactiveglut0.1.6/ghc6.10.1/libHSreactiveglut0.1.6.a(SimpleGL.o): In function `s5SW_info': 

+  (.text+0x1654): undefined reference to `glutInitDisplayMode' 

+  /home/ghc/.cabal/lib/reactiveglut0.1.6/ghc6.10.1/libHSreactiveglut0.1.6.a(SimpleGL.o): In function `s5SW_info': 

+  (.text+0x1668): undefined reference to `glutInitWindowSize' 

+  ... 

+  </pre> 

+  
+  This is a HOpenGL problem and has already been [http://www.haskell.org/pipermail/haskellcafe/2008September/047357.html reported here] and a [http://www.haskell.org/pipermail/haskellcafe/2008September/047815.html solution here]. To make a long story short, you need to explicitly link with glut when compiling: 

+  
+  > ghc make lglut mainis Test Test.hs 
Latest revision as of 19:45, 3 July 2009
Contents
Abstract
FieldTrip is a library for functional 3D graphics, intended for building static, animated, and interactive 3D geometry, efficient enough for realtime synthesis and display. Our first renderer uses OpenGL, with the usual visual limitations. Since FieldTrip is functional, it is about being rather than doing. One describes what models are, not how to render them.
FieldTrip is workinprogress. It's being released to show what's going on and see who's interested in collaborating on developing it further.
Besides this wiki page, here are more ways to find out about and get involved with FieldTrip:
 Join the FieldTrip mailing list.
 Visit the Hackage page for library documentation and to download & install.
 Or install with cabal install FieldTrip. See Installation dependencies below.
 Get the code repository: darcs get http://code.haskell.org/FieldTrip
 Report bugs and request features on the tracker.
Basic types
The basic purpose of the core FieldTrip library is to allow a user build 3D geometry, from individual simple shapes to full 3D scenes. The principal types are as follows.

Geometry3
 3D geometry. These values can be spatially transformed in space (affinely: scale, rotate, translate) and combined (union).

Surf a = (a,a) > (a,a,a)
 Parametric surfaces, i.e., mappings from 2D to 3D. Normals are constructed automatically and exactly via derivatives, thanks to the vectorspace library. These normals are used for shading. For simplicity and composability, surfaces are curved, not faceted.
 Surface rendering tessellates adaptively, caching tessellations in an efficient, infinite data structure for reuse. The mechanism for choosing tessellation is a very primitive placeholder. FieldTrip provides some basic shapes of surfaces (spheres, torus, cubes, etc) and many functions for manipulating surfaces, colors, etc.

Geometry2
 2D geometry. There's a function (
flatG
) to embed 2D into 3D.

Image o = (R,R) > o
 A primitive placeholder for functional imagery in the spirit of Pan. The intention is to use this type or
something like it for texture mapping. Much design and implementation work to be done.
Example
The code for the static torus pair shown above:
torusPair :: Geometry3
torusPair = f red (1/2) `mappend` pivot3X (f green (1/2))
where
tor = torus 1 (2/5)
f :: Col > R > Geometry3
f col dx = materialG (plastic col) (move3X dx tor)
where pivot3X
and move3X
are simple helper shorthands for 3D transformation.
The torus
function used here is a
simple wrapper around a parametric surface defined as follows:
  Torus, given radius of sweep circle and cross section
torus :: (Floating s, VectorSpace s, Scalar s ~ s) => s > s > Surf s
torus sr cr = revolve (const (sr,0) ^+^ cr *^ circle)
where revolve
and circle
are defined in
Graphics.FieldTrip.ParamSurf, along with other tools for shape generation.
The trick to turning this polymorphic torus
function into a Geometry3
is to use a derivative tower (from
vectorspace) for the type parameter s
.
surfG :: Surf (Vector2 R :> R) > Geometry3
torus :: R > R > Geometry3
torus sr cr = surfG (P.torus (pureD sr) (pureD cr))
[fill in more examples]
FieldTrip meets Reactive
FieldTrip contains no support for animation, because we intend it to be used with the Reactive functional reactive programming (FRP) library (and possibly other animation frameworks). By design, FieldTrip is completely orthogonal to any formulation or implementation of FRP.
The reactivefieldtrip project connects Reactive and FieldTrip.
The picture above comes from an animation in reactivefieldtrip.
Load src/Test.hs
, as follows:
~/Haskell$ cd reactivefieldtrip/src ~/Haskell/reactivefieldtrip/src$ ghci GHCi, version 6.10.1: http://www.haskell.org/ghc/ :? for help Loading package ghcprim ... linking ... done. Loading package integer ... linking ... done. Loading package base ... linking ... done. Prelude> :l Test :l Test [1 of 2] Compiling FRP.Reactive.FieldTrip.Adapter ( FRP/Reactive/FieldTrip/Adapter.hs, interpreted ) [2 of 2] Compiling Test ( Test.hs, interpreted ) Ok, modules loaded: FRP.Reactive.FieldTrip.Adapter, Test.
Then run the example:
*Test> anim3 (const (spinningG torusPair)) Loading package OpenGL2.2.1.1 ... linking ... done. Loading package syb ... linking ... done. Loading package base3.0.3.0 ... linking ... done. [...] Loading package reactive0.9.0 ... linking ... done. Loading package FieldTrip0.2.2 ... linking ... done. Loading package reactiveglut0.0.5 ... linking ... done.
Some videos
Problems and solutions
Installation dependencies
Haskell packages
You'll need the OpenGL and GLUT packages. If you are using synaptics/aptget, those are called libghc6opengldev and libghc6glutdev. If you're using cabalinstall, it will take care of the dependencies for you (see "NonHaskell libraries" below though).
NonHaskell libraries
Make sure that you have the opengldev and glutdev libraries installed. If you don't have them, there are two ways to fail: Either on the installation of the corresponding Haskell libraries, like this:
configure: error: no GLUT header found, so this package cannot be built See `config.log' for more details. cabal: Error: some packages failed to install: GLUT2.1.1.2 failed during the configure step. The exception was: exit: ExitFailure 1
Or, if you do have the Haskell packages and C libraries, but accidentally removed the opengldev and glutdev libraries, you can end up with FieldTrip just producing black windows.
Linking problems on Debian Lenny
You may experience linker problems on Debian Lenny. Running:
> ghc make mainis Test Test.hs
can give you:
Linking Test ... /home/ghc/.cabal/lib/reactiveglut0.1.6/ghc6.10.1/libHSreactiveglut0.1.6.a(SimpleGL.o): In function `s5SW_info': (.text+0x1654): undefined reference to `glutInitDisplayMode' /home/ghc/.cabal/lib/reactiveglut0.1.6/ghc6.10.1/libHSreactiveglut0.1.6.a(SimpleGL.o): In function `s5SW_info': (.text+0x1668): undefined reference to `glutInitWindowSize' ...
This is a HOpenGL problem and has already been reported here and a solution here. To make a long story short, you need to explicitly link with glut when compiling:
> ghc make lglut mainis Test Test.hs