.. picture tutorial

Pictures in Pynbody
===================

Density Slice
-------------
The essential kind of image -- a density slice:

.. plot:: tutorials/example_code/density_slice.py
   :include-source:

Integrated Density
------------------
Line-of-sight averaged density map:

.. plot:: tutorials/example_code/density_integrated.py
   :include-source:

Temperature Slice
-----------------
Simple example for displaying a slice of some other quantity (Temperature
in this case)

.. plot:: tutorials/example_code/temperature_slice.py
   :include-source:

Velocity Vectors
----------------
It is also straightforward to obtain an image with velocity
vectors or flow lines overlaid:

.. plot:: tutorials/example_code/velocity_vectors.py
   :include-source:

Multi-band Images of Stars
--------------------------

You can create visualizations of the stellar distribution using
synthetic colors in a variety of bands:

.. plot:: tutorials/example_code/star_render.py
   :include-source:


Creating images using :func:`~pynbody.plot.sph.image`
-----------------------------------------------------

The :func:`~pynbody.plot.sph.image` function is a general purpose function
for creating an x-y map of a value from your :func:`~pynbody.snapshot.SimSnap`
object. Under the hood, the function calls one two SPH kernels (written in c)
to calculate the intensity values of whatever value you're plotting - a 2d
kernel for integrated maps, and a 3d kernel for slices. Both kernels require
the use of a kd-tree to perform an SPH smooth, so you will notice that the
first time :func:`~pynbody.plot.sph.image` is called, it creates a kd-tree.
Subsequent calls on the same data set should use the already created tree,
and thus should be faster.

:func:`~pynbody.plot.sph.image` returns an x,y array representing pixel
intensity. The function also displays the image with automatically created
axes and a colorbar. However, one can use the x-y array and `plt.imshow() <http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.imshow>`_ to create your own plot.


Common issues
-------------

:func:`~pynbody.plot.sph.image` is prone to a number of common errors
when being used by new users. Probably the most common is

::

   ValueError: zero-size array to minimum.reduce without identity

This can come about in a number of circumstances, but essentially it
means that there were not enough particles in the region that was being
plotted. It could be due to no/bad centering, passing in a very small/empty
:func:`~pynbody.snapshot.SubSnap` object, or bad units (units being an issue should
no longer be an issue. In older versions of pynbody, the width parameter
assumed kpc, so if the simulation distances were in e.g. "au", this could
cause a problem).

Another common error is the following:

::

   TypeError: 'int' object does not support item assignment

which occurs when the returned image from the kernel is a singular value
rather than an array. In this case, the issue was because the kernel did
not complete because of attempting to plot a value for the whole
:func:`~pynbody.snapshot.Snapshot` object rather than a specific family (such
as gas). In this case, the "smooth" array needed to be deleted before another
image could be produced because SPH needed to resmooth with the new dark and
star particles.
