******************************************************************************* Pov4Grasp patch informations Patch version: pov4grasp-1.31 Author : Nicolas Calimet Last revision: October 12, 2000 http://pov4grasp.free.fr ******************************************************************************* THIS IS AN UNOFFICIAL VERSION OF POV-RAY 3.1g Official version will be found at http://www.povray.org 0. UPDATES ******* Pov4Grasp-1.31 (released 2000-10-12) - added 'persistent' option to 'grasp_surface' object - added 'fog_start' keyword to replace the special use of 'fog_offset' - added test to turn off vista buffer with camera motion blur (minor effect) Pov4Grasp-1.3 (released 2000-07-12) - added 'preview' modes and 'smooth' option to 'grasp_surface' object - added direct 'filter' and 'transmit' to any property of 'grasp_surface' - relaxed 'grasp_surface' object syntax, added 'gradient' and 'colors_file' - cleaned code for data parsing (removed unnecessary tests) Pov4Grasp-1.22 (released 2000-06-16) - added several spellings for the 'grasp_surface' object (new keywords) - added 'verbose' mode to 'grasp_surface' to be compliant with POV-Ray output - fixed and improved 'discretecolors' property (former 'vertexcolor') - fixed again 'grasp_surface' textures handling Pov4Grasp-1.21 (released 2000-05-24) - improved 'grasp_surface' texture handling to reproduce mesh behaviour - added a few output messages - code reorganized, fixed a minor bug Pov4Grasp-1.2 (released 2000-04-19) - added an experimental camera motion blur effect (moving camera) Pov4Grasp-1.1 and earlier (not released) - added 'vertexcolor' pattern texture for color interpolation within triangles - added 'fog_offset' support for constant fog - added 'grasp_surface' object, followed by template surface support - port to POV-Ray 3.1g code from 3.0 (project started in March 1998) - cleaned a lot of code, some major changes in the 'grasp_surface' code 1. CHANGES TO THE ORIGINAL DISTRIBUTION ************************************ 1.1 Source files (source/) ============ 1.1.1 Modified files are listed in the POV4GRASP.lst file. The patch code is identified using the Pov4GraspPatch label. 1.1.2 Added 2 new files: grasppov.c and grasppov.h 1.1.3 Patch features may be turned off by commenting the line "#define Pov4GraspPatch" near the top of frame.h. Still the new files will be compiled and linked. 1.2 Compiling (source/unix) ========= 1.2.1 The makefile has been modified to account for the new source files grasppov.c and grasppov.h 1.2.2 Target executables have been renamed to pov4grasp, s-pov4grasp and x-pov4grasp. 1.2.3 As usual, you have to compile the zlib and libpng libraries first. Please read the CMPL_Unix.doc file for details. 2. NEW FEATURES ************ 2.1 grasp_surface object ==================== 2.1.1 Description Read a GRASP (1) molecular surface file and map any of its property with specified colors. This new object is merely an extension of a POV-Ray mesh object. Colors are smoothly interpolated between vertices, and several sets of properties can be mapped on different copies of the same object (template). 2.1.2 Syntax grasp_surface { "FILENAME.srf" // GRASP surface file, e.g. "surface.srf" [ with OBJECT_IDENTIFIER ] // template (another grasp_surface object) [ colored_by PROPERTY_NAME ] // see below for syntax [ gradient ,, ] // color gradient [ colors_file "FILENAME.dat" ] // GRASP colors file, e.g. "defcol.dat" [ filter FLOAT ] // filtering transparency [ transmit FLOAT ] // transmitting transparency [ range ] // for color gradient [ precision INTEGER ] // for decimal numbers (default = 0 = full) [ verbose [BOOL] ] // verbose mode (default = off) [ smooth [BOOL] ] // smooth surface (default = on) [ preview [LEVEL] ] // preview mode, level in 1..4 range [ persistent [BOOL] ] // parse surface data only once (animation) [ ... ] // any valid mesh object option } Property names (mutually exclusive) and equivalences: potentials potential curvatures curvature distances distance gproperty1 property1 gproperty2 property2 discretecolors discretecolours discretecolor discretecolour vertexcolor Other equivalences: colored_by coloured_by gradient with color_file colors_file colour_file colours_file with persistent persist Options which are not relevant to the specified property are now simply ignored, and thus won't generate an error. 2.1.3 Notes * Reads only GRASP file format=2 (the latest) and the first surface of merged GRASP files, i.e. that contains several headers. * A template surface can be used to save memory while mapping different sets of properties on several 'grasp_surface' objects. Define this template as for instance "#declare surf = grasp_surface{...}" before invoquing the "surf" identifier in another 'grasp_surface' definition. See the example. * Default surface color is white, and may be changed by the standard pigment/texture/material definitions (see POV-Ray manual). * 'colored_by' options are mutually exclusive. The selected property to be shown is colored using a gradient of 3 different colors. Default colors are those that GRASP uses (e.g. red,white,blue for electrostatic poten- tials). Custom colors are set using the 'gradient' option followed by up to 3 comma-separated color definitions in standard POV-Ray syntax. * 'discretecolors' property has his own 'colors_file' option to read a color description file. This file is automatically written by GRASP if you change the default colors in your GRASP session ("defcol.dat"). * 'range' option applies to all but the 'discretecolors' property. * 'precision' option is the number of decimal digits that will be kept to define the surface coordinates and colors. Very low value (< 4) may have a strong effect on the surface shape. The default value is zero, which means full precision. This parameter is only experimental and does not actually speed up rendering. * 'verbose' mode prints useful messages while parsing the object. Note this is different from the +V command-line switch. * 'smooth' option controls the shape of the surface. You may turn it off for faster rendering, e.g. when using the following option. * A 'preview' mode allows to reduce the surface complexity (number of triangles) in order to save parsing time and memory. This will produce a crude simplification of the surface, thus you should not use it for final rendering. Properties will be shown if specified. A better result is obtained using precision levels (1 to 4) and/or the 'smooth' option. If the grasp_surface object is used as a template, this option will affect the "children" objects as well. * The 'persistent' option is intended to be used in "rigid-body" animations of the object (translations, rotations, scaling). Surface data, including any property, are parsed only once at the beginning of the animation, thus saving parsing time for subsequent frames. There are currently strong limitations in using this option, since the 'grasp_surface' must be a frame-level object; CSG constructions or definition of variables won't allow to use a persistent surface (so we cannot define a persistent template surface). These restrictions may be removed in a future release. 2.1.4 Example #define surf = grasp_surface{ "surface.srf" colored_by potential } grasp_surface{ "surface.srf" with surf finish{ambient 0.2} } grasp_surface{ "surface.srf" with surf range<-10,0,10> } * Note: Detailed tutorials are available at http://pov4grasp.free.fr 2.2 Vertexcolor pattern texture =========================== 2.2.1 Description This new pattern texture can be used with triangles to set a different color at each vertex. Works for 'triangle' and 'smooth_triangle' objects within a 'mesh' or not. This pattern may be used for a small number of triangles or as an alternative to the 'grasp_surface' object. Using this pattern is much less memory consuming than an equivalent standard macro as the TRIMAP.MCR one provided by Chris Colefax (2). 2.2.2 Syntax [texture {] pigment{ vertexcolor ,, } [}] 2.2.3 Notes * Colors order match the vertices order. * Several color definitions may be omitted. * Colors defaults are the same than the 'hexagon' pattern. 2.2.4 Example #declare tricol = texture{pigment{vertexcolor red,green,rgbt<0,0,1,0.5>}} triangle { <-1,0,0><0,1,0><1,0,0> texture{tricol} } 2.3 fog_start in constant/ground fog ================================ 2.3.1 Description Using fog_start allows to define a starting boundary from the camera for constant fog and ground fogs. This may be useful to setup a depth-cueing effect. The keyword replaces the previous use of fog_offset which was incompatible with ground fog (fog type 2) definition. 2.3.2 Example fog{ fog_type 1 fog_start 35 distance 20 color rgb 1.0 } 2.3.3 Notes * fog_start value must be positive, and defaults to 0. * At (fog_start+distance) you get 36.8% of visibility as for normal fog, although afterwards the visibility decreases faster. 2.4 Camera motion blur (experimental) ================== 2.4.1 Description Using camera motion blur will simulate the move of the camera, not objects. This is to be used e.g. when the camera is flying over a landscape. It may be used together with the focal blur effect since the implementations are based roughly on the same scheme. This feature is designed to create more realistic animations (not jerky) in a simple manner than using a lot of averaged frames to achieve good results. It should be also much faster, since the scene is parsed only once for each frame, and the rendering process is adaptive to the amounts of camera moves. 2.4.2 Syntax camera { [...] // camera specifications move_factor float-number // in 0..1 range, 0 disables motion blur blur_samples integer-number // used also for focal blur [ location_prev ] // previous location [ look_at_prev ] // previous look_at [ confidence float-number ] // same as focal blur [ variance float-number ] [ aperture float-number ] // to add focal blur } 2.4.3 Notes * Camera motion blur is turned on when 'move_factor' and 'blur_samples' are positive numbers. It only works with perspective camera as does focal blur in POV-Ray. * 'move_factor' allows to vary the amount of blur that is produced by the camera moves (see below). It roughly plays the same role as 'aperture' in focal blur and simulates the shutter speed of the camera. A value of 1 gives the strongest motion blur effect depending on 'location_prev' and/or 'look_at_prev' parameters. * As in focal blur, 'blur_samples' affects both quality and speed of the rendering. The higher 'blur_samples' you specify, the better is the result. This parameter must be set to at least 5 in camera motion blur. * Camera moves are defined by the linear combination between its current 'location' and/or 'look_at' vectors and the equivalent "previous" vectors, namely 'location_prev' and 'look_at_prev'. This implementation is accurate enough for small moves but may be incorrect for larger ones. Setting absolute vectors versus relative translations/rotations or transformation matrix is much easier to perform complex camera moves using e.g. splines. In POV-Ray animation, these parameters can be setup through variables based on 'clock - clock_delta' if their counterparts are based on 'clock'. See the example. Defaults values are those of 'location' and 'look_at' respectively, thus leading to a static picture. * The 'confidence' and 'variance' parameters play the same role as in focal blur in order to save rendering time. * Antialiasing method 2 (see POV-Ray manual) may be used for rendering both camera motion blur and focal blur. In this respect, focal blur is no more limited to its internal, somewhat not perfect, antialiasing method. 2.4.4 Example Here is an example on how to setup a camera animation with motion blur. Camera 'location' and 'look_at' are following spline paths (defined by arrays of vectors) calculated with the Chris Colefax's SPLINE.MCR set of macros (2). In this example we use the 'spline_value' macro to get the position on the spline corresponding to the given clock value. Note that the first frame will not use camera motion blur. // spline definitions #declare thecam = create_spline( array[]{...}, ... ) #declare thelook = create_spline( array[]{...}, ... ) // camera setup camera { right x up y angle 50 location spline_value(thecam, clock) look_at spline_value(thelook, clock) // previous clock value #declare prev_clock = clock - clock_delta; // camera motion blur #if(clock != prev_clock) location_prev spline_value(thecam, prev_clock) // previous location look_at_prev spline_value(thelook, prev_clock) // previous look_at move_factor 0.33 // in 0..1 range blur_samples 29 variance 1/pow(2,10) #end } 3. REFERENCES ********** (1) GRASP Home Page http://trantor.bioc.columbia.edu/grasp (2) The POV-Ray Include File Page http://www.geocities.com/ccolefax