View to display an image. More...

#include <cvb/ui/image_view.hpp>

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 ImageScene *	ImageScene () 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:: Cvb::UI::ImageView view;

view.setWindowIcon(QIcon(":/qttutorial.png"));

view.SetUploadMode(Cvb::UI::UploadMode::Viewport);

view.SetRenderEngine(Cvb::UI::RenderEngine::OpenGL2);

Cvb::String path(CVB_LIT("%CVB%/Tutorial/ClaraRGB.bmp"));

// expand environment variables in path

path = Cvb::ExpandPath(path);

// load the image

Cvb::ImagePtr image = Cvb::Image::Load(path);

// refresh the image view

view.Refresh(image);

view.show();

std::string

Cvb::Image::Load
static std::unique_ptr< Image > Load(const String &fileName)
Loads an image with the given file name.
Definition: detail_image.hpp:32

Cvb::UI::ImageView
View to display an image.
Definition: decl_image_view.hpp:75

Cvb::UI::ImageView::SetUploadMode
void SetUploadMode(Cvb::UI::UploadMode uploadMode)
Set the current upload mode.
Definition: decl_image_view.hpp:357

Cvb::UI::ImageView::Refresh
void Refresh(Cvb::UI::RefreshMode refreshMode)
Refresh the view using a specified mode.
Definition: detail_image_view.hpp:68

Cvb::UI::ImageView::SetRenderEngine
void SetRenderEngine(Cvb::UI::RenderEngine renderEngine)
Set the current render engine.
Definition: detail_image_view.hpp:252

Cvb::UI::UploadMode::Viewport
@ Viewport

Cvb::UI::RenderEngine::OpenGL2
@ OpenGL2

QIcon

QWidget::show
void show()

QWidget::setWindowIcon
void setWindowIcon(const QIcon &icon)

std::shared_ptr< Image >

Examples: Cvb/QtDisplayAdvanced, Cvb/QtImageDisplay, Cvb/QtStatisticsDisplay, Cvb/QtStreamDisplay, Cvb/QtStreamDisplayPair, Movie2/QtMovie2, ShapeFinder2/QtShapeFinder2, and ShapeFinder2/QtShapeFinder2Cuda.

Constructor & Destructor Documentation

◆ ImageView() [1/2]

ImageView ( QWidget * parent = nullptr )

inlineexplicit

Create an image view.

Parameters

[in] parent Parent object in Qt's object hierarchie.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ ImageView() [2/2]

ImageView	(	class ImageScene *	scene,
		QWidget *	parent = `nullptr`
	)

inlineexplicit

Parameters

[in]	scene	Scene to use with this view.
[in]	parent	Parent object in Qt's object hierarchie.

Exceptions

Any	exception 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] event The Qt event.

Exceptions

Does	not 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] scheduleRepaint Custom callback.

Exceptions

Does	not 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] customWaitForRepaint Custom callback.

Exceptions

Does	not 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

Does	not throw any exception.

◆ ImageScene()

ImageScene * ImageScene ( ) const

inlinenoexcept

Get the image scene.

Returns: The image scene associated with this image view.

Exceptions

Does	not 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

Does	not throw any exception.

◆ IsWaitForRepaintEnabled()

bool IsWaitForRepaintEnabled ( ) const

inlinenoexcept

Checks if waiting for repaint is set.

Returns: True if enabled, false otherwise.

Exceptions

Does	not throw any exception.

◆ mouseMoveEvent()

void mouseMoveEvent ( QMouseEvent * event )

inlineoverrideprotectedvirtual

Handle mouse move events.

Parameters

[in] event The Qt event.

Exceptions

Does	not 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

Any	exception 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] image The image, which is not shared with the display.

Exceptions

Any	exception 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]	image	The image, which is not shared with the display.
[in]	refreshMode	The refresh mode

Exceptions

Any	exception 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
RenderEngine	Upload Thread	Render 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]	image	The image, which will be shared with the display.
[in]	autoRefresh	Switch to control automatic refreshing.

Exceptions

Any	exception 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]	image	The image, which will be shared with the display.
[in]	refreshMode	The refresh mode
[in]	autoRefresh	Switch to control automatic refreshing.

Exceptions

Any	exception 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] refreshMode The refresh mode.

Exceptions

Any	exception 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

Does	not 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] handler The callback.

Returns: Cookie to unregister the callback if not needed anymore.

Exceptions

Any	exception derived from std::exception including CvbException.

Examples: Cvb/QtImageDisplay.

◆ ReleaseRefreshShare()

void ReleaseRefreshShare ( )

inlinenoexcept

Releases the shared image.

Exceptions

Does	not 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

Does	not throw any exception.

◆ ResetCustomScheduleRepaint()

void ResetCustomScheduleRepaint ( )

inlinenoexcept

Reset to the default value.

Exceptions

Does	not throw any exception.

◆ ResetCustomWaitForRepaint()

void ResetCustomWaitForRepaint ( )

inlinenoexcept

Reset to the default value.

Exceptions

Does	not throw any exception.

◆ resizeEvent()

void resizeEvent ( QResizeEvent * event )

inlineoverrideprotectedvirtual

Handle resize events.

Parameters

[in] event The Qt event.

Exceptions

Does	not 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]	dx	Distance covered in x.
[in]	dy	Distance covered in Y.

Exceptions

Does	not 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] enabled True to enable, false to disable.

Exceptions

Does	not 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] refreshMode The new refresh mode.

Exceptions

Does	not throw any exception.

◆ SetRenderEngine()

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

inline

Set the current render engine.

Parameters

[in] renderEngine The new Render engine.

Exceptions

Any	exception 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] uploadMode The new upload mode.

Exceptions

Any	exception 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] enabled True to enable, false to disable.

Exceptions

Any	exception 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] zoomDescriptor The new zoom descriptor.

Exceptions

Does	not throw any exception.

◆ showEvent()

void showEvent ( QShowEvent * event )

inlineoverrideprotectedvirtual

Handle show events.

Parameters

[in] event The Qt event.

Exceptions

Does	not 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

Does	not throw any exception.

◆ TryZoomOut()

bool TryZoomOut ( )

inlinenoexcept

Tries to zoom out.

Returns: bool True if successful, false otherwise.

Exceptions

Does	not throw any exception.

◆ UnregisterEventMouseMoved()

void UnregisterEventMouseMoved ( Cvb::EventCookie eventCookie )

inlinenoexcept

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

Parameters

[in] eventCookie Cookie obtained when the callback was registered.

Exceptions

Does	not throw any exception.

◆ UploadMode()

Cvb::UI::UploadMode UploadMode ( ) const

inlinenoexcept

Get the current upload mode.

Returns: UploadMode The current upload mode.

Exceptions

Does	not throw any exception.

◆ wheelEvent()

void wheelEvent ( QWheelEvent * event )

inlineoverrideprotectedvirtual

Handle mouse wheel events to zoom.

Parameters

[in] event The Qt event.

Exceptions

Does	not 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

Does	not throw any exception.

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ImageView() [1/2]

◆ ImageView() [2/2]

Member Function Documentation

◆ closeEvent()

◆ CustomScheduleRepaint()

◆ CustomWaitForRepaint()

◆ Image()

◆ ImageScene()

◆ IsEventRefreshEnabled()

◆ IsWaitForRepaintEnabled()

◆ mouseMoveEvent()

◆ Refresh() [1/6]

◆ Refresh() [2/6]

◆ Refresh() [3/6]

◆ Refresh() [4/6]

◆ Refresh() [5/6]

◆ Refresh() [6/6]

◆ RefreshMode()

◆ RegisterEventMouseMoved()

◆ ReleaseRefreshShare()

◆ RenderEngine()

◆ ResetCustomScheduleRepaint()

◆ ResetCustomWaitForRepaint()

◆ resizeEvent()

◆ scrollContentsBy()

◆ SetEventRefreshEnabled()

◆ SetRefreshMode()

◆ SetRenderEngine()

◆ SetUploadMode()

◆ SetWaitForRepaintEnabled()

◆ SetZoom()

◆ showEvent()

◆ TryZoomIn()

◆ TryZoomOut()

◆ UnregisterEventMouseMoved()

◆ UploadMode()

◆ wheelEvent()

◆ Zoom()