immvision (C++)

ImmVision: display and inspect images: zoom and pan, pixel values, colormaps for one-channel and float images, views that zoom together, and an inspector that collects images from anywhere in a program.

Start with: ImmVision::Image, ImmVision::ImageDisplay, ImmVision::ImageDisplayResizable, ImageParams, ImmVision::Inspector_AddImage, ImmVision::Inspector_Show.

immvision_types.h¶

Size2d (struct)¶

struct Size2d

2D double-precision size. Used for drawing operations (ellipse, rectangle_size).

Size2d::Size2d¶

Size2d() = default;

Size2d(double w, double h) : width(w), height(h);

Size2d(const Size& s) : width((double)s.width), height((double)s.height);

Color4d (struct)¶

struct Color4d

4-channel double color value (e.g. RGBA or BGRA).

Color4d::Color4d¶

Color4d() = default;

Color4d(double v0, double v1, double v2, double v3) : v{v0, v1, v2, v3};

Rect (struct)¶

struct Rect

Integer rectangle (x, y, width, height).

Rect::Rect¶

Rect() = default;

Rect(int x_, int y_, int w, int h) : x(x_), y(y_), width(w), height(h);

Rect(Point pt, Size sz) : x(pt.x), y(pt.y), width(sz.width), height(sz.height);

Rect(Point pt1, Point pt2)

Construct from two corner points (top-left and bottom-right)

Rect::empty¶

bool empty() const;

Rect::area¶

int area() const;

Rect::contains¶

bool contains(Point pt) const;

Rect::size¶

Size size() const;

image.h¶

Color order¶

The color order of displayed images: RGB by default.
For images in BGR order (OpenCV), call once at the start of your program:
ImmVision::UseBgrColorOrder() (C++) immvision.use_bgr_color_order() (Python)

ImmVision::UseRgbColorOrder¶

IMMVISION_API void UseRgbColorOrder();

ImmVision::UseBgrColorOrder¶

IMMVISION_API void UseBgrColorOrder();

ImmVision::IsUsingRgbColorOrder¶

IMMVISION_API bool IsUsingRgbColorOrder();

Returns True if we are using RGB color order

ImmVision::IsUsingBgrColorOrder¶

IMMVISION_API bool IsUsingBgrColorOrder();

Returns True if we are using BGR color order

ImmVision::IsColorOrderUndefined¶

IMMVISION_API bool IsColorOrderUndefined();

Returns True if the color order was never set (UseRgbColorOrder or UseBgrColorOrder was not called): RGB is used

ImmVision::PushColorOrderRgb¶

IMMVISION_API void PushColorOrderRgb();

Temporary change of color order (useful for displaying a single image with a different color order)

ImmVision::PushColorOrderBgr¶

IMMVISION_API void PushColorOrderBgr();

ImmVision::PopColorOrder¶

IMMVISION_API void PopColorOrder();

Display parameters¶

ColorMapStatsTypeId (enum)¶

enum class ColorMapStatsTypeId

Are we using the stats on the full image, on the Visible ROI, or are we using Min/Max values

ImageInterpolationMode (enum)¶

enum class ImageInterpolationMode

Texture interpolation used when displaying an image

ColormapScaleFromStatsData (struct)¶

struct ColormapScaleFromStatsData

Scale the Colormap according to the Image stats

ColormapSettingsData (struct)¶

struct ColormapSettingsData

Colormap Settings (useful for matrices with one channel, in order to see colors mapping float values)

MouseInformation (struct)¶

struct MouseInformation

Contains information about the mouse inside an image

ImageParams (struct)¶

struct ImageParams

Set of display parameters and options for an Image

ImageParams::ImageToScreen¶

IMMVISION_API ImVec2 ImageToScreen(ImVec2 imagePoint) const;

The screen position of a point of the image (in image coordinates), with the current zoom and pan: to draw over the image, e.g. with ImGui::GetWindowDrawList(). Valid once the image was displayed.

ImmVision::ImageParamsToJson¶

IMMVISION_API std::string ImageParamsToJson(const ImageParams& params);

ImmVision::FillImageParamsFromJson¶

IMMVISION_API void FillImageParamsFromJson(const std::string& json, ImageParams* params);

ImmVision::ImageParamsFromJson¶

IMMVISION_API ImageParams ImageParamsFromJson(const std::string& json);

ImmVision::FactorImageParamsDisplayOnly¶

IMMVISION_API ImageParams FactorImageParamsDisplayOnly();

Create ImageParams that display the image only, with no decoration, and no user interaction

ImmVision::MakeZoomPanMatrix¶

IMMVISION_API Matrix33d MakeZoomPanMatrix( const Point2d & zoomCenter, double zoomRatio, const Size displayedImageSize );

Create a zoom/pan matrix centered around a given point of interest

ImmVision::MakeZoomPanMatrix_ScaleOne¶

IMMVISION_API Matrix33d MakeZoomPanMatrix_ScaleOne( Size imageSize, const Size displayedImageSize );

ImmVision::MakeZoomPanMatrix_FullView¶

IMMVISION_API Matrix33d MakeZoomPanMatrix_FullView( Size imageSize, const Size displayedImageSize );

Display an image¶

ImmVision::Image¶

IMMVISION_API void Image(const std::string& label, const ImageBuffer& image, ImageParams* params);

Display an image, with full user control: zoom, pan, watch pixels, etc.

• label: the legend, displayed above the image. It is also the widget’s id: two images cannot share it (if they do, they might not refresh correctly). To keep a legend and make the id unique, append a suffix: "MyLabel##some_unique_id" (the part after ## is not displayed); to display no legend, use "##some_unique_id"; or wrap the call in imgui.push_id("some_unique_string") / imgui.pop_id().

• image: the image to display. All dense image types are supported (uint8, int16, float32, etc.).
  C++: an ImageBuffer, or a cv::Mat (implicit conversion, zero-copy). Python: a numpy.ndarray.

• params: the options (zoom, colormap, ...) as inputs, and the outputs (mouse position, watched pixels, ...): see ImageParams. It is an input-output parameter, passed as a pointer: keep it alive from frame to frame (if you cannot zoom or pan in a displayed image, extend the scope of its ImageParams).

This function requires that both imgui and OpenGL were initialized (for example, run the app with immapp.run in Python, or HelloImGui::Run in C++).

ImmVision::ImageDisplay¶

IMMVISION_API Point2d ImageDisplay( const std::string& label_id, const ImageBuffer& image, const Size& imageDisplaySize = (0, 0), bool refreshImage = false, bool showOptionsButton = false );

Display an image, with no user interaction by default: a simpler and faster alternative to image().

• label_id: the legend, and the widget’s id (unique: see image()). To display no legend, use "##some_unique_id". A displayed legend makes the widget taller than image_display_size.

• image: the image to display. C++: an ImageBuffer, or a cv::Mat (implicit conversion, zero-copy).
  Python: a numpy.ndarray.

• image_display_size: the size of the displayed image, which may differ from the image’s. With only the width or the height given (e.g. (300, 0)), the other dimension follows the image’s aspect ratio.
  A negative value is the remaining width (or height) of the window minus its absolute value, as ImGui’s item widths: (-1, 0) fills the width of the window.

• refresh_image: the textures are cached: set it to True when the image changed (e.g. live video).

• show_options_button: shows a button that opens the options panel; zoom, pan and watched pixels (double-click) then become possible.

Returns the mouse position in the original image’s coordinates, as doubles, whatever image_display_size: (-1, -1) when the mouse is not over the image. For the buttons, see imgui.is_mouse_down (C++) or imgui.is_mouse_down (Python).

This function requires that both imgui and OpenGL were initialized (see image()).

ImmVision::ImageDisplayResizable¶

IMMVISION_API Point2d ImageDisplayResizable( const std::string& label_id, const ImageBuffer& image, ImVec2* size = nullptr, bool refreshImage = false, bool resizable = true, bool showOptionsButton = false );

Display an image, with no user interaction by default, in a widget the user can resize.
The label is not displayed, but it is the widget’s id (unique: see image()).

• image: the image to display. C++: an ImageBuffer, or a cv::Mat (implicit conversion, zero-copy).
  Python: a numpy.ndarray.

• size: the displayed size, in and out: the size chosen by the user is stored in it, when given.
  A negative value is the remaining width (or height) of the window ((-1, 0): the width of the window), resolved once: the concrete size is stored back.

• refresh_image: the textures are cached: set it to True when the image changed (e.g. live video).

• resizable: whether the user can resize the widget.

• show_options_button: shows a button that opens the options panel.

Returns the mouse position in the original image’s coordinates, as image_display() does.

Utilities¶

ImmVision::AvailableColormaps¶

IMMVISION_API std::vector<std::string> AvailableColormaps();

Return the list of the available color maps
Taken from https://github.com/yuki-koyama/tinycolormap, thanks to Yuki Koyama

ImmVision::ClearTextureCache¶

IMMVISION_API void ClearTextureCache();

Clears the internal texture cache of immvision (this is done automatically at exit time)

Note: this function requires that both imgui and OpenGL were initialized. (for example, use imgui_runner.runfor Python, or HelloImGui::Run for C++)

ImmVision::GetCachedRgbaImage¶

IMMVISION_API ImageBuffer GetCachedRgbaImage(const std::string& label);

Returns the RGBA image currently displayed by ImmVision::Image or ImmVision::ImageDisplay
Note: this image must be currently displayed. This function will return the transformed image (i.e with ColorMap, Zoom, etc.)

ImmVision::VersionInfo¶

IMMVISION_API std::string VersionInfo();

Return immvision version info

ImmVision::ImRead¶

IMMVISION_API ImageBuffer ImRead(const std::string& filename);

Load an image from file (PNG, JPG, BMP, TGA, HDR, etc.) using stb_image.
Returns an empty ImageBuffer if loading fails.
The returned image is always in RGB order (not BGR).
For uint8 images: channels are as stored in file (1, 3, or 4).
For HDR images: returns float32 data.

inspector.h¶

ImmVision::Inspector_AddImage¶

IMMVISION_API void Inspector_AddImage( const ImageBuffer& image, const std::string& legend, const std::string& zoomKey = "", const std::string& colormapKey = "", const Point2d & zoomCenter = (0., 0.), double zoomRatio = -1. );

Add an image to the inspector. Call this from anywhere (e.g. at different steps of an image processing pipeline). Later, call Inspector_Show() to display all collected images.

:param image:
The image to add.
C++: accepts ImageBuffer directly, or cv::Mat (implicit conversion, zero-copy).
Python: pass a numpy.ndarray.

ImmVision::Inspector_Show¶

IMMVISION_API void Inspector_Show();

ImmVision::Inspector_ClearImages¶

IMMVISION_API void Inspector_ClearImages();

gl_texture.h¶

GlTexture (struct)¶

struct GlTexture

GlTexture contains an OpenGL texture which can be created or updated from an ImageBuffer (C++), or numpy array (Python)

GlTexture::GlTexture¶

GlTexture();

GlTexture(const ImageBuffer& image, bool isColorOrderBGR = false);

GlTexture(GlTexture&& other) noexcept = default;

Create an empty texture

GlTexture::UpdateFromImage¶

void UpdateFromImage(const ImageBuffer& image, bool isColorOrderBGR = false);

Update the texture from a new image (ImageBuffer in C++, numpy array in Python).

GlTexture::SizeImVec2¶

ImVec2 SizeImVec2() const;

Returns the size as ImVec2