.. _synthetic_data_generator:

Synthetic Data Generator
========================

The built in synthetic data generator allows for the creation of images
containing objects with known velocities to test the image processing and
tracking algorithms as well as deduce the limits of the techniques.

.. image:: ../gifs/synthetic.gif
    :align: center

There are three methods of producing these images that can be selected from the
``Particle generator`` drop-down list:

1. gaussian - Seeds the centers of the object with colored pixels, then performs
   a gaussian blur using `scipy.ndimage.filter.gaussian_filter <https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html>`_
2. circle - Uses `cv2.circle <https://docs.opencv.org/master/d6/d6e/group__imgproc__draw.html#gaf10604b069374903dbd0f0488cb43670>`_
   to draw circles at the object locations.
3. template - copies and blends selected ``*png`` files with transparency at the
   object locations.

A number of other parameters can be changed including:

1. The particle count can be changed using the ``Particle count`` spinner.
2. The particle radius in pixels can be changed by changing the ``from`` and
   ``to`` spinner values. The actual radius is randomly chosen from that
   range.
3. The particle intensity (the actual pixel values of the particle, 0-255) can
   be selected by changing the ``from`` and ``to`` spinner values. The actual
   intensity is randomly chosen from that range.
4. The particle velocities can be selected by changing the ``x from``, ``x to``,
   ``y from``, and ``y to`` spinner values. As with the other ranges, the
   actual velocities will be randomly chosen from that range.
5. The particle acceleration can be selected by changing the ``x from``,
   ``x to``, ``y from``, and ``y to`` spinner values. As with the other ranges,\
   the actual velocities will be randomly chosen from that range.
6. The number of frames can be selected by entering a value in the ``Frames``
   spinner.
7. The width and height, in pixels, can be changed by entering values in the
   ``Width`` and ``Height`` spinners.
8. The level of random noise can be changed by entering a value in the ``noise``
   spinner. Noise is created by building a random array and adding to the frame
   (:math:`g(i,j) = f(i,j)+n(i,j)`). Any resulting values greater than 255 are
   truncated to 255.
9. The wall interaction between the particle and the wall can be
   changed using the ``Walls`` drop-down list.
10. The restitution coefficient can be changed by using the ``restitution``
    spinner

After the images have been tracked, when displaying the histogram on the post
tab, both the measured and true synthetic distributions are plotted.

.. image:: ../images/synth_compare.png
    :align: center