Geografic-Information-System/raster3d/r3.out.vtk/r3.out.vtk.html

<H2>DESCRIPTION</H2>

Outputs <I>3D raster</I> maps into <I>VTK-ASCII</I> format.  <I>Maps</I> are
valid 3D raster maps in the current mapset.  <I>output</I> is the name of
a VTK-ASCII file which will be written in the current working directory.
If <I>output</I> is not specified then <B>stdout</B> is used.  
The module is sensitive to region settings (set with <em>g.region</em>).

<H2>NOTES</H2>
This filter generates <I>structured points</I>  with <I>celldata</I> 
(default) or <I>pointdata</I>. If top and bottom surfaces are requested
a <I>unstructured grid</I> with <I>celldata</I>  or a <I>structured grid</I>
with <I>pointdata</I> is generated.
This data is put in a simple VTK-ASCII file. Neither XML nor 
binary output are supported. It is possible to choose more then one G3D map
to be written in the VTK-ASCII file. Each <I>celldata</I> is named as the
3D raster map it represents. You can visualize this file with the 
<EM><A HREF="http://www.vtk.org">VTK Toolkit</A></EM>, 
<EM><A HREF="http://www.paraview.org">Paraview</A></EM> and 
<EM><A HREF="http://mayavi.sourceforge.net">MayaVi</A></EM> which are based on VTK.
If you have a 3D raster map with partly no data, use the threshold filter in paraview to 
visualize the valid data. Just filter all data which is greater/lesser than the 
chosen null value in the VTK-ASCII file.

<BR><BR>
The top and bottom region settings are expected in meters. 
If a Latitude-Longitude (LL) coordinates are used, the elevation value for each voxel
will be converted into degree.
<BR><BR>
The <I>input</I>, <I>rgbmaps</I> and <I>vectormaps</I> are optional, 
so only the geometry can be exported.
<BR><BR>
If you use <I>top</I> and <I>bottom</I> and the 2D and 3D region settings are different,
the 2D resolution will be adjust to the 3D resolution. The elevation maps are expected
in meters. If LL coordinates are used, the elevation will automatically converted into degree.
If the surface and bottom maps are in a different unit than meters, use the scale parameter
to convert them into meters.
<BR><BR>
The RGB voxel data can be created from 2D raster maps (Landsat TM images) 
with <EM><A HREF="r.to.rast3.html">r.to.rast3</A></EM>. The values of the RGB maps
must be within 0 and 255. If not, the values are automatically set
to 0 and warnings will be printed to stderr.
<BR><BR>
The vector data is created from three 3d raster maps. Each map represents a vector component.
So x, y and z components are required in this order. This data can be visualized with Glyph3d or 
StreamTracer filters within Paraview.
<br>
<br>
If the <em>-c</em> flag is used and the data should be visualised together with other
data exported via <em>*.out.vtk</em> modules, be sure the <em>-c</em> flag was also
set in these modules. But this will only work with data from the SAME location (the
reference point for the coordinates transformation is based on the center point of
the default region).

<H3>Difference between point- and celldata</H3>

<em>r3.out.vtk</em> can export 3D raster maps with different representations.
<ul>
   <li>
      <I>pointdata</I> -- the cells/values are represented by the center of the cell. 
      Instead of cells, points are created. Each point can hold different values, 
      but the user can only visualize one value at a time. 
   </li>
   <li>
       <I>celldata</I>  
       The cells are created with the same hight, width and depth as in GRASS. Each cell 
       can hold different values, but the user can only visualize one value at a time. 
   </li>
</ul>

<H2>EXAMPLE</H2>

<H3>Simple Spearfish example</H3>

<div class="code"><pre>
g.region -d
g.region res=150 res3=150 t=80 b=0 tbres=10
r.mapcalc "bottom=1800. - elevation.10m"

# synthetic data, could be geological structures:
r3.mapcalc "map3d=row()+col()+depth()"

#export of volume to VTK:
r3.out.vtk -s input=map3d top=elevation.10m bottom=bottom output=/tmp/out.vtk

# visualize in paraview or other VTK viewer:
paraview --data=/tmp/out.vtk
</pre></div>

<H3>Spearfish example with RGB data</H3>

<div class="code"><pre>
#set the region
g.region -d
g.region n=4926970 s=4914857 w=591583 e=607793 res=50 res3=50 t=80 b=0 tbres=10

#create a bottom surface
r.mapcalc "bottom=1800. - elevation.10m"

# synthetic data, could be geological structures:
r3.mapcalc "map3d=row()+col()+depth()"

#get some satellite images with r.in.onearth
r.in.onearth -l output=Sat tmband=Red
r.in.onearth -l output=Sat tmband=IR1
r.in.onearth -l output=Sat tmband=IR2

#Convert the 2d maps to 3d raster maps with r.to.rast3
r.to.rast3 input=SatLandsatTM_Red output=SatLandsatTM_Red
r.to.rast3 input=SatLandsatTM_IR1 output=SatLandsatTM_IR1
r.to.rast3 input=SatLandsatTM_IR2 output=SatLandsatTM_IR2

#export of volume to VTK:
r3.out.vtk -s rgbmaps=SatLandsatTM_IR1,SatLandsatTM_IR2,SatLandsatTM_Red input=map3d top=elevation.10m bottom=bottom output=/tmp/out.vtk

# visualize in paraview or other VTK viewer:
paraview --data=/tmp/out.vtk 
</pre></div>

<H3>Spearfish example with vector data</H3>

<div class="code"><pre>
# set the region
g.region -d
g.region n=4926970 s=4914857 w=591583 e=607793 res=50 res3=50 t=80 b=0 tbres=10

# create a bottom surface
r.mapcalc "bottom=1800. - elevation.10m"

# synthetic data, could be geological structures:
r3.mapcalc "map3d=row()+col()+depth()"

# synthetic vector data, could be groundwater stream vectors
r3.mapcalc "x_part =sin(row())"
r3.mapcalc "y_part =cos(col())"
r3.mapcalc "z_part =sin(depth())"


# export the stuff data to VTK:
r3.out.vtk -s vectormaps=x_part,y_part,z_part input=map3d top=elevation.10m bottom=bottom output=/tmp/out.vtk

# visualize in paraview or other VTK viewer:
paraview --data=/tmp/out.vtk 
# Now use the Glyph and Stream-Trace Filter to get nice vectors and streamlines
</pre></div>


<H3>Slovakia3d example</H3>

<div class="code"><pre>
#reduce resolution:
g.region -dp3 res=1000 res3=1000
r.mapcalc "bottom=100"

#export of volume to VTK:
r3.out.vtk -s in=precip3d.500z50 top=dem500 bottom=bottom out=/tmp/slovakia3d.vtk

# visualize in paraview or other VTK viewer:
paraview --data=/tmp/slovakia3d.vtk
# set Display style to 'surface#
# set Actor Control z to 10
</pre></div>


<H2>SEE ALSO</H2>

<EM><A HREF="r.out.vtk.html">r.out.vtk</A></EM><br>
<EM><A HREF="r3.out.ascii.html">r3.out.ascii</A></EM><br>
<EM><A HREF="g.region.html">g.region</A></EM><br>

<H2>AUTHOR</H2>
Soeren Gebbert

<p><i>Last changed: $Date$</i>