View source for Customized video montages

Video montages are widely used in ''Dynamo'' to show in a single montage part of a stream of data. The user can slide on the subset of the data that is represented at a given moment. Examples of this are found in the slider GUIs used to explore sets of particles, slices inside a given volume, or selections of gold beads.

In this page, we explain how to use the underlying ''Dynamo'' objects to create your own visualization systems. We explain two possible approaches:

* Inline montages
Can be defined easily from the command line without definition of further classes.
* Subclassed montages
Advanced method. This method offers full flexibility at the cost of requiring from the user the creation of new classes.

== Inline montages ==

You can use the class <tt>mbvid.guis.montages.cells.Inline</tt>, that allows inline definition of the action to be computed at each frame. 
For instance, imagine that you have a set of 1000 vectors, and you want to quickly explore their histograms separately.  Let's generate a random data set:.
 
 <nowiki> for k=1:1000;
  myData{k} = randn(20000,1); 
end</nowiki>

For 1000 elements, you probably don't want to show them all in a single screen, but rather slide through the data. Thus,  we create the object that represents the GUI
 
 <nowiki>  gui = mbvid.guis.montages.cells.Inline(); </nowiki>

we link now this object with the stream of data

   <nowiki> gui.setVideo(myData); </nowiki>

My data is a [[matlab cell array]] in this example, but you could pass any other object that implicitly defines an stream of data. If you pass, for instance, a volume of dimensions <tt>lx x ly x lz</tt>, the stream will be defined as a succesion on <tt>lz</tt> frames.

Now, we have to tell the GUI object what to do on each frame. This is done by defining the method  <tt>depictorOnAxesFcn</tt> to be an inline function of two variables. The first is a dummy variable that represents the content of the stream for a given frame. The second is the graphical axis associated to the frame in the montage. Thus:

 <tt>gui.depictorOnAxesFcn = @(x,haxis) hist(haxis,x(:),100);</tt>

This command reads as: "for a frame in position <tt>i</tt>, take the position <tt>i</tt> in the stream (i.e., the <tt>i</tt>-th entry in the cell array <tt>myData</tt>  associated to the <tt>gui</tt> object), and show its histogram (with 100 bins) on the axis associated to the frame". 

Now we are ready to go:

 <tt>  gui.show();</tt>

[[File:CustomVideoMontageInline.png |thumb|center|500px| Customized video montage to show the histograms of a cell array of vectors. ]]

== Subclassed montages ==

Using this options involves a minimal comprehension of Object Oriented Programming. The underlying generic class for video montages is <tt>mbvid.guis.Montage</tt>. 

=== Basic use of a video Montage object===

Showing  the GUI of an user-defined subclass  <tt>myVideoMontage</tt> of <tt>mbvid.guis.Montage</tt> requires first creating the instance

 <tt>gui  = myVideoMontage;</tt>

then attaching the video stream (if it is not included in the constructor)

  <tt>gui  = myVideoMontage();</tt>

and them invoking the <tt>show</tt> method:

 <tt>gui.show();</tt>

Before the show operation, there are different options that you can assign beforehand: 
 <nowiki>rows
columns
width
height
title</nowiki>

=== Structure of a video montage object ===

A video montage object is basically the result of combining of two different types of objectc:

* An scene manager object  that runs the general layout and sliding of the scene.
* Objects of the <tt>frameManager</tt> class that control what is depicting on each panel. 

=== Frame manager class===
This object controls the creation and updating of a frame when its representation is invoked by the scene manager in the videomontage GUI.
The basic frame class is <tt>mbvid.controls.VideoMontageFrameManager</tt>. Custom frame managers  need to be subclasses of this class.

==== Defining the action of a frame ====

You need to define the method  <tt>createFrame</tt> in your subclass (let's call it <tt>myFrameManager</tt>). This will pass the properties  <tt> 'gui' </tt>, <tt>'frameNumber'</tt>, <tt> 'hPanel' </tt>.
==== Linking a frame class to a GUI ====

In order to link a <tt>frame</tt> class to a particular class of GUI, we can assign the name of the class to the <tt></tt> property of the GUI object.

 <tt>gui.frameManagerType = 'mbvid.controls.VideoMontageFrameManager' </tt>

The usual practice is to include this definition in the constructor method of the GUI, to ensure this assignation is ran before the GUI is shown.

==== Example of subclassing====

In order to create a new class, you can use the usual Matlab system, or just type:

 <tt>mbnew myFrameManager . mbvid.controls.montageFrameManager </tt>

which will open the editor with this predefined content for the class <tt>@myFrameManager</tt>, created in the current directory.

  <nowiki>%
% class definition
%
classdef myFrameManager < mbvid.controls.montageFrameManager
  
    properties 
  
    end 
  
  
    methods 
  
       function obj=myFrameManager(varargin)
  
             obj=obj@mbvid.controls.montageFrameManager(varargin{:});
       end
              
  
    end 
  
end </nowiki>

You can the define the method <tt>createFrame()</tt> inside this file, using the properties  <tt> 'gui' </tt>, <tt>'frameNumber'</tt>, <tt> 'hPanel' </tt> that will be available in the <tt>obj</tt> during runtime. With 

 <tt>dlookfor createFrame </tt>

you can find examples  across ''Dynamo'' that implement this method in different subclasses. In our case, imagine that we want to plot a sine of the -sorted- values of the data contained in each stream entry. Moreover, in this sine we want to use a frequency that changes linearly with the number of frame. This requirement already sets us outside of the realm of   [[Customized Video Montages #Inline montages| inline montages]], as we cannot enter the number of frame in the dependencies of the customizing function <tt>gui.depictorOnAxesFcn</tt>.

Further, for this example we introduce a modification of the plotting axes themselves, making them cover the full panel object, also overcoming the limitation of inlines of type  <tt>mbvid.guis.montages.cells.Inline</tt>. We just provide the class <tt>myFrameManager</tt> with the method <tt>createFrame</tt> 

 <nowiki>       function createFrame(obj);
           haxis = axes('Parent',obj.hPanel);
           
           set(haxis,'Position',[0,0,1,1]);
           
           myVideo = obj.gui.getVideo();
           myData = myVideo.read(obj.frameNumber);  
           
           % change the data differently for each frame
           representedData = sin(sort(myData)*obj.frameNumber);
           plot(representedData,'Parent',haxis);
       end </nowiki>

This can be typed into the class file itself, or in the class folder (after declaring the method signature in the class file). With this definition, we could use as basis the general class <tt>mbvid.guis.VideoMontage</tt>.

You also '''need''' to provide and  <tt>updateFrame</tt>, which will be triggered each time we change the scene. This is the actual art of designing video montages and specifically subclasses of frameManager. Here, you should normally provide your class with further properties to store and reuse graphic elements or already available computations, so that they don't need to be recreated each time new frames are generated or recalled.... but in simple applications, you can also avoid over-engineering by simply invoking again the creation of the frame.
       
<nowiki>        function updateFrame(obj);
            % Just recreates the frame
            % Not recommended for performance-critic applications
            obj.createFrame();
       end </nowiki>



 <tt>a = mbvid.guis.VideoMontage();</tt>

but linking it to the type of frame behaviour we just defined: 

 <tt>a.frameManagerType = 'myFrameManager'; </tt>

If we now link the stream of data that we defined previously:

 <tt>a.setVideo(myData);</tt>

we can now show the video montage:

 <tt>a.show();</tt>

[[File:CustomVideoMontageSineRandom.png |thumb|center|500px| Customized video montage based on the subclassing of the standard <tt>frameManager</tt>. ]]