opencv-ruby 1.0

data/docs/getting-started.md

@@ -0,0 +1,236 @@
+# Getting Started
+
+## Following OpenCV Documentation
+
+The opencv-ruby API closely mirrors OpenCV's C++ API. This means:
+
+- **C++ tutorials work directly** - OpenCV's extensive [C++ tutorials](https://docs.opencv.org/4.x/d9/df8/tutorial_root.html) translate almost 1:1 to Ruby
+- **Python examples need adaptation** - OpenCV's Python API uses different conventions (NumPy arrays, different naming)
+
+When learning OpenCV with Ruby, we recommend following **C++ examples** rather than Python ones. See [C++ to Ruby](cpp-to-ruby.md) for the translation guide, or [Python to Ruby](python-to-ruby.md) if coming from Python.
+
+## Quick Reference
+
+For detailed type and naming mappings, see:
+
+- [C++ to Ruby](cpp-to-ruby.md) - Method naming, namespaces, enums, InputArray/OutputArray
+- [Python to Ruby](python-to-ruby.md) - Key differences from Python's cv2 module
+- [Type Mappings](type-mappings.md) - Complete C++ to Ruby type reference
+
+## Common Operations
+
+### Loading and Saving Images
+
+```ruby
+# Load a color image
+image = Cv.imread('photo.jpg', Cv::ImreadModes::IMREAD_COLOR)
+
+# Load as grayscale
+gray = Cv.imread('photo.jpg', Cv::ImreadModes::IMREAD_GRAYSCALE)
+
+# Save an image
+Cv.imwrite('output.png', image.input_array)
+
+# Save with options (JPEG quality)
+Cv.imwrite('output.jpg', image.input_array, [Cv::ImwriteFlags::IMWRITE_JPEG_QUALITY, 95])
+```
+
+### Color Conversion
+
+```ruby
+# BGR to Grayscale
+gray = Cv::Mat.new
+Cv.cvt_color(image.input_array, gray.output_array, Cv::ColorConversionCodes::COLOR_BGR2GRAY)
+
+# BGR to HSV
+hsv = Cv::Mat.new
+Cv.cvt_color(image.input_array, hsv.output_array, Cv::ColorConversionCodes::COLOR_BGR2HSV)
+```
+
+### Image Filtering
+
+```ruby
+# Gaussian blur
+blurred = image.gaussian_blur(Cv::Size.new(5, 5), 1.5)
+
+# Or using the module function
+blurred = Cv::Mat.new
+Cv.gaussian_blur(image.input_array, blurred.output_array, Cv::Size.new(5, 5), 1.5)
+
+# Bilateral filter (edge-preserving)
+filtered = image.bilateral_filter(9, 75, 75)
+
+# Median blur
+median = image.median_blur(5)
+```
+
+### Edge Detection
+
+```ruby
+# Canny edge detection
+edges = Cv::Mat.new
+Cv.canny(gray.input_array, edges.output_array, 50, 150)
+
+# Sobel derivatives
+sobel_x = Cv::Mat.new
+Cv.sobel(gray.input_array, sobel_x.output_array, CV_64F, 1, 0)
+```
+
+### Thresholding
+
+```ruby
+# Simple threshold
+binary = Cv::Mat.new
+Cv.threshold(gray.input_array, binary.output_array, 127, 255, Cv::ThresholdTypes::THRESH_BINARY)
+
+# Otsu's automatic thresholding
+_, binary = gray.threshold(0, 255, Cv::ThresholdTypes::THRESH_BINARY | Cv::ThresholdTypes::THRESH_OTSU)
+
+# Adaptive threshold
+adaptive = gray.adaptive_threshold(255,
+  Cv::AdaptiveThresholdTypes::ADAPTIVE_THRESH_GAUSSIAN_C,
+  Cv::ThresholdTypes::THRESH_BINARY, 11, 2)
+```
+
+### Drawing
+
+```ruby
+# Create a canvas
+canvas = Cv::Mat.new(400, 400, CV_8UC3, Cv::Scalar.new(255, 255, 255))
+
+# Draw a rectangle
+Cv.rectangle(canvas.input_output_array,
+  Cv::Point.new(50, 50), Cv::Point.new(150, 150),
+  Cv::Scalar.new(0, 0, 255), 2)
+
+# Draw a circle
+Cv.circle(canvas.input_output_array,
+  Cv::Point.new(200, 200), 50,
+  Cv::Scalar.new(0, 255, 0), -1)  # -1 = filled
+
+# Draw a line
+Cv.line(canvas.input_output_array,
+  Cv::Point.new(0, 0), Cv::Point.new(400, 400),
+  Cv::Scalar.new(255, 0, 0), 3)
+
+# Put text
+Cv.put_text(canvas.input_output_array, "Hello OpenCV!",
+  Cv::Point.new(50, 350),
+  Cv::HersheyFonts::FONT_HERSHEY_SIMPLEX, 1.0,
+  Cv::Scalar.new(0, 0, 0), 2)
+```
+
+### Finding Contours
+
+```ruby
+# Find contours
+contours, hierarchy = binary.find_contours(
+  Cv::RetrievalModes::RETR_EXTERNAL,
+  Cv::ContourApproximationModes::CHAIN_APPROX_SIMPLE)
+
+# Draw contours
+Cv.draw_contours(image.input_output_array, contours, -1, Cv::Scalar.new(0, 255, 0), 2)
+
+# Get contour area
+area = Cv.contour_area(Cv::InputArray.new(contours[0]))
+```
+
+### Feature Detection
+
+```ruby
+# Create ORB detector
+orb = Cv::ORB.create
+
+# Detect keypoints
+keypoints = Std::Vector≺cv꞉꞉KeyPoint≻.new
+orb.detect(gray.input_array, keypoints)
+
+# Compute descriptors
+descriptors = Cv::Mat.new
+orb.compute(gray.input_array, keypoints, descriptors.output_array)
+
+# Or detect and compute together
+keypoints = Std::Vector≺cv꞉꞉KeyPoint≻.new
+descriptors = Cv::Mat.new
+orb.detect_and_compute(gray.input_array, Cv::Mat.new.input_array, keypoints, descriptors.output_array)
+```
+
+### Video Capture
+
+```ruby
+# Open camera
+cap = Cv::VideoCapture.new(0)
+
+# Or open video file
+cap = Cv::VideoCapture.new('video.mp4')
+
+# Check if opened
+unless cap.opened?
+  puts "Failed to open video"
+  exit
+end
+
+# Read frames
+frame = Cv::Mat.new
+while cap.read(frame.output_array)
+  # Process frame...
+  break if frame.empty?
+end
+
+cap.release
+```
+
+## Displaying Images
+
+For GUI display, you can use OpenCV's HighGUI module:
+
+```ruby
+# Create a window
+Cv.named_window("Display", Cv::WindowFlags::WINDOW_AUTOSIZE)
+
+# Show image
+Cv.imshow("Display", image.input_array)
+
+# Wait for key press (0 = indefinitely)
+Cv.wait_key(0)
+
+# Destroy window
+Cv.destroy_all_windows
+```
+
+### Face Detection
+
+A sample to detect faces from an image.
+
+```ruby
+require 'opencv'
+include OpenCV
+
+if ARGV.length < 2
+  puts "Usage: ruby #{__FILE__} source dest"
+  exit
+end
+
+data = './data/haarcascades/haarcascade_frontalface_alt.xml'
+detector = CvHaarClassifierCascade::load(data)
+image = CvMat.load(ARGV[0])
+detector.detect_objects(image).each do |region|
+  color = CvColor::Blue
+  image.rectangle! region.top_left, region.bottom_right, :color => color
+end
+
+image.save_image(ARGV[1])
+window = GUI::Window.new('Face detection')
+window.show(image)
+GUI::wait_key
+```
+
+## Where to Learn More
+
+- **Test Suite** - The `test/` folder contains Ruby examples for almost every API. These are excellent references for real-world usage patterns.
+- [C++ to Ruby](cpp-to-ruby.md) - Translation guide for C++ code
+- [Python to Ruby](python-to-ruby.md) - Guide for Python OpenCV users
+- [Type Mappings](type-mappings.md) - Complete type reference
+- [OpenCV C++ Tutorials](https://docs.opencv.org/4.x/d9/df8/tutorial_root.html) - Primary learning resource
+- [OpenCV API Reference](https://docs.opencv.org/4.x/) - Detailed function documentation
+- [API Reference](api/Cv/index.md) - Ruby-specific API documentation

data/docs/index.md

@@ -0,0 +1,71 @@
+# OpenCV Ruby
+
+Modern Ruby bindings for [OpenCV](https://opencv.org/) 4.x based on its C++ API.
+
+## Overview
+
+**opencv-ruby** provides comprehensive Ruby bindings for OpenCV, the world's most popular open-source computer vision library. Unlike previous Ruby OpenCV bindings, this library:
+
+- Exposes almost all of OpenCV's C++ API (excluding CUDA)
+- Uses [Rice](https://github.com/ruby-rice/rice) for clean, modern C++ to Ruby bindings
+- Requires Ruby 3.2+ and OpenCV 4.x
+- Provides 1,600+ classes, enums, and modules
+
+To give you an overview of the completness of the bindings, opencv-ruby includes:
+
+| Type             | Count   |
+|------------------|---------|
+| Classes          | 1,058   |
+| Methods          | 3,145   |
+| Module functions | 4,006   |
+| Constructors     | 1,359   |
+| Attributes       | 913     |
+| Enums            | 160     |
+
+
+## Key Features
+
+- **Core Operations**: Matrix operations, arithmetic, linear algebra
+- **Image Processing**: Filtering, morphology, color conversion, geometric transforms
+- **Feature Detection**: SIFT, ORB, AKAZE, BRISK, and more
+- **Object Detection**: Cascade classifiers, HOG descriptors, ArUco markers
+- **Machine Learning**: SVM, decision trees, neural networks, k-means
+- **Deep Neural Networks**: Load and run models from TensorFlow, PyTorch, ONNX, Caffe
+- **Video Processing**: Optical flow, background subtraction, video I/O
+- **Camera Calibration**: Intrinsic/extrinsic calibration, stereo vision, pose estimation
+- **Image Stitching**: Panorama creation with exposure compensation and seam finding
+
+## Quick Example
+
+```ruby
+require 'opencv-ruby'
+
+# Load an image
+image = Cv.imread('photo.jpg', Cv::ImreadModes::IMREAD_COLOR)
+
+# Convert to grayscale
+gray = Cv::Mat.new
+Cv.cvt_color(image.input_array, gray.output_array, Cv::ColorConversionCodes::COLOR_BGR2GRAY)
+
+# Apply Gaussian blur
+blurred = gray.gaussian_blur(Cv::Size.new(5, 5), 1.5)
+
+# Detect edges with Canny
+edges = Cv::Mat.new
+Cv.canny(blurred.input_array, edges.output_array, 50, 150)
+
+# Save the result
+Cv.imwrite('edges.jpg', edges.input_array)
+```
+
+## Documentation Approach
+
+This documentation focuses on Ruby-specific usage patterns and getting started guides. For detailed information about OpenCV algorithms and parameters, we link directly to the official [OpenCV documentation](https://docs.opencv.org/4.x/).
+
+The Ruby API closely mirrors the C++ API, so OpenCV's C++ documentation and tutorials are directly applicable. See the [Getting Started](getting-started.md) guide for tips on translating C++ examples to Ruby.
+
+## Project Links
+
+- **Source Code**: [github.com/cfis/opencv-ruby](https://github.com/cfis/opencv-ruby)
+- **OpenCV Documentation**: [docs.opencv.org](https://docs.opencv.org/4.x/)
+- **Rice (C++ Bindings)**: [github.com/ruby-rice/rice](https://github.com/ruby-rice/rice)

data/docs/installation.md

@@ -0,0 +1,77 @@
+# Installation
+
+## Prerequisites
+
+OpenCV is a large, complex C++ code base that makes heavy use of templates. Therefore, to build the Ruby bindings you will need a machine that has at least 32GB of memory, a decent amount of disk space and an up-to-date-date C++ compiler (C++17 or higher). Expect compile times to range from 5 minutes on the latest Macs to 30 minutes for relatively new x86 laptops. Older hardware will of course be slower and compile times vary greatly by compiler (MSVC and Clang are much faster than gcc).
+
+## Installing OpenCV
+
+### macOS
+
+On a MacBook Pro M4, it will take about 10 minutes to build the extension. It will be approximately 170MB.
+
+You will first need to install [HomeBrew](https://brew.sh/)
+
+Then:
+
+```bash
+brew install libffi opencv
+gem install opencv-ruby --preset macos-release
+```
+
+### Fedora
+
+On a Meteor Lake (Intel Core Ultra 7 165U) laptop with 64GB memory, it will take about 30 minutes to build the extension with g++. The extension will be roughly 200MB. Note that g++ uses *a lot* of memory, with some processes taking up to 17GB of memory. At most 6 concurrent g++ instances can at once with 64GB. If you have a machine with 32GB of memory you will need to reduce the number of concurrent jobs. Do this by overriding the setting in the CMakePresets.json file.
+
+```bash
+sudo apt-get install libffi-devel opencv
+gem install opencv-ruby --preset linux-release
+```
+
+### Ubuntu/Debian
+
+```bash
+sudo apt-get install libffi-dev libopencv-dev
+gem install opencv-ruby --preset linux-release
+```
+
+### Windows (RubyInstaller + DevKit)
+
+Most Ruby developers on Windows use the [RubyInstaller](https://rubyinstaller.org/) which installs a MSYS2/Mingw64 environment. On a Meteor Lake (Intel Core Ultra 7 165U) laptop with 64GB memory, it will take about 30 minutes to build the extension with g++. The size will be about 200MB.
+
+```bash
+  pacman -S mingw-w64-ucrt-x86_64-opencv mingw-w64-ucrt-x86_64-qt6-base mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-libffi
+  gem install opencv-ruby --preset mingw-release
+```
+
+You MUST install qt6-base because the OpenCV highgui module is built with it. However, it is not listed as dependency so you have to install it manually.
+
+### Windows Visual Studio (MSVC)
+
+You can also use Visual Studio on Windows in combination with vcpkg. On a Meteor Lake (Intel Core Ultra 7 165U) laptop with 64GB memory, it will take about 30 minutes to build the extension. It will be 70MB.
+
+After installing Visual Studio and vcpkg, install the gem like this:
+
+```bash
+gem install opencv-ruby --preset msvc-release
+```
+
+Notice you don't have to install any dependencies first. This is because the build system uses vcpkg in manifest mode, which will download and build all dependencies like libffi and OpenCV. The first time you do this, it can take quite a while, up to an hour (it is a one time cost).
+
+This has been tested with Visual Studio 2022 and 2026, with Visual Studio 2026 being strongly preferred (it is quite a bit faster). 
+
+## Verifying Installation
+
+To test that the installation was successful:
+
+```ruby
+require 'opencv-ruby'
+
+# Check OpenCV version
+puts Cv.get_version_string
+# => "4.10.0" (or your installed version)
+
+# Create a simple matrix
+mat = Cv::Mat.new(3, 3, CV_8UC1, Cv::Scalar.new(255))
+puts "Created #{mat.rows}x#{mat.cols} matrix"
+```

data/docs/python-to-ruby.md

@@ -0,0 +1,332 @@
+# Python to Ruby Translation
+
+Many developers learn OpenCV through Python. While opencv-ruby can accomplish the same tasks, there are significant differences because **opencv-ruby wraps the C++ API directly**, whereas **Python's cv2 module has its own conventions**.
+
+## Key Differences
+
+| Aspect | Python (cv2) | Ruby (opencv-ruby) |
+|--------|--------------|-------------------|
+| **Array type** | NumPy `ndarray` | `Cv::Mat` |
+| **Function style** | `cv2.function()` | `Cv.function()` or `mat.method()` |
+| **Output handling** | Returns result | Often uses `output_array` parameter |
+| **Enums** | Integer constants | Enum classes |
+| **Memory** | NumPy manages | Ruby GC manages |
+
+**Important**: The differences between Python and Ruby are larger than between C++ and Ruby. When possible, refer to C++ documentation and the [C++ to Ruby](cpp-to-ruby.md) guide.
+
+## NumPy Arrays vs Cv::Mat
+
+The biggest difference is data representation.
+
+### Python: NumPy Arrays
+
+```python
+# Python - uses NumPy ndarrays
+import cv2
+import numpy as np
+
+# Images are NumPy arrays
+image = cv2.imread("photo.jpg")
+print(type(image))  # <class 'numpy.ndarray'>
+print(image.shape)  # (480, 640, 3)
+
+# Create arrays with NumPy
+zeros = np.zeros((480, 640), dtype=np.uint8)
+ones = np.ones((480, 640, 3), dtype=np.uint8) * 255
+
+# Direct pixel access via NumPy indexing
+pixel = image[100, 200]  # BGR tuple
+image[100, 200] = [255, 0, 0]  # Set pixel
+```
+
+### Ruby: Cv::Mat
+
+```ruby
+# Ruby - uses Cv::Mat objects
+require 'opencv-ruby'
+
+# Images are Mat objects
+image = Cv.imread("photo.jpg")
+puts image.class  # Cv::Mat
+puts "#{image.rows}x#{image.cols}"  # 480x640
+
+# Create matrices with Mat methods
+zeros = Cv::Mat.zeros(480, 640, CV_8UC1).to_mat
+ones = Cv::Mat.new(480, 640, CV_8UC3, Cv::Scalar.new(255, 255, 255))
+
+# Pixel access via Mat indexing
+pixel = image[100, 200]  # Returns Vec3b
+image[100, 200] = Cv::Vec3b.new(255, 0, 0)  # Set pixel
+```
+
+## Function Calling Conventions
+
+### Python: Returns Results Directly
+
+```python
+# Python - functions return results
+gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+blurred = cv2.GaussianBlur(gray, (5, 5), 1.5)
+edges = cv2.Canny(blurred, 50, 150)
+```
+
+### Ruby: Uses Input/Output Arrays
+
+```ruby
+# Ruby - often uses explicit output arrays
+gray = Cv::Mat.new
+Cv.cvt_color(image.input_array, gray.output_array, Cv::ColorConversionCodes::COLOR_BGR2GRAY)
+
+blurred = Cv::Mat.new
+Cv.gaussian_blur(gray.input_array, blurred.output_array, Cv::Size.new(5, 5), 1.5)
+
+edges = Cv::Mat.new
+Cv.canny(blurred.input_array, edges.output_array, 50, 150)
+
+# Many methods also have convenience versions
+blurred = gray.gaussian_blur(Cv::Size.new(5, 5), 1.5)
+```
+
+## Enums and Constants
+
+### Python: Integer Constants
+
+```python
+# Python - bare integer constants
+gray = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
+_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
+resized = cv2.resize(image, (320, 240), interpolation=cv2.INTER_LINEAR)
+```
+
+### Ruby: Enum Classes
+
+```ruby
+# Ruby - enum classes with namespacing
+gray = Cv.imread("photo.jpg", Cv::ImreadModes::IMREAD_GRAYSCALE)
+
+binary = Cv::Mat.new
+Cv.threshold(gray.input_array, binary.output_array, 127, 255, Cv::ThresholdTypes::THRESH_BINARY)
+
+resized = Cv::Mat.new
+Cv.resize(image.input_array, resized.output_array, Cv::Size.new(320, 240), 0, 0,
+          Cv::InterpolationFlags::INTER_LINEAR)
+```
+
+## Common Operations Comparison
+
+### Reading and Writing Images
+
+```python
+# Python
+image = cv2.imread("input.jpg")
+cv2.imwrite("output.png", image)
+
+# With flags
+gray = cv2.imread("input.jpg", cv2.IMREAD_GRAYSCALE)
+cv2.imwrite("output.jpg", image, [cv2.IMWRITE_JPEG_QUALITY, 95])
+```
+
+```ruby
+# Ruby
+image = Cv.imread("input.jpg")
+Cv.imwrite("output.png", image.input_array)
+
+# With flags
+gray = Cv.imread("input.jpg", Cv::ImreadModes::IMREAD_GRAYSCALE)
+Cv.imwrite("output.jpg", image.input_array, [Cv::ImwriteFlags::IMWRITE_JPEG_QUALITY, 95])
+```
+
+### Color Conversion
+
+```python
+# Python
+gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+```
+
+```ruby
+# Ruby
+gray = Cv::Mat.new
+Cv.cvt_color(image.input_array, gray.output_array, Cv::ColorConversionCodes::COLOR_BGR2GRAY)
+
+hsv = Cv::Mat.new
+Cv.cvt_color(image.input_array, hsv.output_array, Cv::ColorConversionCodes::COLOR_BGR2HSV)
+```
+
+### Drawing
+
+```python
+# Python
+cv2.rectangle(image, (50, 50), (150, 150), (0, 0, 255), 2)
+cv2.circle(image, (200, 200), 50, (0, 255, 0), -1)
+cv2.line(image, (0, 0), (400, 400), (255, 0, 0), 3)
+cv2.putText(image, "Hello", (50, 350), cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 0, 0), 2)
+```
+
+```ruby
+# Ruby
+Cv.rectangle(image.input_output_array,
+  Cv::Point.new(50, 50), Cv::Point.new(150, 150),
+  Cv::Scalar.new(0, 0, 255), 2)
+
+Cv.circle(image.input_output_array,
+  Cv::Point.new(200, 200), 50,
+  Cv::Scalar.new(0, 255, 0), -1)
+
+Cv.line(image.input_output_array,
+  Cv::Point.new(0, 0), Cv::Point.new(400, 400),
+  Cv::Scalar.new(255, 0, 0), 3)
+
+Cv.put_text(image.input_output_array, "Hello",
+  Cv::Point.new(50, 350),
+  Cv::HersheyFonts::FONT_HERSHEY_SIMPLEX, 1.0,
+  Cv::Scalar.new(0, 0, 0), 2)
+```
+
+### Thresholding
+
+```python
+# Python - returns tuple (threshold_value, result)
+_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
+_, otsu = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+adaptive = cv2.adaptiveThreshold(gray, 255,
+    cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2)
+```
+
+```ruby
+# Ruby
+binary = Cv::Mat.new
+Cv.threshold(gray.input_array, binary.output_array, 127, 255, Cv::ThresholdTypes::THRESH_BINARY)
+
+otsu = Cv::Mat.new
+Cv.threshold(gray.input_array, otsu.output_array, 0, 255,
+  Cv::ThresholdTypes::THRESH_BINARY | Cv::ThresholdTypes::THRESH_OTSU)
+
+adaptive = gray.adaptive_threshold(255,
+  Cv::AdaptiveThresholdTypes::ADAPTIVE_THRESH_GAUSSIAN_C,
+  Cv::ThresholdTypes::THRESH_BINARY, 11, 2)
+```
+
+### Contours
+
+```python
+# Python
+contours, hierarchy = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+cv2.drawContours(image, contours, -1, (0, 255, 0), 2)
+
+for contour in contours:
+    area = cv2.contourArea(contour)
+    x, y, w, h = cv2.boundingRect(contour)
+```
+
+```ruby
+# Ruby
+contours, hierarchy = binary.find_contours(
+  Cv::RetrievalModes::RETR_EXTERNAL,
+  Cv::ContourApproximationModes::CHAIN_APPROX_SIMPLE)
+
+Cv.draw_contours(image.input_output_array, contours, -1, Cv::Scalar.new(0, 255, 0), 2)
+
+contours.each do |contour|
+  area = Cv.contour_area(Cv::InputArray.new(contour))
+  rect = Cv.bounding_rect(Cv::InputArray.new(contour))
+  x, y, w, h = rect.x, rect.y, rect.width, rect.height
+end
+```
+
+### Feature Detection
+
+```python
+# Python
+orb = cv2.ORB_create()
+keypoints = orb.detect(gray, None)
+keypoints, descriptors = orb.detectAndCompute(gray, None)
+
+# Draw keypoints
+output = cv2.drawKeypoints(gray, keypoints, None)
+```
+
+```ruby
+# Ruby
+orb = Cv::ORB.create
+keypoints = Std::Vector≺cv꞉꞉KeyPoint≻.new
+orb.detect(gray.input_array, keypoints)
+
+keypoints = Std::Vector≺cv꞉꞉KeyPoint≻.new
+descriptors = Cv::Mat.new
+orb.detect_and_compute(gray.input_array, Cv::Mat.new.input_array, keypoints, descriptors.output_array)
+
+# Draw keypoints
+output = Cv::Mat.new
+Cv.draw_keypoints(gray.input_array, keypoints, output.output_array)
+```
+
+### Video Capture
+
+```python
+# Python
+cap = cv2.VideoCapture(0)
+
+while True:
+    ret, frame = cap.read()
+    if not ret:
+        break
+
+    # Process frame...
+
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
+
+cap.release()
+```
+
+```ruby
+# Ruby
+cap = Cv::VideoCapture.new(0)
+
+frame = Cv::Mat.new
+while cap.read(frame.output_array)
+  break if frame.empty?
+
+  # Process frame...
+
+  break if Cv.wait_key(1) == 'q'.ord
+end
+
+cap.release
+```
+
+## Python Convenience vs Ruby Explicitness
+
+Python's OpenCV bindings include many conveniences that Ruby doesn't have:
+
+| Python Convenience | Ruby Equivalent |
+|-------------------|-----------------|
+| `image.shape` | `[image.rows, image.cols, image.channels]` |
+| `image.dtype` | `image.type` or `image.depth` |
+| `image.copy()` | `image.clone` |
+| `image[y, x]` | `image[y, x]` (similar) |
+| `image[y1:y2, x1:x2]` (slicing) | `image.row_range(...).col_range(...)` |
+| NumPy broadcasting | Manual loops or OpenCV functions |
+| `np.array([...])` | `Cv::Mat.new(...)` with data |
+
+## Tips for Python Users
+
+1. **Always create output Mats**: Unlike Python where functions return results, Ruby often requires pre-creating output matrices.
+
+2. **Use `.input_array` and `.output_array`**: These are required for most OpenCV functions in Ruby.
+
+3. **Enum names are longer**: `cv2.THRESH_BINARY` becomes `Cv::ThresholdTypes::THRESH_BINARY`.
+
+4. **Check the tests**: The `test/` folder has Ruby examples for almost every API.
+
+5. **Refer to C++ docs**: Since Ruby wraps C++ directly, C++ documentation is more accurate than Python docs.
+
+6. **Type conversions differ**: No automatic NumPy ↔ list conversion; use explicit `Std::Vector≺T≻` types.
+
+## See Also
+
+- [C++ to Ruby](cpp-to-ruby.md) - More direct translation guide (recommended)
+- [Type Mappings](type-mappings.md) - Complete type reference
+- [Getting Started](getting-started.md) - Common operations with examples