vendor: OpenCV 5.0.0 snapshot at 755e50675d97db9b7d449d8bd6b09888646f6c6e

modules/ovis/CMakeLists.txt

@@ -0,0 +1,30 @@
+set(the_description "OGRE 3D Visualiser.")
+
+find_package(OGRE QUIET CONFIG)
+
+if(NOT OGRE_FOUND)
+  message(STATUS "Module opencv_ovis disabled because OGRE3D was not found")
+  ocv_module_disable(ovis)
+elseif(OGRE_VERSION VERSION_LESS 1.11.5)
+  message(STATUS "Module opencv_ovis disabled because of incompatible OGRE3D version (${OGRE_VERSION})")
+  ocv_module_disable(ovis)
+else() # we need C++11 for OGRE 1.11
+  if(MSVC)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qstd=c++11")
+  else()
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+  endif()
+endif()
+
+include_directories(${OGRE_INCLUDE_DIRS})
+link_directories(${OGRE_LIBRARY_DIRS})
+
+ocv_add_module(ovis opencv_core opencv_imgproc opencv_geometry WRAP python)
+ocv_glob_module_sources()
+ocv_module_include_directories()
+ocv_create_module()
+
+ocv_add_samples(opencv_objdetect opencv_aruco)
+
+ocv_warnings_disable(CMAKE_CXX_FLAGS -Wunused-parameter)
+ocv_target_link_libraries(${the_module} ${OGRE_LIBRARIES})

modules/ovis/README.md

@@ -0,0 +1,4 @@
+OVIS Module
+===========
+
+allows you to render 3D data using the OGRE 3D engine and obtain the rendering as cv::Mat.

modules/ovis/include/opencv2/ovis.hpp

@@ -0,0 +1,423 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+#ifndef _OPENCV_OVIS_H_
+#define _OPENCV_OVIS_H_
+
+#include <opencv2/core.hpp>
+
+/**
+@defgroup ovis OGRE 3D Visualiser
+
+ovis is a simplified rendering wrapper around [ogre3d](https://www.ogre3d.org/).
+The [Ogre terminology](https://ogrecave.github.io/ogre/api/latest/_the-_core-_objects.html) is used in the API
+and [Ogre Script](https://ogrecave.github.io/ogre/api/latest/_scripts.html) is assumed to be used for advanced customization.
+
+Besides the API you see here, there are several environment variables that control the behavior of ovis.
+They are documented in @ref createWindow.
+
+## Loading geometry
+
+You can create geometry [on the fly](@ref createTriangleMesh) or by loading Ogre `.mesh` files.
+
+### Blender
+For converting/ creating geometry [Blender](https://www.blender.org/) is recommended.
+- Blender 2.7x is better tested, but Blender 2.8x should work too
+- install [blender2ogre](https://github.com/OGRECave/blender2ogre) matching your Blender version
+- download the [Ogre MSVC SDK](https://www.ogre3d.org/download/sdk/sdk-ogre) which contains `OgreXMLConverter.exe` (in `bin/`) and set the path in the blender2ogre settings
+- get [ogre-meshviewer](https://github.com/OGRECave/ogre-meshviewer) to enable the preview function in blender2ogre as well as for verifying the exported files
+- in case the exported materials are not exactly how you want them, consult the [Ogre Manual](https://ogrecave.github.io/ogre/api/latest/_material-_scripts.html)
+
+### Assimp
+When using Ogre 1.12.9 or later, enabling the Assimp plugin allows to load arbitrary geometry.
+Simply pass `bunny.obj` instead of `bunny.mesh` as `meshname` in @ref WindowScene::createEntity.
+
+You should still use ogre-meshviewer to verify that the geometry is converted correctly.
+*/
+
+namespace cv {
+namespace ovis {
+//! @addtogroup ovis
+//! @{
+
+enum SceneSettings
+{
+    /// the window will use a separate scene. The scene will be shared otherwise.
+    SCENE_SEPARATE = 1,
+    /// allow the user to control the camera.
+    SCENE_INTERACTIVE = 2,
+    /// draw coordinate system crosses for debugging
+    SCENE_SHOW_CS_CROSS = 4,
+    /// Apply anti-aliasing. The first window determines the setting for all windows.
+    SCENE_AA = 8,
+    /// Render off-screen without a window. Allows separate AA setting. Requires manual update via @ref WindowScene::update
+    SCENE_OFFSCREEN = 16,
+    /// Enable real-time shadows in the scene. All entities cast shadows by default. Control via @ref ENTITY_CAST_SHADOWS
+    SCENE_SHADOWS = 32
+};
+
+enum MaterialProperty
+{
+    MATERIAL_POINT_SIZE,
+    MATERIAL_LINE_WIDTH,
+    MATERIAL_OPACITY,
+    MATERIAL_EMISSIVE,
+    MATERIAL_DIFFUSE,
+    MATERIAL_TEXTURE0,
+    MATERIAL_TEXTURE = MATERIAL_TEXTURE0,
+    MATERIAL_TEXTURE1,
+    MATERIAL_TEXTURE2,
+    MATERIAL_TEXTURE3,
+};
+
+enum EntityProperty
+{
+    ENTITY_MATERIAL,
+    ENTITY_SCALE,
+    ENTITY_AABB_WORLD,
+    ENTITY_ANIMBLEND_MODE,
+    ENTITY_CAST_SHADOWS
+};
+
+/**
+ * A 3D viewport and the associated scene
+ */
+class CV_EXPORTS_W WindowScene {
+public:
+    virtual ~WindowScene();
+
+    /**
+     * set window background to custom image/ color
+     * @param image
+     */
+    CV_WRAP virtual void setBackground(InputArray image) = 0;
+
+    /// @overload
+    CV_WRAP_AS(setBackgroundColor) virtual void setBackground(const Scalar& color) = 0;
+
+    /**
+     * enable an ordered chain of full-screen post processing effects
+     *
+     * this way you can add distortion or SSAO effects.
+     * The effects themselves must be defined inside Ogre .compositor scripts.
+     * @param names compositor names that will be applied in order of appearance
+     * @see addResourceLocation
+     */
+    CV_WRAP virtual void setCompositors(const std::vector<String>& names) = 0;
+
+    /**
+     * place an entity of a mesh in the scene
+     *
+     * the mesh needs to be created beforehand. Either programmatically
+     * by e.g. @ref createPointCloudMesh or by placing the respective file in a resource location.
+     * @param name entity name
+     * @param meshname mesh name
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     * @see addResourceLocation
+     */
+    CV_WRAP virtual void createEntity(const String& name, const String& meshname,
+                                      InputArray tvec = noArray(), InputArray rot = noArray()) = 0;
+
+    /**
+     * remove an entity from the scene
+     * @param name entity name
+     */
+    CV_WRAP virtual void removeEntity(const String& name) = 0;
+
+    /**
+     * set the property of an entity to the given value
+     * @param name entity name
+     * @param prop @ref EntityProperty
+     * @param value the value
+     * @param subEntityIdx index of the sub-entity (default: all)
+     */
+    CV_WRAP virtual void setEntityProperty(const String& name, int prop, const String& value,
+                                           int subEntityIdx = -1) = 0;
+
+    /// @overload
+    CV_WRAP virtual void setEntityProperty(const String& name, int prop, const Scalar& value) = 0;
+
+    /**
+     * get the property of an entity
+     * @param name entity name
+     * @param prop @ref EntityProperty
+     * @param value the value
+     */
+    CV_WRAP virtual void getEntityProperty(const String& name, int prop, OutputArray value) = 0;
+
+    /**
+     * convenience method to visualize a camera position
+     *
+     * @param name entity name
+     * @param K intrinsic matrix
+     * @param imsize image size
+     * @param zFar far plane in camera coordinates
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     * @param color line color
+     * @return the extents of the Frustum at far plane, where the top left corner denotes the principal
+     * point offset
+     */
+    CV_WRAP virtual Rect2d createCameraEntity(const String& name, InputArray K, const Size& imsize,
+                                              float zFar, InputArray tvec = noArray(),
+                                              InputArray rot = noArray(),
+                                              const Scalar& color = Scalar::all(1)) = 0;
+
+    /**
+     * creates a point light in the scene
+     * @param name entity name
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     * @param diffuseColor
+     * @param specularColor
+     */
+    CV_WRAP virtual void createLightEntity(const String& name, InputArray tvec = noArray(),
+                                           InputArray rot = noArray(),
+                                           const Scalar& diffuseColor = Scalar::all(1),
+                                           const Scalar& specularColor = Scalar::all(1)) = 0;
+
+    /**
+     * update entity pose by transformation in the parent coordinate space. (pre-rotation)
+     * @param name entity name
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     */
+    CV_WRAP virtual void updateEntityPose(const String& name, InputArray tvec = noArray(),
+                                          InputArray rot = noArray()) = 0;
+
+    /**
+     * set entity pose in the world coordinate space.
+     * @param name enitity name
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     * @param invert use the inverse of the given pose
+     */
+    CV_WRAP virtual void setEntityPose(const String& name, InputArray tvec = noArray(),
+                                       InputArray rot = noArray(), bool invert = false) = 0;
+
+	/**
+     * Retrieves the current pose of an entity
+	 * @param name entity name
+     * @param R 3x3 rotation matrix
+     * @param tvec translation vector
+     * @param invert return the inverted pose
+     */
+	CV_WRAP virtual void getEntityPose(const String& name, OutputArray R = noArray(), OutputArray tvec = noArray(),
+                                       bool invert = false) = 0;
+
+    /**
+     * get a list of available entity animations
+     * @param name entity name
+     * @param out the animation names
+     */
+    CV_WRAP virtual void getEntityAnimations(const String& name, std::vector<String>& out) = 0;
+
+    /**
+     * play entity animation
+     * @param name entity name
+     * @param animname animation name
+     * @param loop enable or disable animation loop
+     * @see getEntityAnimations
+     */
+    CV_WRAP virtual void playEntityAnimation(const String& name, const String& animname,
+                                               bool loop = true) = 0;
+
+    /**
+     * stop entity animation
+     * @param name enitity name
+     * @param animname animation name
+     */
+    CV_WRAP virtual void stopEntityAnimation(const String& name, const String& animname) = 0;
+
+    /**
+     * read back the image generated by the last call to @ref waitKey
+     */
+    CV_WRAP virtual void getScreenshot(OutputArray frame) = 0;
+
+    /**
+     * read back the texture of an active compositor
+     * @param compname name of the compositor
+     * @param texname name of the texture inside the compositor
+     * @param mrtIndex if texture is a MRT, specifies the attachment
+     * @param out the texture contents
+     */
+    CV_WRAP virtual void getCompositorTexture(const String& compname, const String& texname,
+                                              OutputArray out, int mrtIndex = 0) = 0;
+
+    /**
+     * get the depth for the current frame.
+     *
+     * return the per pixel distance to the camera in world units
+     */
+    CV_WRAP virtual void getDepth(OutputArray depth) = 0;
+
+    /**
+     * convenience method to force the "up" axis to stay fixed
+     *
+     * works with both programmatic changes and SCENE_INTERACTIVE
+     * @param useFixed whether to enforce the fixed yaw axis
+     * @param up the axis to be fixed
+     */
+    CV_WRAP virtual void fixCameraYawAxis(bool useFixed, InputArray up = noArray()) = 0;
+
+    /**
+     * Sets the current camera pose
+     * @param tvec translation
+     * @param rot @ref Rodrigues vector or 3x3 rotation matrix
+     * @param invert use the inverse of the given pose
+     */
+    CV_WRAP virtual void setCameraPose(InputArray tvec = noArray(), InputArray rot = noArray(),
+                                       bool invert = false) = 0;
+
+    /**
+     * convenience method to orient the camera to a specific entity
+     * @param target entity name
+     * @param offset offset from entity centre
+     */
+    CV_WRAP virtual void setCameraLookAt(const String& target, InputArray offset = noArray()) = 0;
+
+	/**
+     * convenience method to orient an entity to a specific entity.
+	 * If target is an empty string the entity looks at the given offset point
+	 * @param origin entity to make look at
+     * @param target name of target entity
+	 * @param offset offset from entity centre
+     */
+	CV_WRAP virtual void setEntityLookAt(const String& origin, const String& target, InputArray offset = noArray()) = 0;
+
+    /**
+     * Retrieves the current camera pose
+     * @param R 3x3 rotation matrix
+     * @param tvec translation vector
+     * @param invert return the inverted pose
+     */
+    CV_WRAP virtual void getCameraPose(OutputArray R = noArray(), OutputArray tvec = noArray(),
+                                       bool invert = false) = 0;
+
+    /**
+     * set intrinsics of the camera
+     *
+     * @param K intrinsic matrix or noArray(). If noArray() is specified, imsize
+     * is ignored and zNear/ zFar can be set separately.
+     * @param imsize image size
+     * @param zNear near clip distance or -1 to keep the current
+     * @param zFar  far clip distance or -1 to keep the current
+     */
+    CV_WRAP virtual void setCameraIntrinsics(InputArray K, const Size& imsize,
+                                             float zNear = -1,
+                                             float zFar = -1) = 0;
+    /**
+     * render this window, but do not swap buffers. Automatically called by @ref ovis::waitKey
+     */
+    CV_WRAP virtual void update() = 0;
+};
+
+/**
+ * Add an additional resource location that is search for meshes, textures and materials
+ *
+ * must be called before the first createWindow. If give path does not exist, retries inside
+ * Ogre Media Directory.
+ * @param path folder or Zip archive.
+ */
+CV_EXPORTS_W void addResourceLocation(const String& path);
+
+/**
+ * create a new rendering window/ viewport
+ * @param title window title
+ * @param size size of the window
+ * @param flags a combination of @ref SceneSettings
+ *
+ * Furthermore, the behavior is controlled by the following environment variables
+ * - OPENCV_OVIS_VERBOSE_LOG: print all of OGRE log output
+ * - OPENCV_OVIS_RENDERSYSTEM: the name of the OGRE RenderSystem to use
+ * - OPENCV_OVIS_NOVSYNC: disable VSYNC for all windows
+ */
+CV_EXPORTS_W Ptr<WindowScene> createWindow(const String& title, const Size& size,
+                                           int flags = SCENE_INTERACTIVE | SCENE_AA);
+
+/**
+ * update all windows and wait for keyboard event
+ *
+ * @param delay 0 is the special value that means "forever".
+ *        Any positive number returns after sync to blank (typically 16ms).
+ * @return the code of the pressed key or -1 if no key was pressed
+ */
+CV_EXPORTS_W int waitKey(int delay = 0);
+
+/**
+ * set the property of a material to the given value
+ * @param name material name
+ * @param prop @ref MaterialProperty
+ * @param value the value
+ */
+CV_EXPORTS_W void setMaterialProperty(const String& name, int prop, const Scalar& value);
+
+/// @overload
+CV_EXPORTS_W void setMaterialProperty(const String& name, int prop, const String& value);
+
+/**
+ * set the texture of a material to the given value
+ * @param name material name
+ * @param prop @ref MaterialProperty
+ * @param value the texture data
+ */
+CV_EXPORTS_AS(setMaterialTexture) void setMaterialProperty(const String& name, int prop, InputArray value);
+
+/**
+ * set the shader property of a material to the given value
+ * @param name material name
+ * @param prop property name
+ * @param value the value
+ */
+CV_EXPORTS_W void setMaterialProperty(const String& name, const String& prop, const Scalar& value);
+
+/**
+ * create a 2D plane, X right, Y down, Z up
+ *
+ * creates a material with the same name
+ * @param name name of the mesh
+ * @param size size in world units
+ * @param image optional texture
+ */
+CV_EXPORTS_W void createPlaneMesh(const String& name, const Size2f& size, InputArray image = noArray());
+
+/**
+ * creates a point cloud mesh
+ *
+ * creates a material with the same name
+ * @param name name of the mesh
+ * @param vertices float vector of positions
+ * @param colors uchar vector of colors
+ */
+CV_EXPORTS_W void createPointCloudMesh(const String& name, InputArray vertices, InputArray colors = noArray());
+
+/**
+ * creates a grid
+ *
+ * creates a material with the same name
+ * @param name name of the mesh
+ * @param size extents of the grid
+ * @param segments number of segments per side
+ */
+CV_EXPORTS_W void createGridMesh(const String& name, const Size2f& size, const Size& segments = Size(1, 1));
+
+/**
+ * creates a triangle mesh from vertex-vertex or face-vertex representation
+ *
+ * creates a material with the same name
+ * @param name name of the mesh
+ * @param vertices float vector of positions
+ * @param normals float vector of normals
+ * @param indices int vector of indices
+ */
+CV_EXPORTS_W void createTriangleMesh(const String& name, InputArray vertices, InputArray normals = noArray(), InputArray indices = noArray());
+
+/// @deprecated use setMaterialProperty
+CV_EXPORTS_W void updateTexture(const String& name, InputArray image);
+//! @}
+}
+}
+
+#endif

modules/ovis/misc/python/test_ovis.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+import os
+import numpy as np
+import cv2 as cv
+
+from tests_common import NewOpenCVTests
+#from unittest import TestCase as NewOpenCVTests
+
+
+class ovis_contrib_test(NewOpenCVTests):
+
+    def setUp(self):
+        super().setUp()
+        # use software rendering
+        os.environ["OPENCV_OVIS_RENDERSYSTEM"] = "Tiny Rendering Subsystem"
+        # in case something goes wrong
+        os.environ["OPENCV_OVIS_VERBOSE_LOG"] = "1"
+
+    def test_multiWindow(self):
+        win0 = cv.ovis.createWindow("main", (1, 1))
+        win1 = cv.ovis.createWindow("other", (1, 1))
+        del win1
+        win1 = cv.ovis.createWindow("other", (1, 1))
+        del win1
+
+    def test_addResourceLocation(self):
+        win0 = cv.ovis.createWindow("main", (1, 1))
+        with self.assertRaises(cv.error):
+            # must be called before the first createWindow
+            cv.ovis.addResourceLocation(".")
+
+    def test_texStride(self):
+        win = cv.ovis.createWindow("main", (1, 1))
+        data = np.zeros((200, 200), dtype=np.uint8)
+        cv.ovis.createPlaneMesh("plane", (1, 1), data[50:-50, 50:-50])
+
+
+if __name__ == '__main__':
+    NewOpenCVTests.bootstrap()

modules/ovis/samples/aruco_ar_demo.cpp

@@ -0,0 +1,70 @@
+#include <opencv2/highgui.hpp>
+#include <opencv2/geometry.hpp>
+#include <opencv2/videoio.hpp>
+
+#include <opencv2/ovis.hpp>
+#include <opencv2/aruco.hpp>
+
+#include <iostream>
+
+
+#define KEY_ESCAPE 27
+
+using namespace cv;
+
+int main()
+{
+  Mat img;
+  std::vector<std::vector<Point2f>> corners;
+  std::vector<int> ids;
+  std::vector<Vec3d> rvecs;
+  std::vector<Vec3d> tvecs;
+
+  const Size2i imsize(800, 600);
+  const double focal_length = 800.0;
+
+  // aruco
+  aruco::Dictionary adict = aruco::getPredefinedDictionary(aruco::DICT_4X4_50);
+
+  aruco::ArucoDetector detector(adict);
+  Mat out_img;
+  adict.generateImageMarker(0, 400, out_img);
+  imshow("marker", out_img);
+
+  // random calibration data, your mileage may vary
+  Mat1d cm = Mat1d::zeros(3, 3); // init empty matrix
+  cm.at<double>(0, 0) = focal_length; // f_x
+  cm.at<double>(1, 1) = focal_length; // f_y
+  cm.at<double>(2, 2) = 1; // f_z
+  Mat K = getDefaultNewCameraMatrix(cm, imsize, true);
+
+  // AR scene
+  ovis::addResourceLocation("packs/Sinbad.zip"); // shipped with Ogre
+
+  Ptr<ovis::WindowScene> win = ovis::createWindow(String("arucoAR"), imsize, ovis::SCENE_INTERACTIVE | ovis::SCENE_AA);
+  win->setCameraIntrinsics(K, imsize);
+  win->createEntity("sinbad", "Sinbad.mesh", Vec3i(0, 0, 5), Vec3f(1.57, 0.0, 0.0));
+  win->createLightEntity("sun", Vec3i(0, 0, 100));
+
+  // video capture
+  VideoCapture cap{0};
+  cap.set(CAP_PROP_FRAME_WIDTH, imsize.width);
+  cap.set(CAP_PROP_FRAME_HEIGHT, imsize.height);
+
+  std::cout << "Press ESCAPE to exit demo" << std::endl;
+  while (ovis::waitKey(1) != KEY_ESCAPE) {
+    cap.read(img);
+    win->setBackground(img);
+    detector.detectMarkers(img, corners, ids);
+
+    waitKey(1);
+
+    if (ids.size() == 0)
+      continue;
+
+    aruco::estimatePoseSingleMarkers(corners, 5, K, noArray(), rvecs, tvecs);
+    win->setCameraPose(tvecs.at(0), rvecs.at(0), true);
+  }
+
+  return 0;
+}

modules/ovis/samples/aruco_ar_demo.py

@@ -0,0 +1,36 @@
+import numpy as np
+import cv2 as cv
+
+# aruco
+adict = cv.aruco.getPredefinedDictionary(cv.aruco.DICT_4X4_50)
+cv.imshow("marker", adict.generateImageMarker(0, 400))
+
+# random calibration data. your mileage may vary.
+imsize = (800, 600)
+K = cv.getDefaultNewCameraMatrix(np.diag([800, 800, 1]), imsize, True)
+
+# AR scene
+cv.ovis.addResourceLocation("packs/Sinbad.zip") # shipped with Ogre
+
+win = cv.ovis.createWindow("arucoAR", imsize, flags=0)
+win.setCameraIntrinsics(K, imsize)
+win.createEntity("figure", "Sinbad.mesh", (0, 0, 5), (1.57, 0, 0))
+win.createLightEntity("sun", (0, 0, 100))
+
+# video capture
+cap = cv.VideoCapture(0)
+cap.set(cv.CAP_PROP_FRAME_WIDTH, imsize[0])
+cap.set(cv.CAP_PROP_FRAME_HEIGHT, imsize[1])
+
+while cv.ovis.waitKey(1) != 27:
+    img = cap.read()[1]
+    win.setBackground(img)
+    corners, ids = cv.aruco.detectMarkers(img, adict)[:2]
+
+    cv.waitKey(1)
+
+    if ids is None:
+        continue
+
+    rvecs, tvecs = cv.aruco.estimatePoseSingleMarkers(corners, 5, K, None)[:2]
+    win.setCameraPose(tvecs[0].ravel(), rvecs[0].ravel(), invert=True)

modules/ovis/samples/ovis_demo.cpp

@@ -0,0 +1,58 @@
+#include <opencv2/geometry.hpp>
+#include <opencv2/videoio.hpp>
+
+#include <opencv2/ovis.hpp>
+
+#include <iostream>
+
+
+#define KEY_ESCAPE 27
+
+using namespace cv;
+
+int main()
+{
+  Mat R;
+  Vec3d t;
+
+  const Size2i imsize(800, 600);
+  const double focal_length = 800.0;
+
+  //add some external resources
+  ovis::addResourceLocation("packs/Sinbad.zip"); // shipped with Ogre
+
+  //camera intrinsics
+  Mat1d K = Mat1d::zeros(3, 3); // init empty matrix
+  K.at<double>(0, 0) = focal_length; // f_x
+  K.at<double>(1, 1) = focal_length; // f_y
+  K.at<double>(0, 2) = 400; // t_x
+  K.at<double>(1, 2) = 500; // t_y
+  K.at<double>(2, 2) = 1; // f_z
+
+  //observer scene
+  Ptr<ovis::WindowScene> owin = ovis::createWindow(String("VR"), imsize);
+  ovis::createGridMesh("ground", Size2i(10, 10), Size2i(10, 10));
+  owin->createEntity("ground", "ground", Vec3f(1.57, 0, 0));
+  owin->createCameraEntity("cam", K, imsize, 5);
+  owin->createEntity("sinbad", "Sinbad.mesh", Vec3i(0, 0, 5), Vec3f(CV_PI/2.0, 0.0, 0.0)); // externally defined mesh
+  owin->createLightEntity("sun", Vec3i(0, 0, -100));
+
+  // setup and play idle animation
+  owin->setEntityProperty("sinbad", ovis::EntityProperty::ENTITY_ANIMBLEND_MODE, Scalar(1)); // 1 = cumulative
+  owin->playEntityAnimation("sinbad", "IdleBase");
+  owin->playEntityAnimation("sinbad", "IdleTop");
+
+  //interaction scene
+  Ptr<ovis::WindowScene> iwin = ovis::createWindow(String("AR"), imsize, ovis::SCENE_SEPARATE | ovis::SCENE_INTERACTIVE);
+  iwin->createEntity("sinbad", "Sinbad.mesh", Vec3i(0, -5, 0), Vec3f(CV_PI, 0.0, 0.0));
+  iwin->createLightEntity("sun", Vec3i(0, 0, -100));
+  iwin->setCameraIntrinsics(K, imsize);
+
+  std::cout << "Press ESCAPE to exit demo" << std::endl;
+  while (ovis::waitKey(1) != KEY_ESCAPE) {
+      iwin->getCameraPose(R, t);
+      owin->setEntityPose("cam", t, R);
+  }
+
+  return 1;
+}

modules/ovis/samples/ovis_demo.py

@@ -0,0 +1,35 @@
+import numpy as np
+import cv2 as cv
+
+# add some external resources
+cv.ovis.addResourceLocation("packs/Sinbad.zip")
+
+# camera intrinsics
+imsize = (800, 600)
+K = np.diag([800, 800, 1])
+K[:2, 2] = (400, 500) # offset pp
+
+# observer scene
+owin = cv.ovis.createWindow("VR", imsize)
+cv.ovis.createGridMesh("ground", (10, 10), (10, 10))
+owin.createEntity("ground", "ground", rot=(1.57, 0, 0))
+owin.createCameraEntity("cam", K, imsize, 5)
+owin.createEntity("sinbad", "Sinbad.mesh", tvec=(0, -5, 0), rot=(np.pi, 0, 0))  # externally defined mesh
+owin.createLightEntity("sun", (0, 0, -100))
+
+# setup and play idle animation
+owin.setEntityProperty("sinbad", cv.ovis.ENTITY_ANIMBLEND_MODE, 1) # 1 = cumulative
+owin.playEntityAnimation("sinbad", "IdleBase")
+owin.playEntityAnimation("sinbad", "IdleTop")
+
+# interaction scene
+iwin = cv.ovis.createWindow("AR", imsize, cv.ovis.SCENE_SEPARATE | cv.ovis.SCENE_INTERACTIVE)
+iwin.createEntity("sinbad", "Sinbad.mesh", tvec=(0, -5, 0), rot=(np.pi, 0, 0))
+iwin.createLightEntity("sun", (0, 0, -100))
+iwin.setCameraIntrinsics(K, imsize)
+
+while cv.ovis.waitKey(1) != 27:
+    R, t = iwin.getCameraPose()
+    owin.setEntityPose("cam", t, R)
+
+del iwin # must be destroyed in reverse creation order

modules/ovis/src/meshes.cpp

@@ -0,0 +1,246 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+#include "precomp.hpp"
+
+namespace cv
+{
+namespace ovis
+{
+using namespace Ogre;
+
+void createPlaneMesh(const String& name, const Size2f& size, InputArray image)
+{
+    CV_Assert(_app);
+
+    // material
+    MaterialPtr mat = MaterialManager::getSingleton().create(name, RESOURCEGROUP_NAME);
+
+    Pass* rpass = mat->getTechniques()[0]->getPasses()[0];
+    rpass->setCullingMode(CULL_NONE);
+    rpass->setEmissive(ColourValue::White);
+
+    if (!image.empty())
+    {
+        _createTexture(name, image.getMat());
+        rpass->createTextureUnitState(name);
+    }
+
+    // plane
+    MovablePlane plane(-Vector3::UNIT_Z, 0);
+    MeshPtr mesh = MeshManager::getSingleton().createPlane(
+        name, RESOURCEGROUP_NAME, plane, size.width, size.height, 1, 1, true, 1, 1, 1, -Vector3::UNIT_Y);
+    mesh->getSubMesh(0)->setMaterialName(name);
+}
+
+void createPointCloudMesh(const String& name, InputArray vertices, InputArray colors)
+{
+    int color_type = colors.type();
+    CV_Assert(_app);
+    CV_CheckTypeEQ(vertices.type(), CV_32FC3, "vertices type must be Vec3f");
+    CV_Assert(vertices.isContinuous());
+    if (!colors.empty())
+        CV_CheckType(color_type, color_type == CV_8UC3 || color_type == CV_8UC4, "unsupported type");
+
+    // material
+    MaterialPtr mat = MaterialManager::getSingleton().create(name, RESOURCEGROUP_NAME);
+    Pass* rpass = mat->getTechniques()[0]->getPasses()[0];
+    rpass->setEmissive(ColourValue::White);
+    rpass->setPointSpritesEnabled(true);
+
+    // mesh
+    MeshPtr mesh = MeshManager::getSingleton().createManual(name, RESOURCEGROUP_NAME);
+    SubMesh* sub = mesh->createSubMesh();
+    sub->useSharedVertices = true;
+    sub->operationType = RenderOperation::OT_POINT_LIST;
+    sub->setMaterialName(name);
+
+    int n = vertices.rows();
+
+    mesh->sharedVertexData = new VertexData();
+    mesh->sharedVertexData->vertexCount = n;
+    VertexDeclaration* decl = mesh->sharedVertexData->vertexDeclaration;
+
+    // vertex data
+    HardwareBufferManager& hbm = HardwareBufferManager::getSingleton();
+
+    Mat _vertices = vertices.getMat();
+
+    int source = 0;
+    HardwareVertexBufferSharedPtr hwbuf;
+
+    decl->addElement(source, 0, VET_FLOAT3, VES_POSITION);
+    hwbuf = hbm.createVertexBuffer(decl->getVertexSize(source), n, HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    hwbuf->writeData(0, hwbuf->getSizeInBytes(), _vertices.ptr(), true);
+    mesh->sharedVertexData->vertexBufferBinding->setBinding(source, hwbuf);
+
+    // color data
+    if (!colors.empty())
+    {
+        mat->setLightingEnabled(false);
+        source += 1;
+
+        Mat col4;
+        cvtColor(colors, col4, color_type == CV_8UC3 ? COLOR_BGR2RGBA : COLOR_BGRA2RGBA);
+
+        decl->addElement(source, 0, VET_COLOUR, VES_DIFFUSE);
+        hwbuf =
+            hbm.createVertexBuffer(decl->getVertexSize(source), n, HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+        hwbuf->writeData(0, hwbuf->getSizeInBytes(), col4.ptr(), true);
+        mesh->sharedVertexData->vertexBufferBinding->setBinding(source, hwbuf);
+
+        rpass->setVertexColourTracking(TVC_DIFFUSE);
+    }
+
+    AxisAlignedBox bounds(AxisAlignedBox::EXTENT_NULL);
+    for (int i = 0; i < n; i++)
+    {
+        Vec3f v = _vertices.at<Vec3f>(i);
+        bounds.merge(Vector3(v[0], v[1], v[2]));
+    }
+    mesh->_setBounds(bounds);
+}
+
+void createTriangleMesh(const String& name, InputArray vertices, InputArray normals, InputArray indices)
+{
+    CV_CheckTypeEQ(vertices.type(), CV_32FC3, "vertices type must be Vec3f");
+    CV_Assert(vertices.isContinuous());
+
+    if(!normals.empty())
+    {
+        CV_CheckTypeEQ(normals.type(), CV_32FC3, "normals type must be Vec3f");
+        CV_Assert(normals.isContinuous());
+        CV_Assert(normals.size() == vertices.size());
+    }
+    if(!indices.empty())
+    {
+        CV_CheckTypeEQ(indices.type(), CV_32S, "indices type must be int");
+        CV_Assert(indices.isContinuous());
+    }
+
+    // default material
+    auto mat = MaterialManager::getSingleton().create(name, RESOURCEGROUP_NAME);
+
+    // mesh
+    MeshPtr mesh = MeshManager::getSingleton().createManual(name, RESOURCEGROUP_NAME);
+    SubMesh* sub = mesh->createSubMesh();
+    sub->useSharedVertices = true;
+    sub->operationType = RenderOperation::OT_TRIANGLE_LIST;
+    sub->setMaterialName(name);
+
+    int n = vertices.rows();
+
+    mesh->sharedVertexData = new VertexData();
+    mesh->sharedVertexData->vertexCount = n;
+    VertexDeclaration* decl = mesh->sharedVertexData->vertexDeclaration;
+
+    // vertex data
+    HardwareBufferManager& hbm = HardwareBufferManager::getSingleton();
+
+    Mat _vertices = vertices.getMat();
+
+    int source = 0;
+    HardwareVertexBufferSharedPtr hwbuf;
+
+    decl->addElement(source, 0, VET_FLOAT3, VES_POSITION);
+    hwbuf = hbm.createVertexBuffer(decl->getVertexSize(source), n, HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    hwbuf->writeData(0, hwbuf->getSizeInBytes(), _vertices.ptr(), true);
+    mesh->sharedVertexData->vertexBufferBinding->setBinding(source, hwbuf);
+
+    // normals
+    if (!normals.empty())
+    {
+        source += 1;
+
+        Mat _normals = normals.getMat();
+        decl->addElement(source, 0, VET_FLOAT3, VES_NORMAL);
+        hwbuf =
+            hbm.createVertexBuffer(decl->getVertexSize(source), n, HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+        hwbuf->writeData(0, hwbuf->getSizeInBytes(), _normals.ptr(), true);
+        mesh->sharedVertexData->vertexBufferBinding->setBinding(source, hwbuf);
+    }
+    else
+    {
+        mat->setLightingEnabled(false);
+    }
+
+    // indices
+    if (!indices.empty())
+    {
+        Mat _indices = indices.getMat();
+
+        HardwareIndexBufferSharedPtr ibuf = HardwareBufferManager::getSingleton().createIndexBuffer(
+            HardwareIndexBuffer::IT_32BIT, indices.total(), HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+        ibuf->writeData(0, ibuf->getSizeInBytes(), _indices.ptr(), true);
+
+        sub->indexData->indexBuffer = ibuf;
+        sub->indexData->indexStart = 0;
+        sub->indexData->indexCount = indices.total();
+    }
+
+    AxisAlignedBox bounds(AxisAlignedBox::EXTENT_NULL);
+    for (int i = 0; i < n; i++)
+    {
+        Vec3f v = _vertices.at<Vec3f>(i);
+        bounds.merge(Vector3(v[0], v[1], v[2]));
+    }
+    mesh->_setBounds(bounds);
+}
+
+void createGridMesh(const String& name, const Size2f& size, const Size& segments)
+{
+    CV_Assert_N(_app, !segments.empty());
+
+    // material
+    MaterialPtr mat = MaterialManager::getSingleton().create(name, RESOURCEGROUP_NAME);
+    Pass* rpass = mat->getTechniques()[0]->getPasses()[0];
+    rpass->setEmissive(ColourValue::White);
+
+    // mesh
+    MeshPtr mesh = MeshManager::getSingleton().createManual(name, RESOURCEGROUP_NAME);
+    SubMesh* sub = mesh->createSubMesh();
+    sub->useSharedVertices = true;
+    sub->operationType = RenderOperation::OT_LINE_LIST;
+    sub->setMaterialName(name);
+
+    int n = (segments.width + 1) * 2 + (segments.height + 1) * 2;
+
+    mesh->sharedVertexData = new VertexData();
+    mesh->sharedVertexData->vertexCount = n;
+    VertexDeclaration* decl = mesh->sharedVertexData->vertexDeclaration;
+
+    // vertex data
+    HardwareBufferManager& hbm = HardwareBufferManager::getSingleton();
+
+    int source = 0;
+    HardwareVertexBufferSharedPtr hwbuf;
+    decl->addElement(source, 0, VET_FLOAT2, VES_POSITION);
+    hwbuf = hbm.createVertexBuffer(decl->getVertexSize(source), n, HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    mesh->sharedVertexData->vertexBufferBinding->setBinding(source, hwbuf);
+
+    Vector2 step = Vector2(size.width, size.height) / Vector2(segments.width, segments.height);
+
+    Vec2f* data = (Vec2f*)hwbuf->lock(HardwareBuffer::HBL_DISCARD);
+
+    for (int i = 0; i < segments.width + 1; i++)
+    {
+        data[i * 2] = Vec2f(-size.width / 2 + step.x * i, -size.height / 2);
+        data[i * 2 + 1] = Vec2f(-size.width / 2 + step.x * i, size.height / 2);
+    }
+
+    data += (segments.width + 1) * 2;
+
+    for (int i = 0; i < segments.height + 1; i++)
+    {
+        data[i * 2] = Vec2f(-size.width / 2, -size.height / 2 + step.y * i);
+        data[i * 2 + 1] = Vec2f(size.width / 2, -size.height / 2 + step.y * i);
+    }
+
+    hwbuf->unlock();
+
+    Vector3 sz(size.width, size.height, 0);
+    mesh->_setBounds(AxisAlignedBox(-sz/2, sz/2));
+}
+}
+}

modules/ovis/src/precomp.hpp

@@ -0,0 +1,25 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+#ifndef __OPENCV_PRECOMP_H__
+#define __OPENCV_PRECOMP_H__
+
+#include <opencv2/core.hpp>
+#include <opencv2/imgproc.hpp>
+#include "opencv2/ovis.hpp"
+#include "opencv2/opencv_modules.hpp"
+
+#include <Ogre.h>
+
+namespace cv {
+namespace ovis {
+struct Application;
+extern Ptr<Application> _app;
+
+extern const char* RESOURCEGROUP_NAME;
+void _createTexture(const String& name, Mat image);
+}
+}
+
+#endif