Animator.h

Go to the documentation of this file.

//# Animator.h: movie control for one or more WorldCanvasHolders
//# Copyright (C) 1996,1997,1999,2000
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef TRIALDISPLAY_ANIMATOR_H
#define TRIALDISPLAY_ANIMATOR_H

//# aips includes
#include <casa/aips.h>
#include <list>

//# display library includes
#include <display/DisplayEvents/WCRefreshEH.h>

namespace casa { //# NAMESPACE CASA - BEGIN

//# forwards
        class WorldCanvasHolder;
        class Animator;

// <summary>
// WorldCanvas refresh event handler for Animator class.
// </summary>
//
// <synopsis>
// This class is a simple implementation of a WCRefreshEH which
// passes WorldCanvas refresh events on to an Animator object.
// </synopsis>

        class AnimatorRefEH : public WCRefreshEH {
        public:
                AnimatorRefEH(Animator *animator);
                virtual ~AnimatorRefEH() {};
                virtual void operator()(const WCRefreshEvent &ev);
        private:
                Animator *itsAnimator;
        };

// <summary>
// Animation controller for WorldCanvasHolders.
// </summary>
// <use visibility=export>
//
// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
// </reviewed>
//
// <prerequisite>
//   <li> Attribute
//   <li> AttributeBuffer
//   <li> WorldCanvasHolder
//   <li> DisplayData
// </prerequisite>
//
// <etymology>
// An Animator animates animations
// </etymology>
//
// <synopsis>
//  TBW
// </synopsis>
// <example>
//
// First example is making a simple movie of all the
// channels in a data cube
//
// <srcblock>
// // Create a PixelCanvas for X11 to draw on
// X11PixelCanvas(parent, xpcctbl, width, height) ;
// // and a World casacore::Coordinate  interface for this PixelCanvas
// WorldCanvas  wCnvs(&pixelCnvs);
//
// // Create a WorldCanvasHolder
// WorldCanvasHolder wCnvsHldr(&wCnvs);
//
// // Create an ImageDisplayData object of the data cube to display the
// // channels (assuming 3rd axis is velocity in this cube)
// ImageDisplayData cube(myDataSet, 0, 1, 2);
// // and register this with the WorldCanvasHolder
// wCnvsHldr.addDisplayData(&cube);
//
// // Create an Animator for the WorldCanvasHolder and register the
// // WorldCanvasHolder
// Animator animator;
// animator.addWorldCanvasHolder(&wCnvsHldr);
//
// // start with first channel
// animator.setMin(0.0);
// // last channel of cube (assuming it has 30 channels)
// animator.setMax(29.0);
// // go in steps of one channel
// animator.setStep(1.0);
// // only one channel at a time, so tolerance must be less than 1.0
// anomator.setTolerance(0.1);
// // display new channel every 0.2 sec
// animator.setUpdateInterval(0.2);
// // we want a normal boring movie
// animator.setNextMode(animator::NEXT_FORWARD);
// // and we define the channel (ie index)
// animator.setMatchMode(Animator::MATCH_INDEX);
// // set the Update method
// animator.setUpdateMode(Animator::UPDATE_DIRECT);
// // and start the movie
// animator.startMovie();
//       .
//       .
//       .
// // After a while we want to change to Rock & Roll mode:
// animator.setMovieMode(Animator::NEXT_ROCKandROLL);
//       .
//       .
//       .
// // and after another while we stop
// animator.stopMovie();
// </srcblock>
// Second example is that we want to blink between channel 20 of the previous
// cube and an optical image
// <srcblock>
// // Create an ImageDataDisplay of the image and register with
// // the WorldCanvasHolder
// ImageDataDisplay image(myImage, 0, 2);
// wCnvsHldr.addDisplayData(&image);
//
// // Create a casacore::List to contain the AttributeBuffers
// casacore::List<void *> buffList;
// // and an iterator for this list
// casacore::ListIter<void *> it(&buffList);
//
// // Create AttributeBuffers and fill them
// AttributeBuffer atBuff1;
// // This is to mark the cube. The name and value of the Attribute or
// // Attributes that can be used is arbitrary, as long as the different
// // AttributeBuffers in the casacore::List select different datasets (even that is
// // not really necessary, but you will be blinking between the same frames
// // and not many people will get excited about that....)
// atBuff1.add("AjaxWordtKampioen", "yes");
// it.addRight((void *) &attBuff1);
//
// // the buffer for the image
// AttributeBuffer atBuff2;
// atBuff2.add("AjaxWordtKampioen", "of course");
// at.addRight((void *) &attBuff2);
//
// // and set this list on the Animator
// animator.setBlinkList(&buffList);
//
// // Set the same attributes on the DisplayDatas so the Attribute matching
// // mechanism between the WorldCanvasHolder and the DisplayDatas will select
// // the right data at the right time automatically
// cube.addAttribute(attBuff1);
// image.addAttribute(attBuff2);
//
// // Tell animator to use channel 20
// animator.gotoCoord(20.0);
// // The Animator should write "zIndex" to select channel 20
// animator.setMatchMode(Animator::MATCH_INDEX);
// // Because we set the UpdateMode to UPDATE_BLINK, the zIndex does
// // not change each time the timer goes off.
// animator.setUpdateMode(Animator::UPDATE_BLINK);
// // and the blinking can start:
// animator.startMovie();
//       .
//       .
//       .
// // After a while we want to blink between channel 19 and the optical image.
// // this is done by setting NextMode to NEXT_BACKWARD and invoke nextCoord().
// // Of course we could also have used only animator.prevCoord(), but just
// // to show the principle...
// animator.setNextMode(Animator::NEXT_BACKWARD);
// animator.nextCoord();

//
// // We can add a third data set, set "AjaxWordtKampioen" to "always" for that data,
// // and the blinking is between 3 datasets:
//
// // stop the blinking
// animator.stopMovie();
//
// // Create DisplayData from data
// ImageDataDisplay image2(mySecondImage, 0, 2);
//
// // Add to WorldCanvasHolder
// wCnvsHldr.addDisplayData(&image2);
//
// //Setup AttributeBuffer
// AttributeBuffer atBuff3;
// atBuff3.add("AjaxWordtKampioen", "always");
//
// // add to data
// image2.addAttribute(attBuff3);
//
// // and add to List
// at.addRight((void *) &attBuff3);
//
// // set the updated list on the animator (strictly speaking not neseccary
// // here, because animator already has the address of this casacore::List, but...)
// animator.setBlinkList(&buffList);
//
// //and go!!!
// animator.startMovie();
// </srcblock>
// The third example is to run movies, selected on world coordinates on two
// WorldCanvasHolders in synch:
// <srcblock>
// // Create a PixelCanvas for X11 to draw on
// X11PixelCanvas(parent, xpcctbl, width, height) ;
// // and two  WorldCanvases side by side on the same PixelCanvas
// WorldCanvas wCnvs1(&pixelCanvas, 0.0, 0.25, 0.5, 0.5);
// WorldCanvas wCnvs2(&pixelCanvas, 0.5, 0.25, 0.5, 0.5);
//
// // A WorldCanvasHolder for each WorldCanvas
// WorldCanvasHolder wCnvsHldr1(&wCnvs1);
// WorldCanvasHolder wCnvsHldr2(&wCnvs2);
//
// // We have an HI data cube of an object
// ImageDisplayData HIcube(HIdata, 0, 1, 2);
// // that we display on the first WorldCanvas
// wCnvsHldr1.addDisplayData(HIcube);
//
// // and we have a CO cube of the same object that we display on the second
// // WorldCanvas
// ImageDisplayData COcube(COdata, 0, 1, 2);
// wCnvsHldr2.addDisplayData(COcube);
//
// // Create an animator and register the two WorldCanvasHolders
// Animator animator;
// animator.addWorldCanvasHolder(wCnvsHldr1);
// animator.addWorldCanvasHolder(wCnvsHldr2);
//
// // Set the movie parameters:
// // Select on world coordinate (ie velocity)
// animator.setMatchMode(Animator::MATCH_WORLD);
// // start and end velocities
// animator.setMinAndMax(1200.0, 1400.0);
// // and the tolerance to 10.0 and the step to 20.0
// animator.setTolerance(10.0):
// animator.setStep(20.0);
//
// // Set speed of movies and the mode
// animator.setUpdateInterval(0.2);
// animator.setNextMode(Animator::ROCKandROLL);
//
// // Now, on the first canvas a movie will be played of the HI data, and on
// // the second canvas a movie of the CO data. Because the selection is done
// // on world coordinate, the two movies display the data of the same
// // velocity (within the tolerance of 10.0), in steps of 20.0, synchronized,
// // regardless of the channel separation of the two datasets:
// animator.startMovie();
//
// </srcblock>
// </example>
//
//
// <motivation> To allow for easy control of movies, possibly synchonous on
// more than one WorldCanvas, as well as lay the basis for the userinterface
// for this, a central class is needed that controls sequences of DisplayData.
// </motivation>
//
// <todo>
//   <li> make Animator know about Units
// </todo>

        class Animator {

        public:

                // Defines the way the Animator calculates the Z coordinate of the next
                // frame in the sequence. This defines the behaviour of the member
                // nextCoord().
                enum NextMode {
                    // Movie in forward direction. Step is added, if the Z coordinate is larger
                    // than maximum then display minimum, increment again until maximum, etc.
                    // This is the default.
                    NEXT_FORWARD,
                    // Movie in backward direction. Step is subtracted, if Z coordinate is
                    // smaller than mimnimum then display maximum, decrement until minimum,
                    // etc etc
                    NEXT_BACKWARD,
                    // Movie goes up and down the sequence. Step is added until the Z
                    // coordinate is larger than maximum, then step is subtracted until the Z
                    // coordinate is smaller than minimum, then step is added, and so on, and
                    // so on
                    NEXT_ROCKANDROLL
                };

                // Defines wheter the sequence is defined using the index in the sequence or
                // by the world coordinate of the 'Z-axis' (the "zValue" or "zIndex" used by the
                // WorldCanvasHolders and the DisplayDatas), or only by the AttributeBuffers
                enum MatchMode {
                    // casacore::Sequence is defined by writing Attribute "zIndex" with the value of the
                    // Z coordinate to WorldCanvasHolders, plus the ones from the casacore::List of
                    // AttributeBuffers.
                    // This is the default
                    MATCH_INDEX,
                    // casacore::Sequence is defined by writing Attribute "zValue"with the value of the
                    // Z coordinate to WorldCanvasHolders, plus the ones from the casacore::List of
                    // AttributeBuffers
                    MATCH_WORLD,
                    // Only the Attributes from the casacore::List of AttributeBuffers are written
                    MATCH_LIST_ONLY
                };

                // Decides whether the Z coordinate should be changed according to the
                // NextMode before each update or not
                enum UpdateMode {
                    // Do change the Z coordinate before each update. Use this for 'normal
                    // movies'.
                    // This is the default.
                    UPDATE_DIRECT,
                    // Do not change Z coordinate, but rely on the AttributeBuffers to change
                    // what is displayed. Use this for blinking.
                    UPDATE_BLINK
                };



                // Constructor
                Animator();

                //Destrutor
                virtual ~Animator();

                // Go to next Z coordinate in sequence
                virtual void nextCoord();

                // Go to previous Z coordinate in sequence
                virtual void prevCoord();

                // Go to  Z coordinate zCoord
                virtual void gotoCoord(casacore::Double zCoord);

                // Set increment in the Z coordinate for the movie
                // <group>
                virtual void setStep(casacore::uInt zIncrement);
                virtual void setStep(casacore::Double zIncrement);
                // </group>

                // Set the tolerance in the Z coordinate
                // <group>
                virtual void setTolerance(casacore::uInt tolerance);
                virtual void setTolerance(casacore::Double tolerance);
                // </group>

                // Set the minimum and maximum Z coordinate for the movie
                virtual void setMinAndMaxCoord(casacore::Double zMin, casacore::Double zMax);

                // Set whether "zIndex", "zValue" or none of the two should be written
                // additionally to the AttributeBuffers.
                virtual void setMatchMode(Animator::MatchMode match);


                // Set the way the increments are done, ie. it defines the action of
                // nextCoord() (options NEXT_FORWARD, NEXT_BACKWARD, UPDATE_ROCKANDROLL)
                virtual void setNextMode(Animator::NextMode  mode);


                // Set whether an increment should be done before each update (UPDATE_DIRECT or
                // UPDATE_BLINK)
                virtual void setUpdateMode(Animator::UpdateMode mode);

                // Set update interval of movie in milliseconds
                virtual void setUpdateInterval(casacore::Double interval);

                // Set the list of additional Attributes that the Animator  places on the
                // WorldCanvasHolders before each update.
                virtual void setBlinkRestrictions(std::list<void *> *attBuffers);

                // Remove the casacore::List with AttributeBuffers
                virtual void clearBlinkRestrictions();

                // Stop and start movie
                // <group>
                virtual void startMovie();
                virtual void stopMovie();
                // </group>

                // Return the length of the movie. In UpdateMode UPDATE_DIRECT this is the
                // number of frames that follow from the minimum and maximum Z coordiante
                // and the step. In UPDATE_BLINK mode this is the length of the casacore::List of
                // AttributeBuffers set on the Animator using setBlinkAttributes
                virtual casacore::uInt getMovieLength();

                // Return the current position in the movie.  This is really a bad
                // thing, but needed in the interim for the viewer.
                virtual casacore::Int getCurrentPosition();

                // Reset the Animator. This will set the minimum coordiante to 0, the
                // maximum to the number of elements registered with the WorldCanvasHolders,
                // the step to 1.0 and the update mode to MATCH_INDEX
                virtual void reset();

                // Add a WorldCanvasHolder to the list controlled by this Animator
                virtual void addWorldCanvasHolder(WorldCanvasHolder *newHolder);

                // Remove a WorldCanvasHolder from the list controlled by this Animator
                virtual void removeWorldCanvasHolder(WorldCanvasHolder& holder);

                // Refresh event handler - just used to see if resetCoordinates was
                // set.  If so, then we should partially reset the animator.
                virtual void operator()(const WCRefreshEvent& ev);

        private:

                // casacore::List of WorldCanvasHolders
                std::list<void *> holderList;

                // casacore::List of the AttributeBuffers
                std::list<void *> *attBufList;

                // parameters of movies
                casacore::Double minCoord;
                casacore::Double maxCoord;

                // Increment for computing currentCoord. Always postive
                casacore::Double movieStep;

                // State variables
                // Tolerance for coordinate Restriction
                casacore::Double coordTolerance;
                // Current Z coordiante
                casacore::Double currentCoord;
                // the MatchMode
                Animator::MatchMode matchMode;
                // the NextMode
                Animator::NextMode nextMode;
                // The UpdateMode
                Animator::UpdateMode updateMode;
                // and the interval of the timer
                casacore::Double updateInterval;

                // The number of the AttributeBuffer to use. Computed by computeNewCoord()
                // Has to be casacore::Int, not casacore::uInt! (because I sometimes subtract 1!)
                casacore::Int numberInList;

                // In which direction the movie is currently going
                casacore::Int movieDirection;

                // Compute, based on the UPDATE_MODE and NEXT_MODE, the Z coordinate of the
                // new frame to display (ie. the new currentCoord). If the updateMode ==
                // UPDATE_BLINK, nothing happens. If the updateMode == UPDATE_DIRECT, the
                // value of currentCoord is incremented or decremented with the absolute
                // value of movieStep, depending in whether the next_Mode is NEXT_FORWARD,
                // NEXT_BACKWARD or NEXT_ROCKANDROLL and whether the new value goes outside
                // the bounds set by minCoord and maxCoord.
                void computeNextCoord(casacore::Int addOrSubtract);

                // Helper routine for computeNewCoord(). If addOrSubtract > 0, 1 is added to
                // number, if addOrSubtract < 0, 1 is subtracted
                void increment(casacore::Int& number, casacore::Int addOrSubtract);

                // Helper routine for computeNewCoord(). The inverse of <src>increment(casacore::Int&,
                // casacore::Int)</src>
                void decrement(casacore::Int& number, casacore::Int addOrSubtract);

                // Helper routine for computeNewCoord(). If addOrSubtract > 0, movieStep is added to
                // number, if addOrSubtract < 0, movieStep is subtracted
                void increment(casacore::Double& number, casacore::Int addOrSubtract);

                // Helper routine for computeNewCoord(). The inverse of <src>increment(casacore::Double&,
                // casacore::Int)</src>
                void decrement(casacore::Double& number, casacore::Int addOrSubtract);


                // Write the necessary Attributes to all the WorldCanvasHolders. The content
                // of one of the registered AttributeBuffer is always written. If the
                // updateMode == UPDATE_DIRECT the n-th AttributeBuffer is written, where n
                // is the sequence number of the frame, based on minCoord and movieStep. If
                // the updateMode == UPDATE_BLINK the Animator just loops through the list
                // of AttributeBuffers based on numberInList.
                // If MatchMode == MATCH_INDEX also an Attribute is written with name
                // "zIndex" and with the value of currentCoord.
                // If MatchMode == MATCH_COORD also an Attribute is written with name
                // "zValue" and with the value of currentCoord.
                void writeRestrictions();

                // Invoke refresh() on all the WorldCanvasHolders registered with the
                // Animator
                void refresh();

                // Return the number of AttributeBuffers in the casacore::List of AttributeBuffer
                casacore::Int listLen();

                // refresh event handler
                AnimatorRefEH *itsAnimatorRefEH;

        };


} //# NAMESPACE CASA - END

#endif