Commits

Nathan Goldbaum committed 2496596

Adding docs and a cookbook recipe for OffAxisProjectionPlot. Closes #489.

Comments (0)

Files changed (3)

source/cookbook/offaxis_projection_colorbar.py

 # automatically.
 L = [0.5, 0.4, 0.7]
 
-# Our "width" is the width of the image plane as well as the depth.
-# The first element is the left to right width, the second is the
-# top-bottom width, and the last element is the back-to-front width
+# Here, W is the width of the image. The first element is the left to right
+# width, the second is the top-bottom width.  D, specified seperately, is the
+# back-to-front width.  The widths can be specified in code units by supplying a
+# a list of floats or in arbitrary physical units by supplying a list of (width,
+# unit) tuples.
+# physical units by 
 # (all in code units)
-W = [0.04,0.04,0.4]
+W = [(40,'kpc'),(40,'kpc')]
+D = (40,'kpc')
 
-# The number of pixels along one side of the image.
-# The final image will have Npixel^2 pixels.
-Npixels = 512
+# Now we create an OffAxisProjectionPlot. Note that we set no_ghost equal to
+# False, so that we *do* include ghost zones in our data.  This takes longer to
+# calculate, but the results look much cleaner than when you ignore the ghost
+# zones.  Also note that we set the field which we want to project as "Density",
+# but really we could use any arbitrary field or list of fields (e.g
+# "Temperature", or ["Metallicity","VorticitySquared"]).
+image = OffAxisProjectionPlot(pf, L, "Density", center=c, width=w, depth=d)
 
-# Now we call the off_axis_projection function, which handles the rest.
-# Note that we set no_ghost equal to False, so that we *do* include ghost
-# zones in our data.  This takes longer to calculate, but the results look
-# much cleaner than when you ignore the ghost zones.
-# Also note that we set the field which we want to project as "Density", but
-# really we could use any arbitrary field like "Temperature", "Metallicity"
-# or whatever.
-image = off_axis_projection(pf, c, L, W, Npixels, "Density", no_ghost=False)
-
-# Image is now an NxN array representing the intensities of the various pixels.
-# And now, we call our direct image saver.  We save the log of the result.
-write_projection(image, "offaxis_projection_colorbar.png", 
-                 colorbar_label="Column Density (cm$^{-2}$)")
+# Image is now an instance of PWViewerMPL, just like the other plot window
+# plots.  It can be saved to disk very easily:
+filename = image.save()

source/visualizing/plots.rst

 :class:`~yt.visualization.plot_window.PlotWindow` interface is useful for
 taking a quick look at simulation outputs.  The ``PlotCollection`` interface
 was previously used to generate all types of plots, but is now primarily left
-as a mechanism for easily generating profile and phase plots.
+as a mechanism for generating profile and phase plots.
 
 .. _simple-inspection:
 
-Simple Data Inspection
-----------------------
+Visual Inspection
+-----------------
 
 If you need to take a quick look at a single simulation output, ``yt``
 provides the ``PlotWindow`` interface for generating annotated 2D
 is requested of it -- for instance, when the width or field is changed
 -- this high-resolution data is then pixelized and placed in a buffer
 of fixed size. This is accomplished behind the scenes using
-:class:`yt.visualization.fixed_resolution.FixedResolutionBuffer`.
-``PlotWindow`` plots expose the underlying matplotlib ``figure`` and
-``axes`` objects, making it easy to add new annotations.
+:class:`yt.visualization.fixed_resolution.FixedResolutionBuffer``
+``PlotWindow`` expose the underlying matplotlib ``figure`` and
+``axes`` objects, making it easy to customize your plots and 
+add new annotations.
 
 .. _slice-plots:
 
 
    from yt.mods import *
    pf = load("RedshiftOutput0005")
-   slc = SlicePlot(pf, 'z', 'Density',[0.2,0.3,0.8],(20,'kpc'))
+   slc = SlicePlot(pf, 'z', 'Density', [0.2,0.3,0.8], (20,'kpc'))
    slc.save()
 
 The above example will display an annotated plot of a slice of the
 ~~~~~~~~~~~~~~~~
 
 Using a fast adaptive projection, ``yt`` is able to quickly project
-simulation data along the coordinate axes.  Off-axis projections are
-also available, although only as a raw image file (see
-:ref:`cookbook-offaxis_projection`).
+simulation data along the coordinate axes.
 
 Projection plots are created by instantiating a
 :class:`~yt.visualization.plot_window.ProjectionPlot` object.  For
 :class:`~yt.visualization.plot_window.OffAxisSlicePlot` for the full
 class description.
 
-In-Depth Data Visualization
----------------------------
+.. _off-axis-projections:
+
+Off Axis Projections
+~~~~~~~~~~~~~~~~~~~~
+
+Off axis projection plots .  Internally, off axis projections are
+created using :ref:`the-camera-interface` by applying the
+:class:`~yt.visualization.volume_rendering.transfer_functions.ProjectionTransferFunction`.
+In this use case, the volume renderer casts a set of plane
+parallel rays, one for each pixel in the image.  The data values
+along each ray are summed, creating the final image buffer.
+
+.. _off-axis-projection-function:
+
+To avoid manually creating a camera and setting the transfer
+function, yt provides the :func:`~yt.visualization.volume_rendering.camera.off-axis-projection`
+function, which wraps the camera interface to create an off axis
+projection image buffer.  These images can be saved to disk or
+used in custom plots.  This snippet creates an off axis
+projection through a simulation.
+
+.. code-block:: python
+
+   from yt.mods import *
+   pf = load("RedshiftOutput0005")
+   L = [1,1,0] # vector normal to cutting plane
+   north_vector = [1,-1,0]
+   W = [0.2, 0.2, 0.2]
+   N = 512
+   image = off_axis_projection(pf, c, L, W, N, "Density")
+   write_image(na.log10(image), "%s_offaxis_projection.png" % pf)
+
+Here, ``W`` is the width of the projection in the x, y, *and* z
+directions.
+
+One can also generate generate annotated off axis projections
+using
+:class:`~yt.visualization.plot_window.OffAxisProjectionPlot`. These
+plots can be created in much the same way as an
+``OffAxisSlicePlot``, requiring only an open dataset, a direction
+to project along, and a field to project.  For example:
+
+.. code-block:: python
+
+   from yt.mods import *
+   pf = load("RedshiftOutput0005")
+   L = [1,1,0] # vector normal to cutting plane
+   north_vector = [1,-1,0]
+   prj = OffAxisProjectionPlot(pf,L,'Density',north_vector=north_vector)
+   prj.save()
+
+OffAxisProjectionPlots can also be created with a number of
+keyword arguments, as described in the `api reference`__ for the
+class initializer.
+
+__ :class:`~yt.visualization.plot_window.OffAxisProjectionPlot`
+
+Quantative Analysis and Visualization
+-------------------------------------
 
 The second plotting interface, based on the
 :class:`~yt.visualization.plot_collection.PlotCollection` class, is

source/visualizing/volume_rendering.rst

 .. image:: _images/vr_sample.jpg
    :width: 512
 
-.. _the_camera_interface:
+.. _the-camera-interface:
 
 The Camera Interface
 --------------------
 
 The Simple Volume Rendering Interface
 -------------------------------------
-.. warning:: This has been removed in yt-2.3.  Please use :ref:`the_camera_interface`.
+.. warning:: This has been removed in yt-2.3.  Please use :ref:`the-camera-interface`.