WorldCanvas.h

Classes

WorldCanvas -- Implementation of drawing in world coordinates on top of a PixelCanvas. (full description)

class WorldCanvas : public PCRefreshEH, public PCMotionEH, public PCPositionEH, public DisplayEH, public DisplayOptions

Interface

Public Members
WorldCanvas(PixelCanvas *pc, Double xOrigin = 0.0, Double yOrigin = 0.0, Double xSize = 1.0, Double ySize = 1.0)
virtual ~WorldCanvas()
PixelCanvas *pixelCanvas() const
void addRefreshEventHandler(DisplayEH &eh)
void addMotionEventHandler(WCMotionEH &eh)
void addPositionEventHandler(WCPositionEH &eh)
void removeRefreshEventHandler(const DisplayEH &eh)
void removeMotionEventHandler(const WCMotionEH &eh)
void removePositionEventHandler(const WCPositionEH &eh)
void callMotionEventHandlers(const WCMotionEvent &ev)
void callPositionEventHandlers(const WCPositionEvent &ev)
virtual void handleEvent(DisplayEvent& ev)
void operator()(const PCRefreshEvent &pev)
void operator()(const PCMotionEvent &pev)
void operator()(const PCPositionEvent &pev)
void refresh(const Display::RefreshReason &reason = Display::UserCommand, const Bool &explicitrequest = True)
Bool refreshAllowed()
void hold()
void release()
void setCoordinateHandler(WCCoordinateHandler *ch)
void setSizeControlHandler(WCSizeControlHandler *sh)
void setResampleHandler(WCResampleHandler *rh)
void setDataScaleHandler(WCDataScaleHandler *sh)
void setWorldCanvasPosition(Double fracXOffset, Double fracYOffset, Double fracXSize, Double fracYSize)
Bool pixToLin(Vector<Double> &lin, const Vector<Double> &pix)
Bool pixToLin(Matrix<Double> &lin, Vector<Bool> &failures, const Matrix<Double> &pix)
Bool linToPix(Vector<Double> &pix, const Vector<Double> &lin)
Bool linToPix(Matrix<Double> &pix, Vector<Bool> &failures, const Matrix<Double> &lin)
Bool linToWorld(Vector<Double> &world, const Vector<Double> &lin)
Bool linToWorld(Matrix<Double> &world, Vector<Bool> &failures, const Matrix<Double> &lin)
Bool worldToLin(Vector<Double> &lin, const Vector<Double> &world)
Bool worldToLin(Matrix<Double> &lin, Vector<Bool> &failures, const Matrix<Double> &world)
Bool pixToWorld(Vector<Double> &world, const Vector<Double> &pix)
Bool pixToWorld(Matrix<Double> &world, Vector<Bool> &failures, const Matrix<Double> &pix)
Bool worldToPix(Vector<Double> &pix, const Vector<Double> &world)
Bool worldToPix(Matrix<Double> &pix, Vector<Bool> &failures, const Matrix<Double> &world)
void registerColormap(Colormap *cmap, Float weight = 1.0)
void registerColormap(Colormap *cmap, Colormap *cmapToReplace)
void unregisterColormap(Colormap *cmap)
void setColormap(Colormap *cmap)
Colormap *colormap() const
uInt newList()
void endList()
void drawList(uInt list)
void deleteList(uInt list)
void deleteLists()
Bool validList(uInt list)
void setColor(const String &color)
void setClearColor(const String &color)
Bool setFont(const String &fontName)
void setForeground(uLong color)
void setBackground(uLong color)
void setLineWidth(Float width)
void setLineStyle(Display::LineStyle style)
void setCapStyle(Display::CapStyle style)
void setJoinStyle(Display::JoinStyle style)
void setFillStyle(Display::FillStyle style)
void setFillRule(Display::FillRule rule)
void setArcMode(Display::ArcMode mode)
Bool setWorldBackgroundColor(const String color)
Bool setWorldForegroundColor(const String color)
String getWorldBackgroundColor()
String getWorldForegroundColor()
virtual void setDrawBuffer(Display::DrawBuffer buf)
Display::DrawBuffer drawBuffer() const
void setImageCacheStrategy(Display::ImageCacheStrategy strategy)
Display::ImageCacheStrategy imageCacheStrategy() const
void clear()
void clearNonDrawArea()
virtual void setDefaultOptions()
virtual Bool setOptions(const Record &rec, Record &updatedOptions)
virtual Record getOptions() const
void setAttribute(Attribute& at)
void setAttributes(AttributeBuffer& at)
void removeAttribute(String& name)
Bool getAttributeValue(const String& name, uInt& newValue) const
Bool getAttributeValue(const String& name, Int& newValue) const
Bool getAttributeValue(const String& name, Float& newValue) const
Bool getAttributeValue(const String& name, Double& newValue) const
Bool getAttributeValue(const String& name, Bool& newValue) const
Bool getAttributeValue(const String& name, String& newValue) const
Bool getAttributeValue(const String& name, Vector<uInt>& newValue) const
Bool getAttributeValue(const String& name, Vector<Int>& newValue) const
Bool getAttributeValue(const String& name, Vector<Float>& newValue) const
Bool getAttributeValue(const String& name, Vector<Double>& newValue) const
Bool getAttributeValue(const String& name, Vector<Bool>& newValue) const
Bool getAttributeValue(const String& name, Vector<String>& newValue) const
Bool existsAttribute(String& name) const
AttValue::ValueType attributeType(String& name) const
virtual void acquirePGPLOTdevice(const Bool &linear = True)
virtual void releasePGPLOTdevice()
virtual Int pgid() const
Bool drawText(const Vector<Double> &point, const String &text, Display::TextAlign alignment = Display::AlignCenter, const Bool &linear = False)
Bool drawPoint(const Vector<Double> &point, const Bool &linear = False)
Bool drawLine(const Vector<Double> &a, const Vector<Double> &b, const Bool &linear = False)
Bool drawPoints(const Matrix<Double> &points, const Bool &linear = False)
Bool drawPoints(const Vector<Float> &px, const Vector<Float> &py, Bool linear = False)
Bool drawTextStrings(const Vector<Float> &px, const Vector<Float> &py, const Vector<String> &strings, const Float rotation = 0.0, const Float xoffset = 0.0, const Float yoffset = 0.0, const Bool linear = False)
Bool drawMarkers(const Vector<Float> &px, const Vector<Float> &py, const Display::Marker = Display::Cross, const Int size = 5, const Bool& linear = False)
Bool drawMappedMarkers(const Vector<Float> &px, const Vector<Float> &py, const Vector<Float>& values, const Int sizemin = 1, const Int sizemax = 20, const Display::Marker = Display::Cross, const Bool& linear = False)
Bool drawLines(const Matrix<Double> &vertices, const Bool &linear = False)
Bool drawPolyline(const Matrix<Double> &vertices, const Bool &linear = False)
Bool drawPolygon(const Matrix<Double> &vertices, const Bool &linear = False)
Bool drawColormappedPoints(const Matrix<Double> &points, const Vector<Float> &values, const Bool &linear = False)
Bool drawColormappedEllipses(const Matrix<Double> &centres, const Vector<Float> &smajor, const Vector<Float> &sminor, const Vector<Float> &pangle, const Vector<Float> &colors, const Float &scale = 1.0, const Bool &outline = True, const Bool &linear = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Vector<Float> &levels, const Bool usePixelEdges = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Vector<Float> &levels, const Bool usePixelEdges = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Matrix<Bool> &mask, const Vector<Float> &levels, const Bool usePixelEdges = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Matrix<Bool> &mask, const Vector<Float> &levels, const Bool usePixelEdges = False)
Bool redrawIndexedImage(void* drawObj, Display::RefreshReason reason)
Bool removeIndexedImage(void* drawObj)
void clearColormapChangeCache()
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Matrix<Bool> &mask, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Matrix<Bool> &mask, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Display::ColorComponent &colorcomponent, const Bool usePixelEdges = False)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Display::ColorComponent &colorcomponent, const Bool usePixelEdges = False)
void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Complex>& data, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)
void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& data, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)
void drawMarkerMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& data, const Matrix<Bool>& mask, Int xPixelInc, Int yPixelInc, Float scale, Double xWorldInc, Double yWorldInc, const String& markeType, Bool usePixelEdges)
void drawMarkerMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Complex>& data, const Matrix<Bool>& mask, Int xPixelInc, Int yPixelInc, Float scale, Double xWorldInc, Double yWorldInc, const String& markerType, Bool usePixelEdges)
void flushComponentImages()
void copyBackBufferToFrontBuffer()
void copyFrontBufferToBackBuffer()
void swapBuffers()
Double linXMin() const
Double linYMin() const
Double linXMax() const
Double linYMax() const
Double linXMinLimit() const
Double linYMinLimit() const
Double linXMaxLimit() const
Double linYMaxLimit() const
uInt canvasXOffset() const
uInt canvasYOffset() const
uInt canvasXSize() const
uInt canvasYSize() const
uInt canvasDrawXOffset() const
uInt canvasDrawYOffset() const
uInt canvasDrawXSize() const
uInt canvasDrawYSize() const
void setZoomRectangleLCS(const Vector<Double> &min, const Vector<Double> &max)
void moveZoomRectangleLCS(double dx, double dy)
void resetZoomRectangle()
void setLinearCoordinateSystem(const Vector<Double> &blc, const Vector<Double> &trc, Bool resetZoom = True)
Double dataMin() const
void setDataMin(Double min)
Double dataMax() const
void setDataMax(Double max)
void setDataMinMax(Double min, Double max)
Display::ComplexToRealMethod complexToRealMethod() const
void setComplexToRealMethod(const Display::ComplexToRealMethod method)
void setCoordinateSystem(const CoordinateSystem &csys)
const CoordinateSystem &coordinateSystem() const
Bool inDrawArea(Int x, Int y)
Bool inWC(Int x, Int y)
Bool inPC(Int x, Int y)
Private Members
void ctorInit()
void callRefreshEventHandlers(const WCRefreshEvent &ev)
void updateCanvasSizesOffsets()
void updateFracSizesOffsets()
Bool castingConversion(Vector<Int> &pixelpt, const Vector<Double> &worldpt, const Bool &linear)
Bool castingConversion(Matrix<Int> &pixelpts, const Matrix<Double> &worldpts, const Bool &linear)
Bool castingConversion(Matrix<Float> &pixelpts, const Matrix<Double> &worldpts, const Bool &linear)
Bool castingClippingConversion(Vector<Int> &pixelx, Vector<Int> &pixely, Vector<Bool> &validConversions, const Vector<Float> &worldx, const Vector<Float> &worldy, const Bool linear)
void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& amp, const Matrix<Float>& pa, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)
void trimAndResampleImage(Vector<Double> &drawBlc, Vector<Double> &drawTrc, Matrix<Float> &sampledImage, const Vector<Double> &blc, const Vector<Double> &trc, const Matrix<Float> &data, const Bool &usePixelEdges = False)
void trimAndResampleImage(Vector<Double> &drawBlc, Vector<Double> &drawTrc, Matrix<Float> &sampledImage, Matrix<Bool> &resampledMask, const Vector<Double> &blc, const Vector<Double> &trc, const Matrix<Float> &data, const Matrix<Bool> &mask, const Bool &usePixelEdges = False)
void mapToColorAndDrawImage(const Vector<Int> &blc, const Matrix<uInt> &scaledImage)
void mapToColorAndDrawImage(const Vector<Int> &blc, const Matrix<uInt> &scaledImage, const Matrix<Bool> &mask)
Bool mapToColorAndDrawPoints(const Matrix<Double> &points, const Vector<uInt> &scaledValues, const Bool &linear = False)
Bool mapToColorAndDrawEllipses(const Matrix<Double> &centres, const Vector<Float> &smajor, const Vector<Float> &sminor, const Vector<Float> &pangle, const Vector<uInt> scaledValues, const Float &scale, const Bool &outline, const Bool &linear)
ColorIndexedImage_* getClearedColorIndexedImage(void* drawObj=0)

Description

Prerequisite

Etymology

WorldCanvas is a canvas on which primitives specified in world coordinates are drawn.

Synopsis

The world canvas manages a portion of a PixelCanvas and provides mechanisms to allow the user to draw images and vectors in world coordinates. The position of the WorldCanvas may be dynamically changed.

The WorldCanvas vector graphics commands assume world coordinates are specified and use a registered coordinate handler to map those coordinates via a linear system to pixel coordinates. The pixel coordinates are then sent on to the PixelCanvas where they are plotted.

Images are drawn by sending a Matrix and specifying the world-coordinate location of the center of the lower-left pixel. If the dataMin and dataMax values have been set, they will be used to scale the data, otherwise the min and max will be scanned.

Customizable tools associated with the WorldCanvas available to assist with various aspects of display.

The interface for these tools are implemented as abstract base classes, and the tools are implemented by deriving from these classes and overriding the functions contained therein.

The WorldCanvas provides an interface to the PixelCanvas caching mechanism. Clever use of caching and parsing of the reason field of a WCRefreshEvent can reduce unnecessary recomputation needed for refreshing the screen.

The WorldCanvas maintains a set of Attributes which the user can set on the WorldCanvas. An Attribute is a combination of a name and a value, the value can be of type uInt, Int, Float, Double, Bool and String, and Vectors of these. These Attributes serve two purposes: 1) to allow to place (using the member functions setAttribute and setAttributes) more or less arbitrary information on the WorldCanvas that other classes can read from the WorldCanvas. Since the name of an Attribute can be defined at run time, any name can be used (i.e. there is no pre-defined set of names that can only be used), and 2) to have a generic interface to some of the internal variables of the WorldCanvas. Some internal variabels can be set/read with their own interface routine (e.g. linXMin and friends using setZoomRectangleLCS), but they can also be modified/read using the Attribute interface (using getAttributeValue). The use of e.g. SetZoomRectangleLCS() and setAttribute() is equivalent. See AttributeBuffer for more details. The following Attributes (and their types) are pre-defined on the WorldCanvas and can be accessed using the Attribute interface (note: these Attributes cannot be deleted using removeAttribute()):

The WorldCanvas knows three coordinate systems.

Motivation

Wanted a world-coordinate plotting canvas

Example

See the test programs in Display/test

To Do

Member Description

WorldCanvas(PixelCanvas *pc, Double xOrigin = 0.0, Double yOrigin = 0.0, Double xSize = 1.0, Double ySize = 1.0)

Construct a WorldCanvas on the given PixelCanvas, at the given origin (in fractions of the PixelCanvas extent), and having the given size (in the same units).

virtual ~WorldCanvas()

Destructor.

PixelCanvas *pixelCanvas() const

Return a pointer to the PixelCanvas on which this WorldCanvas is installed.

void addRefreshEventHandler(DisplayEH &eh)
void addMotionEventHandler(WCMotionEH &eh)
void addPositionEventHandler(WCPositionEH &eh)

Add the given refresh, motion and position event handlers to the WorldCanvas.

void removeRefreshEventHandler(const DisplayEH &eh)
void removeMotionEventHandler(const WCMotionEH &eh)
void removePositionEventHandler(const WCPositionEH &eh)

Remove the given refresh, motion and position event handlers from the WorldCanvas.

void callMotionEventHandlers(const WCMotionEvent &ev)
void callPositionEventHandlers(const WCPositionEvent &ev)

Call all of the motion and position event handlers that are installed on the WorldCanvas.

virtual void handleEvent(DisplayEvent& ev)

Handle other, generic types of events. As with call*Handlers above, WC handles these new events by simply distributing them to event handlers registered on it. However, rather than create any more handler lists in WorldCanvas, generic event handlers (DisplayEHs) piggyback on the RefreshEHList. WorldCanvas is also a DisplayEH, and all DisplayEHs implement handling of these new events by overriding the (null) base class version of this method.

void operator()(const PCRefreshEvent &pev)
void operator()(const PCMotionEvent &pev)
void operator()(const PCPositionEvent &pev)

Handle implicit refresh, motion and position events occuring on the PixelCanvas on which this WorldCanvas is installed. These functions translate PixelCanvas events into WorldCanvas events.

void refresh(const Display::RefreshReason &reason = Display::UserCommand, const Bool &explicitrequest = True)

Refresh the WorldCanvas for the given reason. The refresh is prevented from occuring if the PixelCanvas is not yet mapped to the screen, or if the refreshes have been held with earlier call/s to hold() which has/have not been matched with the same number of calls to release().

Bool refreshAllowed()

Is a refresh currently allowed?

void hold()
void release()

Hold and release response to refreshes requested with the refresh() member function. Multiple calls to hold() can be made, and refreshes will not resume until the same number of calls have been made to release(). Note that these functions do not affect whether internally (implicitly) generated refreshes continue to occur. That is, refresh events due to PixelCanvas resize events, or Colormap changes, for example, will continue to be acted upon.

void setCoordinateHandler(WCCoordinateHandler *ch)
void setSizeControlHandler(WCSizeControlHandler *sh)
void setResampleHandler(WCResampleHandler *rh)
void setDataScaleHandler(WCDataScaleHandler *sh)

Set Coordinate, SizeControl, Resample and DataScale handlers for the WorldCanvas. If the given handler is 0, then resort to using the default handler.

void setWorldCanvasPosition(Double fracXOffset, Double fracYOffset, Double fracXSize, Double fracYSize)

Set the location of the WorldCanvas on its PixelCanvas.

Bool pixToLin(Vector<Double> &lin, const Vector<Double> &pix)
Bool pixToLin(Matrix<Double> &lin, Vector<Bool> &failures, const Matrix<Double> &pix)
Bool linToPix(Vector<Double> &pix, const Vector<Double> &lin)
Bool linToPix(Matrix<Double> &pix, Vector<Bool> &failures, const Matrix<Double> &lin)
Bool linToWorld(Vector<Double> &world, const Vector<Double> &lin)
Bool linToWorld(Matrix<Double> &world, Vector<Bool> &failures, const Matrix<Double> &lin)
Bool worldToLin(Vector<Double> &lin, const Vector<Double> &world)
Bool worldToLin(Matrix<Double> &lin, Vector<Bool> &failures, const Matrix<Double> &world)
Bool pixToWorld(Vector<Double> &world, const Vector<Double> &pix)
Bool pixToWorld(Matrix<Double> &world, Vector<Bool> &failures, const Matrix<Double> &pix)
Bool worldToPix(Vector<Double> &pix, const Vector<Double> &world)
Bool worldToPix(Matrix<Double> &pix, Vector<Bool> &failures, const Matrix<Double> &world)

Pixel, linear and world coordinate transformation functions. For the Vector versions, the coordinate mapping returns False if the transformation failed. For the Matrix versions, failures(i) on input should be set to True if the i'th transformation should not be attempted. On output, failures(i) is True if the transformation was not attempted, or failed. If on input the failures vector has zero length, it will be assumed that no prior failures have occurred.

void registerColormap(Colormap *cmap, Float weight = 1.0)
void registerColormap(Colormap *cmap, Colormap *cmapToReplace)
void unregisterColormap(Colormap *cmap)

Register/unregister a Colormap on the PixelCanvas. Registration counts are remembered, so that a particular Colormap is guaranteed to be available as long as that Colormap has been registered more times than it has been unregistered. Requests are forwarded to the PixelCanvas.

void setColormap(Colormap *cmap)
Colormap *colormap() const

Set and retrieve the current Colormap on the PixelCanvas. This function must be called prior to using a WorldCanvas (or PixelCanvas) drawing routines which is expected to use a Colormap. Passing an unregistered Colormap to setColormap will result in an exception being thrown. Requests are forwarded to the PixelCanvas.

uInt newList()
void endList()
void drawList(uInt list)
void deleteList(uInt list)
void deleteLists()
Bool validList(uInt list)

Display list support functions. A display list is started with a call to newList(), finished with a call to endList(), and drawn with a call to drawList(x), with the argument x being the list number returned by the original call to newList(). Lists can be deleted individually with deleteList(x) or in total with deleteLists(). Requests are forwarded to the PixelCanvas.

void setColor(const String &color)
void setClearColor(const String &color)
Bool setFont(const String &fontName)
void setForeground(uLong color)
void setBackground(uLong color)
void setLineWidth(Float width)
void setLineStyle(Display::LineStyle style)
void setCapStyle(Display::CapStyle style)
void setJoinStyle(Display::JoinStyle style)
void setFillStyle(Display::FillStyle style)
void setFillRule(Display::FillRule rule)
void setArcMode(Display::ArcMode mode)

Set various graphics attributes. All of these requests are passed directly to the PixelCanvas, except for setColor, which also installs the requested color for subsequent calls to PgPlot functions.

Bool setWorldBackgroundColor(const String color)
Bool setWorldForegroundColor(const String color)
String getWorldBackgroundColor()
String getWorldForegroundColor()

Set/retrieve the background and foreground colors of the WorldCanvas. These can be different to those for the PixelCanvas. Indeed, they will be used as default colors on the WorldCanvas when necessary.

virtual void setDrawBuffer(Display::DrawBuffer buf)
Display::DrawBuffer drawBuffer() const

Set/retrieve the drawing buffer, the target destination for graphics. Requests are passed directly to the PixelCanvas.

void setImageCacheStrategy(Display::ImageCacheStrategy strategy)
Display::ImageCacheStrategy imageCacheStrategy() const

Set/retrieve the caching strategy on the PixelCanvas. Appropriate values are Display::ClientAlways (use client memory to cache images [safer]), Display::ServerAlways (use server memory to cache images [faster]), and Display::ServerMemoryThreshold (use server memory until a threshold is reached [not yet implemented]). Requests are passed to the PixelCanvas.

void clear()
void clearNonDrawArea()

Clear the WorldCanvas, or just the area on the WorldCanvas but outside the drawing area, ie. the margins that are normally reserved for axis labels and the like.

virtual void setDefaultOptions()

Install the default options for this DisplayData

virtual Bool setOptions(const Record &rec, Record &updatedOptions)

Apply options stored in rec to the DisplayData; return value True means a refresh is needed. Any fields added to the updatedOptions argument are options which have changed in some way due to the setting of other options - ie. they are context sensitive.

virtual Record getOptions() const

Retrieve the current and default options and parameter types.

void setAttribute(Attribute& at)
void setAttributes(AttributeBuffer& at)

Set an Attribute or Attributes on the WorldCanvas.

void removeAttribute(String& name)

Remove an Attribute. Pre-defined Attributes of the WorldCanvas cannot be removed (although nothing serious will happen if you try).

Bool getAttributeValue(const String& name, uInt& newValue) const
Bool getAttributeValue(const String& name, Int& newValue) const
Bool getAttributeValue(const String& name, Float& newValue) const
Bool getAttributeValue(const String& name, Double& newValue) const
Bool getAttributeValue(const String& name, Bool& newValue) const
Bool getAttributeValue(const String& name, String& newValue) const
Bool getAttributeValue(const String& name, Vector<uInt>& newValue) const
Bool getAttributeValue(const String& name, Vector<Int>& newValue) const
Bool getAttributeValue(const String& name, Vector<Float>& newValue) const
Bool getAttributeValue(const String& name, Vector<Double>& newValue) const
Bool getAttributeValue(const String& name, Vector<Bool>& newValue) const
Bool getAttributeValue(const String& name, Vector<String>& newValue) const

User interface to get individual values from the attribute buffer.

Bool existsAttribute(String& name) const

Check if a certain Attribute exists.

AttValue::ValueType attributeType(String& name) const

Get the type of an Attribute.

virtual void acquirePGPLOTdevice(const Bool &linear = True)
virtual void releasePGPLOTdevice()

Position the PGPLOT filter on the WorldCanvas. If linear is specified False, then the alignment is done by world coordinates, assuming that a linear approximation is valid. void verifyPGFilterAlignment(const Bool &linear = True);

Acquire and release a PGPLOT device for this WorldCanvas. This is necessary since PGPLOT generally only supports 8 currently active devices. So refresh cycles on the WorldCanvas acquire a PGPLOT device at the start, and release it at the end. Cycles are counted so that external user-classes can call these functions if necessary in a nested state. If linear is specified as False, then the PGPLOT device is aligned by world coordinates, under the assumption that a linear approximation is valid, that is, the curvature is small.

virtual Int pgid() const

Return the PGPLOT device id for external use.

Bool drawText(const Vector<Double> &point, const String &text, Display::TextAlign alignment = Display::AlignCenter, const Bool &linear = False)

Draw unrotated text at the given position. If the conversion from world to pixel coordinates fails, the text is not drawn, and False is returned. If linear is True, then the provided position is actually in linear world canvas coordinates, rather than true world coordinates.

Bool drawPoint(const Vector<Double> &point, const Bool &linear = False)

Draw a single point using the current color. If the conversion from world to pixel coordinates fails, the point is not drawn, and False is the return value. If linear is True, then the point position is given in linear world canvas coordinates, not true world coordinates.

Bool drawLine(const Vector<Double> &a, const Vector<Double> &b, const Bool &linear = False)

Draw a single line using the current color. If either of the conversions from world to pixel coordinates fail, then the line is not drawn, and False is returned. If linear is True, then the line endpoints are given in world canvas linear coordinates rather than real world coordinates.

Bool drawPoints(const Matrix<Double> &points, const Bool &linear = False)

Draw a bunch of points using the current color. If any points fail to convert then none of them are drawn, and False is returned. If linear is True, then the vertices are given in linear world canvas coordinates rather than real world coordinates.

Bool drawPoints(const Vector<Float> &px, const Vector<Float> &py, Bool linear = False)

Draw a set of points using the current color. Those points which fail to convert, or lie outside the WorldCanvas drawing area, are not drawn.

Bool drawTextStrings(const Vector<Float> &px, const Vector<Float> &py, const Vector<String> &strings, const Float rotation = 0.0, const Float xoffset = 0.0, const Float yoffset = 0.0, const Bool linear = False)

Draw a set of text strings using the current color. If any points fail to convert, then those particular strings are not drawn. rotation gives the rotation of the text in degrees counter-clockwise from horizontal. xoffset and yoffset can be given to globally shift the labels by the specified amounts (in units of the character height). If linear is True, then the vertices are given in linear world canvas coordinates rather than true world coordinates.

Bool drawMarkers(const Vector<Float> &px, const Vector<Float> &py, const Display::Marker = Display::Cross, const Int size = 5, const Bool& linear = False)

Draw a set of markers using the current color and a given pixel size. If any points fail to convert, then those particular points are not marked. markertype is an Display::Marker. If linear is True, then the points are given in linear world canvas coordinates rather than true world coordinates.

Bool drawMappedMarkers(const Vector<Float> &px, const Vector<Float> &py, const Vector<Float>& values, const Int sizemin = 1, const Int sizemax = 20, const Display::Marker = Display::Cross, const Bool& linear = False)

Bool drawLines(const Matrix<Double> &vertices, const Bool &linear = False)

Draw pairs of lines using the current color. If any points fail to convert then the lines are not drawn and False is returned. If linear is True, then the vertices are given as linear world coordinates rather than true world coordinates.

Bool drawPolyline(const Matrix<Double> &vertices, const Bool &linear = False)

Draw a polyline (connected line) between the vertices using the current color. If any coordinates fail to convert from world to pixel, then the entire polyline is not drawn and False is returned. The end point is not implicitly connected to the starting point. If linear is True, then the provided vertices are actually linear world canvas coordinates.

Bool drawPolygon(const Matrix<Double> &vertices, const Bool &linear = False)

Draw a polygon (closed line, or line loop using the points) using the current color. If any coordinates fail to convert then the polygon is not drawn. The end point is implicitly connected to the start point. If linear is True, then the provided vertices are actually linear world coordinates.

Bool drawColormappedPoints(const Matrix<Double> &points, const Vector<Float> &values, const Bool &linear = False)

Draw a set of points in colors which are taken from the current Colormap.

Bool drawColormappedEllipses(const Matrix<Double> &centres, const Vector<Float> &smajor, const Vector<Float> &sminor, const Vector<Float> &pangle, const Vector<Float> &colors, const Float &scale = 1.0, const Bool &outline = True, const Bool &linear = False)

Draw a set of colored ellipses, possibly with outlines. The x and y locations must given, along with semi-major and semi-minor axes, and position angle measured in degrees positive from the x axis in a counter-clockwise direction. The size of the ellipses is globally scaled by the scale factor, and if outline is True, then each ellipse will have an outline in the current pen color.

void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Vector<Float> &levels, const Bool usePixelEdges = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Vector<Float> &levels, const Bool usePixelEdges = False)

Draw a contour map at the specified levels, and place the lower left pixel at blPos, and the upper right pixel at trPos. If usePixelEdges is True, then the given world positions are the position of the blc and trc of the blc and trc pixels, otherwise they are the positions of the centres of the pixels. Note that the contours are not intrinsically drawn in world coordinates. For complex data, the conversion to real values is done according to the last call to setComplexToRealMethod.

void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Matrix<Bool> &mask, const Vector<Float> &levels, const Bool usePixelEdges = False)
void drawContourMap(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Matrix<Bool> &mask, const Vector<Float> &levels, const Bool usePixelEdges = False)

Draw a contour map at the specified levels, and place the lower left pixel at blPos, and the upper right pixel at trPos. If usePixelEdges is True, then the given world positions are the position of the blc and trc of the blc and trc pixels, otherwise they are the positions of the centres of the pixels. Note that the contours are not intrinsically drawn in world coordinates. For complex data, the conversion to real values is done according to the last call to setComplexToRealMethod. These functions also have a mask argument, which is a Boolean pixel mask whose shape must match that of data, and only pixels in data where corresponding pixels in mask are True will be contoured.

Bool redrawIndexedImage(void* drawObj, Display::RefreshReason reason)

Optimization to speed up colormap fiddling in 24bit mode (software Colormap); see images_, below for usage.

Bool removeIndexedImage(void* drawObj)

Remove image from the colormap change cache, if any (see images_, below). Return value indicates whether there was anything to remove.

void clearColormapChangeCache()

Clear the whole colormap change cache (see images_, below).

void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Bool usePixelEdges = False, void* drawObj=0)

Draw an image, mapping data values to Colormap entries, and place the lower left pixel at blPos, and the upper right pixel at trPos. If usePixelEdges is True, then the given world positions are the position of the blc and trc of the blc and trc pixels, otherwise they are the positions of the centres of the pixels. See images_, below, for non-default usage of the drawObj parameter.

void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Matrix<Bool> &mask, const Bool usePixelEdges = False, void* drawObj=0)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Matrix<Bool> &mask, const Bool usePixelEdges = False, void* drawObj=0)

Draw an image, mapping data values to Colormap entries, and place the lower left pixel at blPos, and the upper right pixel at trPos. If usePixelEdges is True, then the given world positions are the position of the blc and trc of the blc and trc pixels, otherwise they are the positions of the centres of the pixels. These functions also have a mask argument, which is a Boolean pixel mask whose shape must match that of data, and only pixels in data where corresponding pixels in mask are True will be drawn. See images_, below, for non-default usage of the drawObj parameter.

void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Float> &data, const Display::ColorComponent &colorcomponent, const Bool usePixelEdges = False)
void drawImage(const Vector<Double> &blPos, const Vector<Double> &trPos, const Matrix<Complex> &data, const Display::ColorComponent &colorcomponent, const Bool usePixelEdges = False)

Draw a component of a multi-channel image, mapping data values to component levels, and place the lower left pixel at blPos, and the upper right pixel at trPos. If usePixelEdges is True, then the given world positions are the position of the blc and trc of the blc and trc pixels, otherwise they are the positions of the centres of the pixels. The components are not drawn until flushComponentImages() is called.

void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Complex>& data, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)
void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& data, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)

Draw a vector map.

void drawMarkerMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& data, const Matrix<Bool>& mask, Int xPixelInc, Int yPixelInc, Float scale, Double xWorldInc, Double yWorldInc, const String& markeType, Bool usePixelEdges)
void drawMarkerMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Complex>& data, const Matrix<Bool>& mask, Int xPixelInc, Int yPixelInc, Float scale, Double xWorldInc, Double yWorldInc, const String& markerType, Bool usePixelEdges)

Draw marker maps. Only makerType "square" available presently. The marker holds its shape in screen pixel coordinates. This means a square is always a square regardless of aspect ratio

void flushComponentImages()

Flush the component images, ie. compose a single image from the buffered channel images and place it on the WorldCanvas. This effectively is passed on to the PixelCanvas where the component images are cached.

void copyBackBufferToFrontBuffer()
void copyFrontBufferToBackBuffer()
void swapBuffers()

Buffer memory exchanges which operate only on the area of the WorldCanvas. (Not cacheable yet.)

Double linXMin() const
Double linYMin() const
Double linXMax() const
Double linYMax() const

Provide information on the extents of the linear coordinate system.

Double linXMinLimit() const
Double linYMinLimit() const
Double linXMaxLimit() const
Double linYMaxLimit() const

Provide information on the limits of the linear coordinate system.

uInt canvasXOffset() const
uInt canvasYOffset() const
uInt canvasXSize() const
uInt canvasYSize() const

Provide information on the WorldCanvas offset and size.

uInt canvasDrawXOffset() const
uInt canvasDrawYOffset() const
uInt canvasDrawXSize() const
uInt canvasDrawYSize() const

Provide information on the WorldCanvas drawable offset and size.

void setZoomRectangleLCS(const Vector<Double> &min, const Vector<Double> &max)

Set the zoom rectangle to the specfied linear coordinate range.

void moveZoomRectangleLCS(double dx, double dy)

Move the zoom rectangle across the screen, ie. pan.

void resetZoomRectangle()

Reset the zoom to show the entire allowable range of the linear coordinate system.

void setLinearCoordinateSystem(const Vector<Double> &blc, const Vector<Double> &trc, Bool resetZoom = True)

Set the allowable range of the linear coordinate system.

Double dataMin() const
void setDataMin(Double min)
Double dataMax() const
void setDataMax(Double max)
void setDataMinMax(Double min, Double max)

Functions to set and retrieve the minimum and maximum data values for scaling data that is drawn on the WorldCanvas. These values are forwarded to the scale handler, when, for example, images are drawn.

Display::ComplexToRealMethod complexToRealMethod() const
void setComplexToRealMethod(const Display::ComplexToRealMethod method)

ComplexToRealMethod defines which real component of a Complex image to extract when it is necessary to convert Complex data into real data.

void setCoordinateSystem(const CoordinateSystem &csys)
const CoordinateSystem &coordinateSystem() const

Set and retrieve the CoordinateSystem of this WorldCanvas. Set with 0 and the WorldCanvas loses its CoordinateSystem!

Bool inDrawArea(Int x, Int y)
Bool inWC(Int x, Int y)
Bool inPC(Int x, Int y)

Convenience functions returning whether a pixel coordinate is within bounds of the WC's inner draw area, the WC, or the underlying PC.

void ctorInit()

Support for construction.

void callRefreshEventHandlers(const WCRefreshEvent &ev)

Call all registered refresh handlers (public method is refresh()).

void updateCanvasSizesOffsets()
void updateFracSizesOffsets()

Update canvas sizes/offsets from the fracOffsets, and vice versa.

Bool castingConversion(Vector<Int> &pixelpt, const Vector<Double> &worldpt, const Bool &linear)
Bool castingConversion(Matrix<Int> &pixelpts, const Matrix<Double> &worldpts, const Bool &linear)
Bool castingConversion(Matrix<Float> &pixelpts, const Matrix<Double> &worldpts, const Bool &linear)

Convert the given coordinate/s to pixel coordinates. If linear is True, then the given coordinates are in linear world coordinates, otherwise they are real world coordinates. A return value of False indicates the conversion failed.

Bool castingClippingConversion(Vector<Int> &pixelx, Vector<Int> &pixely, Vector<Bool> &validConversions, const Vector<Float> &worldx, const Vector<Float> &worldy, const Bool linear)

Convert the given coordinate/s to pixel coordinates. If linear is True, then the input coordinates are linear world coordinates, otherwise they are true world coordinates. This version applies clipping, so that any points in the series which lie outside the linear coordinate range of the WorldCanvas are discarded. Thus the output Vectors can be shorter than the input Vectors. A mask indicating which of the input points were valid is returned for user reference.

void drawVectorMap(const Vector<Double>& blc, const Vector<Double>& trc, const Matrix<Float>& amp, const Matrix<Float>& pa, const Matrix<Bool>& mask, Float angleConversionFactor, Float phasePolarity, Bool debias, Float variance, Int xPixelInc, Int yPixelInc, Float scale, Bool arrow, Float barb, Float rotation, Double xWorldInc, Double yWorldInc, const Bool usePixelEdges)

Actually draw the vector field. All pa * angleConversionFactor must be radians. rotation must be radians. if amp is of dimension 0, amplitude unity is assumed. if mask if dimension 0 all data are assumed good.

void trimAndResampleImage(Vector<Double> &drawBlc, Vector<Double> &drawTrc, Matrix<Float> &sampledImage, const Vector<Double> &blc, const Vector<Double> &trc, const Matrix<Float> &data, const Bool &usePixelEdges = False)

Trim and resample an image, returning the actual world BLC and TRC for drawing, and the resampled image.

void trimAndResampleImage(Vector<Double> &drawBlc, Vector<Double> &drawTrc, Matrix<Float> &sampledImage, Matrix<Bool> &resampledMask, const Vector<Double> &blc, const Vector<Double> &trc, const Matrix<Float> &data, const Matrix<Bool> &mask, const Bool &usePixelEdges = False)

Trim and resample an image, returning the actual world BLC and TRC for drawing, and the resampled image. This function takes a mask indicating which pixels should be drawn. This function therefore also trims and resamples the mask.

void mapToColorAndDrawImage(const Vector<Int> &blc, const Matrix<uInt> &scaledImage)
void mapToColorAndDrawImage(const Vector<Int> &blc, const Matrix<uInt> &scaledImage, const Matrix<Bool> &mask)

Draw an image where scaledImage gives the Colormap index of each screen (PixelCanvas) pixel. 'blc' contains X and Y PixelCanvas coordinates. Masked version as well.

Bool mapToColorAndDrawPoints(const Matrix<Double> &points, const Vector<uInt> &scaledValues, const Bool &linear = False)

Draw a set of points where scaledValues gives the Colormap index of each point. Point coordinates ('points') are either linear or world coordinates, as specified by 'linear'.

Bool mapToColorAndDrawEllipses(const Matrix<Double> &centres, const Vector<Float> &smajor, const Vector<Float> &sminor, const Vector<Float> &pangle, const Vector<uInt> scaledValues, const Float &scale, const Bool &outline, const Bool &linear)

Draw a set of ellipses where scaledValues gives the Colormap index of each point. Point coordinates ('points') are either linear or world coordinates, as specified by 'linear'.

ColorIndexedImage_* getClearedColorIndexedImage(void* drawObj=0)

Retrieve an indexed image to write onto. Used (exclusively) by WC::drawImage(). If one exists in the cache under this objId key, clear it for reuse; otherwise return a new one. If a (non-zero) objId was provided, it will be cached under that key; removeIndexedImage() can be used to remove such cached images explicitly, but the cache is also frequently cleared automatically. If no caching is requested, however, (objId=0), the caller must delete the image himself when finished -- that type of call is equivalent to 'new ColorIndexedImage_'.