CVB++ 14.0
ImageView Class Reference

View to display an image. More...

#include <cvb/ui/image_view.hpp>

Inherits QGraphicsView.

Public Member Functions

 ImageView (QWidget *parent=nullptr)
 Create an image view. More...
 
 ImageView (class ImageScene *scene, QWidget *parent=nullptr)
 
void Refresh (Cvb::UI::RefreshMode refreshMode)
 Refresh the view using a specified mode. More...
 
void Refresh ()
 Refresh the view. More...
 
void Refresh (const ImagePtr &image, Cvb::UI::RefreshMode refreshMode, AutoRefresh autoRefresh=AutoRefresh::Off)
 Share the image and refresh the view. More...
 
void Refresh (const ImagePtr &image, AutoRefresh autoRefresh=AutoRefresh::Off)
 Share the image and refresh the view. More...
 
void Refresh (const class Image &image, Cvb::UI::RefreshMode refreshMode)
 Refresh the view using the specified image and mode. More...
 
void Refresh (const class Image &image)
 Refresh the view using the specified image. More...
 
void ReleaseRefreshShare () noexcept
 Releases the shared image. More...
 
void SetEventRefreshEnabled (bool enabled) noexcept
 Enables and disables automatic refreshing caused by events. More...
 
bool IsEventRefreshEnabled () const noexcept
 Check if automatic refreshing by events is set. More...
 
void SetWaitForRepaintEnabled (bool enabled)
 Enable and disables waiting for repaints. More...
 
bool IsWaitForRepaintEnabled () const noexcept
 Checks if waiting for repaint is set. More...
 
void CustomWaitForRepaint (std::function< void()> customWaitForRepaint) noexcept
 Set a custom callback associated with a refresh mode. More...
 
void ResetCustomWaitForRepaint () noexcept
 Reset to the default value. More...
 
void CustomScheduleRepaint (std::function< void()> scheduleRepaint) noexcept
 Set a custom callback associated with a refresh mode. More...
 
void ResetCustomScheduleRepaint () noexcept
 Reset to the default value. More...
 
Cvb::UI::RefreshMode RefreshMode () const noexcept
 Get the current refresh mode. More...
 
void SetRefreshMode (Cvb::UI::RefreshMode refreshMode) noexcept
 Set the current refresh mode. More...
 
Cvb::UI::UploadMode UploadMode () const noexcept
 Get the current upload mode. More...
 
void SetUploadMode (Cvb::UI::UploadMode uploadMode)
 Set the current upload mode. More...
 
ImagePtr Image () const noexcept
 Get the currently shared image. More...
 
class ImageSceneImageScene () const noexcept
 Get the image scene. More...
 
bool TryZoomIn () noexcept
 Tries to zoom in. More...
 
bool TryZoomOut () noexcept
 Tries to zoom out. More...
 
ZoomDescriptor Zoom () const noexcept
 Get the current zoom descriptor. More...
 
void SetZoom (ZoomDescriptor zoomDescriptor) noexcept
 Set the current zoom descriptor. More...
 
Cvb::UI::RenderEngine RenderEngine () const noexcept
 Get the current render engine. More...
 
void SetRenderEngine (Cvb::UI::RenderEngine renderEngine)
 Set the current render engine. More...
 
Cvb::EventCookie RegisterEventMouseMoved (std::function< void(Cvb::Point2D< int >, const std::vector< double > &)> handler)
 Register a callback to get pixel values under the moving mouse. More...
 
void UnregisterEventMouseMoved (Cvb::EventCookie eventCookie) noexcept
 Unregister a callback to get pixel values under the moving mouse. More...
 

Protected Member Functions

void closeEvent (QCloseEvent *event) override
 Handles close events. More...
 
void scrollContentsBy (int dx, int dy) override
 Handles scrolling the view. More...
 
void resizeEvent (QResizeEvent *event) override
 Handle resize events. More...
 
void showEvent (QShowEvent *event) override
 Handle show events. More...
 
void wheelEvent (QWheelEvent *event) override
 Handle mouse wheel events to zoom. More...
 
void mouseMoveEvent (QMouseEvent *event) override
 Handle mouse move events. More...
 

Detailed Description

View to display an image.

This is the main class to display an image in a widget based Qt application. It supports all the features provided by QtGraphicsView, with the exception, that it is not possible to have multiple views on the same scene.

Example:
view.setWindowIcon(QIcon(":/qttutorial.png"));
Cvb::String path(CVB_LIT("%CVB%/Tutorial/ClaraRGB.bmp"));
// expand environment variables in path
path = Cvb::ExpandPath(path);
// load the image
// refresh the image view
view.Refresh(image);
view.show();
static std::unique_ptr< Image > Load(const String &fileName)
Loads an image with the given file name.
Definition: detail_image.hpp:32
View to display an image.
Definition: decl_image_view.hpp:75
void SetUploadMode(Cvb::UI::UploadMode uploadMode)
Set the current upload mode.
Definition: decl_image_view.hpp:354
void Refresh(Cvb::UI::RefreshMode refreshMode)
Refresh the view using a specified mode.
Definition: detail_image_view.hpp:68
void SetRenderEngine(Cvb::UI::RenderEngine renderEngine)
Set the current render engine.
Definition: detail_image_view.hpp:238
void show()
void setWindowIcon(const QIcon &icon)
Examples
Cvb/QtDisplayAdvanced, Cvb/QtImageDisplay, Cvb/QtStatisticsDisplay, Cvb/QtStreamDisplay, Cvb/QtStreamDisplayPair, Movie2/QtMovie2, and ShapeFinder2/QtShapeFinder2.

Constructor & Destructor Documentation

◆ ImageView() [1/2]

ImageView ( QWidget parent = nullptr)
inline

Create an image view.

Parameters
[in]parentParent object in Qt's object hierarchie.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ ImageView() [2/2]

ImageView ( class ImageScene scene,
QWidget parent = nullptr 
)
inline
Parameters
[in]sceneScene to use with this view.
[in]parentParent object in Qt's object hierarchie.
Exceptions
Anyexception derived from std::exception including CvbException.

Use this constructor only if you must associate the view with you own subclass of a ImageScene.

Member Function Documentation

◆ closeEvent()

void closeEvent ( QCloseEvent event)
inlineoverrideprotectedvirtual

Handles close events.

Parameters
[in]eventThe Qt event.
Exceptions
Doesnot throw any exception.

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QWidget.

◆ CustomScheduleRepaint()

void CustomScheduleRepaint ( std::function< void()>  scheduleRepaint)
inlinenoexcept

Set a custom callback associated with a refresh mode.

Parameters
[in]scheduleRepaintCustom callback.
Exceptions
Doesnot throw any exception.

This is useful for manual optimization and synchronization if multiple image views are used.

◆ CustomWaitForRepaint()

void CustomWaitForRepaint ( std::function< void()>  customWaitForRepaint)
inlinenoexcept

Set a custom callback associated with a refresh mode.

Parameters
[in]customWaitForRepaintCustom callback.
Exceptions
Doesnot throw any exception.

This is useful for manual optimization and synchronization if multiple image views are used.

◆ Image()

ImagePtr Image ( ) const
inlinenoexcept

Get the currently shared image.

Returns
ImagePtr The currently shared image.
Exceptions
Doesnot throw any exception.

◆ ImageScene()

ImageScene * ImageScene ( ) const
inlinenoexcept

Get the image scene.

Returns
The image scene associated with this image view.
Exceptions
Doesnot throw any exception.

This is useful for accessing Qt features, that are not exposed through this image view.

◆ IsEventRefreshEnabled()

bool IsEventRefreshEnabled ( ) const
inlinenoexcept

Check if automatic refreshing by events is set.

Returns
True if enabled, false otherwise.
Exceptions
Doesnot throw any exception.

◆ IsWaitForRepaintEnabled()

bool IsWaitForRepaintEnabled ( ) const
inlinenoexcept

Checks if waiting for repaint is set.

Returns
True if enabled, false otherwise.
Exceptions
Doesnot throw any exception.

◆ mouseMoveEvent()

void mouseMoveEvent ( QMouseEvent event)
inlineoverrideprotectedvirtual

Handle mouse move events.

Parameters
[in]eventThe Qt event.
Exceptions
Doesnot throw any exception.

The default implementation will run all registered callbacks if there are any.

See also
ImageView::RegisterEventMouseMoved(std::function<void(Point, const std::vector<double> &)> handler)

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QGraphicsView.

◆ Refresh() [1/6]

void Refresh ( )
inline

Refresh the view.

Exceptions
Anyexception derived from std::exception including CvbException.

This is equivalent to calling ImageView::Refresh(enum class RefreshMode) with the defualt mode.

◆ Refresh() [2/6]

void Refresh ( const class Image image)
inline

Refresh the view using the specified image.

Parameters
[in]imageThe image, which is not shared with the display.
Exceptions
Anyexception derived from std::exception including CvbException.

This is equivalent to calling ImageView::Refresh(const class Image &, enum class RefreshMode) with the default mode.

◆ Refresh() [3/6]

void Refresh ( const class Image image,
Cvb::UI::RefreshMode  refreshMode 
)
inline

Refresh the view using the specified image and mode.

Parameters
[in]imageThe image, which is not shared with the display.
[in]refreshModeThe refresh mode
Exceptions
Anyexception derived from std::exception including CvbException.

Refreshing will trigger an image upload and rendering the pixel content in the view. Depending on the selected RenderRngine, upload and rendering may happen in different threads as QGraphicsView does not allow multi threaded access to OpenGL.

Asynchronous Upload
RenderEngineUpload ThreadRender Thread
RenderEngine::Raster Calling Thread Main Thread
RenderEngine::OpenGL2 Main Thread Main Thread
RenderEngine::OpenGL3 Main Thread Main Thread

All Refresh() versions are thread safe with limitations and may be called from either the main thread or the acquisition thread. Depending on the mode this method may block until the main thread has actually rendered the image. This introduces an unavoidable risk for a deadlock. If e.g. the main thread is waiting for the a acquisition thread to finish while acquisition thread is waiting for the main thread to render. In order to prevent that must manually abort the waiting.

All Refresh() versions that take a reference instaed of a pointer will not share the image. So before using a refernce version make sure, that there is no shared image in the display ReleaseRefreshShare(). As a consequence of not sharing the image only Cvb::UI::UploadMode::Image is supported. Furthermore anything registered with RegisterEventMouseMoved will not be called.

See also
ImageView::IsEventRefreshEnabled()
ImageView::SetWaitForRepaintEnabled(bool)

◆ Refresh() [4/6]

void Refresh ( const ImagePtr image,
AutoRefresh  autoRefresh = AutoRefresh::Off 
)
inline

Share the image and refresh the view.

Parameters
[in]imageThe image, which will be shared with the display.
[in]autoRefreshSwitch to control automatic refreshing.
Exceptions
Anyexception derived from std::exception including CvbException.

This is equivalent to calling ImageView::Refresh(const ImagePtr &, enum class RefreshMode, AutoRefresh autoRefresh) with the default mode.

◆ Refresh() [5/6]

void Refresh ( const ImagePtr image,
Cvb::UI::RefreshMode  refreshMode,
AutoRefresh  autoRefresh = AutoRefresh::Off 
)
inline

Share the image and refresh the view.

Parameters
[in]imageThe image, which will be shared with the display.
[in]refreshModeThe refresh mode
[in]autoRefreshSwitch to control automatic refreshing.
Exceptions
Anyexception derived from std::exception including CvbException.

Any previously shared image will be released. Once an image has been shared you may call ImageView::Refresh() or ImageView::Refresh(enum class RefreshMode).

◆ Refresh() [6/6]

void Refresh ( Cvb::UI::RefreshMode  refreshMode)
inline

Refresh the view using a specified mode.

Parameters
[in]refreshModeThe refresh mode.
Exceptions
Anyexception derived from std::exception including CvbException.

This method will refresh the view with the content of the shared image. This is equivalent to calling ImageView::Refresh(const class Image & image, enum class RefreshMode refreshMode) with the currently shared image. If there is no shared image this method will throw.

Examples
Cvb/QtImageDisplay, and Cvb/QtStreamDisplay.

◆ RefreshMode()

Cvb::UI::RefreshMode RefreshMode ( ) const
inlinenoexcept

Get the current refresh mode.

Returns
The current refresh mode.
Exceptions
Doesnot throw any exception.

◆ RegisterEventMouseMoved()

EventCookie RegisterEventMouseMoved ( std::function< void(Cvb::Point2D< int >, const std::vector< double > &)>  handler)
inline

Register a callback to get pixel values under the moving mouse.

Parameters
[in]handlerThe callback.
Returns
Cookie to unregister the callback if not needed anymore.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/QtImageDisplay.

◆ ReleaseRefreshShare()

void ReleaseRefreshShare ( )
inlinenoexcept

Releases the shared image.

Exceptions
Doesnot throw any exception.

Use this method if you must release the shared image manually. Setting a new shared image and destroying this image view will automatically release the shared image.

◆ RenderEngine()

Cvb::UI::RenderEngine RenderEngine ( ) const
inlinenoexcept

Get the current render engine.

Returns
The render engine.
Exceptions
Doesnot throw any exception.

◆ ResetCustomScheduleRepaint()

void ResetCustomScheduleRepaint ( )
inlinenoexcept

Reset to the default value.

Exceptions
Doesnot throw any exception.

◆ ResetCustomWaitForRepaint()

void ResetCustomWaitForRepaint ( )
inlinenoexcept

Reset to the default value.

Exceptions
Doesnot throw any exception.

◆ resizeEvent()

void resizeEvent ( QResizeEvent event)
inlineoverrideprotectedvirtual

Handle resize events.

Parameters
[in]eventThe Qt event.
Exceptions
Doesnot throw any exception.

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QGraphicsView.

◆ scrollContentsBy()

void scrollContentsBy ( int  dx,
int  dy 
)
inlineoverrideprotectedvirtual

Handles scrolling the view.

Parameters
[in]dxDistance covered in x.
[in]dyDistance covered in Y.
Exceptions
Doesnot throw any exception.

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QGraphicsView.

◆ SetEventRefreshEnabled()

void SetEventRefreshEnabled ( bool  enabled)
inlinenoexcept

Enables and disables automatic refreshing caused by events.

Parameters
[in]enabledTrue to enable, false to disable.
Exceptions
Doesnot throw any exception.

In this case events refer to UI events sent to QWidget based classes. E.g these are caused by resizing or scrolling the image view. Obviously these events should trigger a repaint to provide a smooth user experience. Unfortunately such events can trigger each other, potentially causing several unneeded refreshes that in turn may impact performance. This method is used to prevent such behavior during event handling.

See also
ImageView::closeEvent(QCloseEvent * event) override;
ImageView::scrollContentsBy(int dx, int dy) override;
ImageView::resizeEvent(QResizeEvent * event) override;
ImageView::showEvent(QShowEvent *event) override;
ImageView::wheelEvent(QWheelEvent * event) override;
ImageView::mouseMoveEvent(QMouseEvent * event) override;

◆ SetRefreshMode()

void SetRefreshMode ( Cvb::UI::RefreshMode  refreshMode)
inlinenoexcept

Set the current refresh mode.

Parameters
[in]refreshModeThe new refresh mode.
Exceptions
Doesnot throw any exception.

◆ SetRenderEngine()

void SetRenderEngine ( Cvb::UI::RenderEngine  renderEngine)
inline

Set the current render engine.

Parameters
[in]renderEngineThe new Render engine.
Exceptions
Anyexception derived from std::exception including CvbException.

If the new render engine is cannot be set, the call is ignored.

Examples
Cvb/QtImageDisplay, and Cvb/QtStreamDisplay.

◆ SetUploadMode()

void SetUploadMode ( Cvb::UI::UploadMode  uploadMode)
inline

Set the current upload mode.

Parameters
[in]uploadModeThe new upload mode.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/QtImageDisplay, Cvb/QtStreamDisplay, and Movie2/QtMovie2.

◆ SetWaitForRepaintEnabled()

void SetWaitForRepaintEnabled ( bool  enabled)
inline

Enable and disables waiting for repaints.

Parameters
[in]enabledTrue to enable, false to disable.
Exceptions
Anyexception derived from std::exception including CvbException.

This is used to prevent a deadlock condition that can happen between the main thread and the acquisition thread if RefreshMode::UploadAndWaitForRepaint is set. Disabling the wait will abort any current waiting and cause blocking calls to ImageView::Refresh() to return. All further calls will not block, until waiting is enabled again. While the waiting is disabled rendering will fall back to RefreshMode::UploadAndScheduleRepaint.

This method must be called from the UI thread.

Note
Changing the refresh mode to RefreshMode::UploadAndScheduleRepaint is not equivalent, as it will not abort any current waiting.
See also
ImageView::Refresh(const class Image &, enum class RefreshMode)

◆ SetZoom()

void SetZoom ( ZoomDescriptor  zoomDescriptor)
inlinenoexcept

Set the current zoom descriptor.

Parameters
[in]zoomDescriptorThe new zoom descriptor.
Exceptions
Doesnot throw any exception.

◆ showEvent()

void showEvent ( QShowEvent event)
inlineoverrideprotectedvirtual

Handle show events.

Parameters
[in]eventThe Qt event.
Exceptions
Doesnot throw any exception.

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QGraphicsView.

◆ TryZoomIn()

bool TryZoomIn ( )
inlinenoexcept

Tries to zoom in.

Returns
True if successful, false otherwise.
Exceptions
Doesnot throw any exception.

◆ TryZoomOut()

bool TryZoomOut ( )
inlinenoexcept

Tries to zoom out.

Returns
bool True if successful, false otherwise.
Exceptions
Doesnot throw any exception.

◆ UnregisterEventMouseMoved()

void UnregisterEventMouseMoved ( Cvb::EventCookie  eventCookie)
inlinenoexcept

Unregister a callback to get pixel values under the moving mouse.

Parameters
[in]eventCookieCookie obtained when the callback was registered.
Exceptions
Doesnot throw any exception.

◆ UploadMode()

Cvb::UI::UploadMode UploadMode ( ) const
inlinenoexcept

Get the current upload mode.

Returns
UploadMode The current upload mode.
Exceptions
Doesnot throw any exception.

◆ wheelEvent()

void wheelEvent ( QWheelEvent event)
inlineoverrideprotectedvirtual

Handle mouse wheel events to zoom.

Parameters
[in]eventThe Qt event.
Exceptions
Doesnot throw any exception.

Reimplement if you need a different behavior.

See also
ImageView::SetWaitForRepaintEnabled(bool)

Reimplemented from QGraphicsView.

◆ Zoom()

ZoomDescriptor Zoom ( ) const
inlinenoexcept

Get the current zoom descriptor.

Returns
The current zoom descriptor.
Exceptions
Doesnot throw any exception.