opencv-ruby 1.0

data/docs/rice-doc.yaml

@@ -0,0 +1,152 @@
+# Paths are relative to this file
+extension: ../lib/3.4/opencv_ruby.so
+output: ./api
+
+# Note: Ruby core types are automatically linked to docs.ruby-lang.org
+
+namespaces:
+  Std:
+    resolver: cppreference
+
+  Rice:
+    resolver: rice
+
+  Cv:
+    resolver: doxygen
+    root: https://docs.opencv.org/4.x
+    tagfile: https://docs.opencv.org/4.x/opencv.tag
+
+    type_mappings:
+      - pattern: "^enum\\s*"
+        replacement: ""
+      - pattern: "^union\\s*"
+        replacement: ""
+      - pattern: "<.*>"
+        replacement: ""
+      - pattern: "::debug_build_guard"
+        replacement: ""
+
+    method_mappings:
+      Cv:
+        agast: AGAST
+        approx_poly_dp: approxPolyDP
+        calc_optical_flow_pyr_lk: calcOpticalFlowPyrLK
+        calibrate_camera_ro: calibrateCameraRO
+        cam_shift: CamShift
+        compose_rt: composeRT
+        compute_ecc: computeECC
+        create_clahe: createCLAHE
+        current_ui_framework: currentUIFramework
+        create_align_mtb: createAlignMTB
+        create_background_subtractor_knn: createBackgroundSubtractorKNN
+        create_background_subtractor_mog2: createBackgroundSubtractorMOG2
+        denoise_tvl1: denoise_TVL1
+        emd: EMD
+        estimate_affine_2d: estimateAffine2D
+        estimate_affine_partial_2d: estimateAffinePartial2D
+        fast: FAST
+        filter_2d: filter2D
+        find_chessboard_corners_sb?: findChessboardCornersSB
+        find_transform_ecc: findTransformECC
+        fit_ellipse_ams: fitEllipseAMS
+        flip_nd: flipND
+        gaussian_blur: GaussianBlur
+        get_cpu_features_line: getCPUFeaturesLine
+        get_cpu_tick_count: getCPUTickCount
+        get_number_of_cp_us: getNumberOfCPUs
+        get_optimal_dft_size: getOptimalDFTSize
+        get_rotation_matrix_2d: getRotationMatrix2D
+        get_valid_disparity_roi: getValidDisparityROI
+        group_rectangles_meanshift: groupRectangles_meanshift
+        have_open_vx?: haveOpenVX
+        hough_circles: HoughCircles
+        hough_lines: HoughLines
+        hough_lines_p: HoughLinesP
+        hough_lines_point_set: HoughLinesPointSet
+        hu_moments: HuMoments
+        init_camera_matrix_2d: initCameraMatrix2D
+        lu: LU
+        lut: LUT
+        pca_back_project: PCABackProject
+        pca_compute: PCACompute
+        pca_project: PCAProject
+        psnr: PSNR
+        rq_decomp3x3: RQDecomp3x3
+        select_roi: selectROI
+        sep_filter_2d: sepFilter2D
+        set_rng_seed: setRNGSeed
+        set_use_open_vx: setUseOpenVX
+        solve_lp: solveLP
+        solve_pn_p_refine_lm: solvePnPRefineLM
+        solve_pn_p_refine_vvs: solvePnPRefineVVS
+        sv_back_subst: SVBackSubst
+        sv_decomp: SVDecomp
+        the_rng: theRNG
+        transpose_nd: transposeND
+        use_open_vx?: useOpenVX
+        wrapper_emd: wrapperEMD
+
+      Cv::AsyncArray:
+        _get_impl: _getImpl
+        wait_for?: wait_for
+
+      Cv::BackgroundSubtractorKNN:
+        getk_nn_samples: getkNNSamples
+        setk_nn_samples: setkNNSamples
+
+      Cv::Cuda::DeviceInfo:
+        device_id: deviceID
+        ecc_enabled?: ECCEnabled
+        max_surface_2d: maxSurface2D
+        max_texture_2d: maxTexture2D
+        pci_bus_id: pciBusID
+        pci_device_id: pciDeviceID
+        pci_domain_id: pciDomainID
+
+      Cv::Cuda::GpuMat:
+        adjust_roi: adjustROI
+        locate_roi: locateROI
+
+      Cv::Cuda::GpuMatND:
+        to_gpu_mat: operator GpuMat
+
+      Cv::FaceDetectorYN:
+        get_nms_threshold: getNMSThreshold
+
+      Cv::FaceRecognizerSF:
+        set_nms_threshold: setNMSThreshold
+
+      Cv::HOGDescriptor:
+        detect_multi_scale_roi: detectMultiScaleROI
+        detect_roi: detectROI
+
+      Cv::HOGDescriptor::DescriptorStorageFormat:
+        set_svm_detector: setSVMDetector
+
+      Cv::Hfloat:
+        to_float: operator float
+
+      Cv::Mat:
+        locate_roi: locateROI
+
+      Cv::Ml::ANN_MLP:
+        get_rprop_dw0: getRpropDW0
+        get_rprop_dw_max: getRpropDWMax
+        get_rprop_dw_min: getRpropDWMin
+        get_rprop_dw_minus: getRpropDWMinus
+        get_rprop_dw_plus: getRpropDWPlus
+        set_anneal_energy_rng: setAnnealEnergyRNG
+        set_rprop_dw0: setRpropDW0
+        set_rprop_dw_max: setRpropDWMax
+        set_rprop_dw_min: setRpropDWMin
+        set_rprop_dw_minus: setRpropDWMinus
+        set_rprop_dw_plus: setRpropDWPlus
+
+      Cv::Ml::DTrees:
+        get_cv_folds: getCVFolds
+        get_use1_se_rule?: getUse1SERule
+        set_cv_folds: setCVFolds
+        set_use1_se_rule: setUse1SERule
+
+      Cv::Ml::RTrees:
+        get_oob_error: getOOBError

data/docs/type-mappings.md

@@ -0,0 +1,235 @@
+# Type Mappings
+
+This page documents how C++ OpenCV types map to Ruby classes.
+
+## Basic Types
+
+| C++ | Ruby | Description |
+|-----|------|-------------|
+| `cv::Mat` | `Cv::Mat` | N-dimensional dense array (images, matrices) |
+| `cv::Scalar` | `Cv::Scalar` | 4-element vector (colors, values) |
+| `cv::Point` | `Cv::Point` | 2D integer point |
+| `cv::Point2f` | `Cv::Point2f` | 2D float point |
+| `cv::Point2d` | `Cv::Point2d` | 2D double point |
+| `cv::Point3i` | `Cv::Point3i` | 3D integer point |
+| `cv::Point3f` | `Cv::Point3f` | 3D float point |
+| `cv::Point3d` | `Cv::Point3d` | 3D double point |
+| `cv::Size` | `Cv::Size` | 2D integer size (width, height) |
+| `cv::Size2f` | `Cv::Size2f` | 2D float size |
+| `cv::Size2d` | `Cv::Size2d` | 2D double size |
+| `cv::Rect` | `Cv::Rect` | Integer rectangle (x, y, width, height) |
+| `cv::Rect2f` | `Cv::Rect2f` | Float rectangle |
+| `cv::Rect2d` | `Cv::Rect2d` | Double rectangle |
+| `cv::Range` | `Cv::Range` | Integer range (start, end) |
+| `cv::RotatedRect` | `Cv::RotatedRect` | Rotated rectangle |
+| `cv::TermCriteria` | `Cv::TermCriteria` | Termination criteria for iterative algorithms |
+| `cv::Moments` | `Cv::Moments` | Image moments |
+
+## Vector Types
+
+Small fixed-size vectors:
+
+| C++ | Ruby | Description |
+|-----|------|-------------|
+| `cv::Vec2b` | `Cv::Vec2b` | 2 unsigned chars |
+| `cv::Vec3b` | `Cv::Vec3b` | 3 unsigned chars (BGR pixel) |
+| `cv::Vec4b` | `Cv::Vec4b` | 4 unsigned chars (BGRA pixel) |
+| `cv::Vec2s` | `Cv::Vec2s` | 2 shorts |
+| `cv::Vec3s` | `Cv::Vec3s` | 3 shorts |
+| `cv::Vec4s` | `Cv::Vec4s` | 4 shorts |
+| `cv::Vec2i` | `Cv::Vec2i` | 2 integers |
+| `cv::Vec3i` | `Cv::Vec3i` | 3 integers |
+| `cv::Vec4i` | `Cv::Vec4i` | 4 integers |
+| `cv::Vec6i` | `Cv::Vec6i` | 6 integers |
+| `cv::Vec8i` | `Cv::Vec8i` | 8 integers |
+| `cv::Vec2f` | `Cv::Vec2f` | 2 floats |
+| `cv::Vec3f` | `Cv::Vec3f` | 3 floats |
+| `cv::Vec4f` | `Cv::Vec4f` | 4 floats |
+| `cv::Vec6f` | `Cv::Vec6f` | 6 floats |
+| `cv::Vec2d` | `Cv::Vec2d` | 2 doubles |
+| `cv::Vec3d` | `Cv::Vec3d` | 3 doubles |
+| `cv::Vec4d` | `Cv::Vec4d` | 4 doubles |
+
+## Typed Matrix Classes
+
+Type-safe matrix templates:
+
+| C++ | Ruby | Element Type |
+|-----|------|--------------|
+| `cv::Mat1b` | `Cv::Mat1b` | 1-channel unsigned char |
+| `cv::Mat1s` | `Cv::Mat1s` | 1-channel short |
+| `cv::Mat1w` | `Cv::Mat1w` | 1-channel unsigned short |
+| `cv::Mat1i` | `Cv::Mat1i` | 1-channel int |
+| `cv::Mat1f` | `Cv::Mat1f` | 1-channel float |
+| `cv::Mat1d` | `Cv::Mat1d` | 1-channel double |
+| `cv::Mat2b` | `Cv::Mat2b` | 2-channel unsigned char |
+| `cv::Mat3b` | `Cv::Mat3b` | 3-channel unsigned char (BGR image) |
+| `cv::Mat4b` | `Cv::Mat4b` | 4-channel unsigned char (BGRA image) |
+| `cv::Mat3f` | `Cv::Mat3f` | 3-channel float |
+| ... | ... | (all combinations available) |
+
+## Matrix Type Constants
+
+Global constants for `Mat` type specification:
+
+| Constant | Meaning |
+|----------|---------|
+| `CV_8UC1` | 8-bit unsigned, 1 channel |
+| `CV_8UC3` | 8-bit unsigned, 3 channels |
+| `CV_8UC4` | 8-bit unsigned, 4 channels |
+| `CV_8SC1` | 8-bit signed, 1 channel |
+| `CV_16UC1` | 16-bit unsigned, 1 channel |
+| `CV_16SC1` | 16-bit signed, 1 channel |
+| `CV_32SC1` | 32-bit signed integer, 1 channel |
+| `CV_32FC1` | 32-bit float, 1 channel |
+| `CV_32FC2` | 32-bit float, 2 channels |
+| `CV_64FC1` | 64-bit float (double), 1 channel |
+
+Pattern: `CV_{depth}{signed}{channels}` where:
+- Depth: 8, 16, 32, 64
+- Signed: U (unsigned), S (signed), F (float)
+- Channels: C1, C2, C3, C4
+
+## STL Container Mappings
+
+C++ STL containers map to Ruby `Std::` classes:
+
+| C++ | Ruby |
+|-----|------|
+| `std::vector<cv::Mat>` | `Std::Vector≺cv꞉꞉Mat≻` |
+| `std::vector<cv::Point>` | `Std::Vector≺cv꞉꞉Point_≺int≻≻` |
+| `std::vector<cv::Point2f>` | `Std::Vector≺cv꞉꞉Point_≺float≻≻` |
+| `std::vector<cv::KeyPoint>` | `Std::Vector≺cv꞉꞉KeyPoint≻` |
+| `std::vector<cv::DMatch>` | `Std::Vector≺cv꞉꞉DMatch≻` |
+| `std::vector<cv::Rect>` | `Std::Vector≺cv꞉꞉Rect_≺int≻≻` |
+| `std::vector<int>` | `Std::Vector≺int≻` |
+| `std::vector<float>` | `Std::Vector≺float≻` |
+| `std::vector<double>` | `Std::Vector≺double≻` |
+| `std::vector<uchar>` | `Std::Vector≺unsigned char≻` |
+| `std::vector<std::vector<cv::Point>>` | `Std::Vector≺vector≺cv꞉꞉Point_≺int≻≻≻` |
+| `std::string` | Ruby `String` (automatic conversion) |
+
+Note: Ruby uses special Unicode characters (`≺`, `≻`, `꞉꞉`) in type names.
+
+## Input/Output Array Types
+
+| C++ | Ruby Method | Purpose |
+|-----|-------------|---------|
+| `cv::InputArray` | `mat.input_array` | Read-only input |
+| `cv::OutputArray` | `mat.output_array` | Write-only output |
+| `cv::InputOutputArray` | `mat.input_output_array` | Read-write |
+
+## Smart Pointers
+
+| C++ | Ruby |
+|-----|------|
+| `cv::Ptr<T>` | `Cv::Ptr≺T≻` or just the class |
+| `std::shared_ptr<T>` | `Std::SharedPtr≺T≻` |
+
+Most factory methods return smart pointers that Ruby handles automatically:
+
+```ruby
+# These work equivalently
+orb = Cv::ORB.create        # Returns Ptr<ORB>, usable directly
+sift = Cv::SIFT.create(500) # Returns Ptr<SIFT>
+```
+
+## Feature Detection Types
+
+| C++ | Ruby |
+|-----|------|
+| `cv::KeyPoint` | `Cv::KeyPoint` |
+| `cv::DMatch` | `Cv::DMatch` |
+| `cv::Feature2D` | `Cv::Feature2D` |
+| `cv::DescriptorMatcher` | `Cv::DescriptorMatcher` |
+
+## Algorithm Classes
+
+| C++ | Ruby |
+|-----|------|
+| `cv::Algorithm` | `Cv::Algorithm` |
+| `cv::ORB` | `Cv::ORB` |
+| `cv::SIFT` | `Cv::SIFT` |
+| `cv::AKAZE` | `Cv::AKAZE` |
+| `cv::BRISK` | `Cv::BRISK` |
+| `cv::KAZE` | `Cv::KAZE` |
+| `cv::CascadeClassifier` | `Cv::CascadeClassifier` |
+| `cv::HOGDescriptor` | `Cv::HOGDescriptor` |
+| `cv::BackgroundSubtractorMOG2` | `Cv::BackgroundSubtractorMOG2` |
+| `cv::BackgroundSubtractorKNN` | `Cv::BackgroundSubtractorKNN` |
+
+## DNN Types
+
+| C++ | Ruby |
+|-----|------|
+| `cv::dnn::Net` | `Cv::Dnn::Net` |
+| `cv::dnn::Layer` | `Cv::Dnn::Layer` |
+| `cv::dnn::Model` | `Cv::Dnn::Model` |
+| `cv::dnn::ClassificationModel` | `Cv::Dnn::ClassificationModel` |
+| `cv::dnn::DetectionModel` | `Cv::Dnn::DetectionModel` |
+
+## Machine Learning Types
+
+| C++ | Ruby |
+|-----|------|
+| `cv::ml::StatModel` | `Cv::Ml::StatModel` |
+| `cv::ml::SVM` | `Cv::Ml::SVM` |
+| `cv::ml::DTrees` | `Cv::Ml::DTrees` |
+| `cv::ml::RTrees` | `Cv::Ml::RTrees` |
+| `cv::ml::Boost` | `Cv::Ml::Boost` |
+| `cv::ml::KNearest` | `Cv::Ml::KNearest` |
+| `cv::ml::ANN_MLP` | `Cv::Ml::ANN_MLP` |
+| `cv::ml::TrainData` | `Cv::Ml::TrainData` |
+
+## Video Types
+
+| C++ | Ruby |
+|-----|------|
+| `cv::VideoCapture` | `Cv::VideoCapture` |
+| `cv::VideoWriter` | `Cv::VideoWriter` |
+| `cv::Tracker` | `Cv::Tracker` |
+| `cv::TrackerMIL` | `Cv::TrackerMIL` |
+
+## Enum Naming Pattern
+
+C++ enums map to Ruby enum classes:
+
+| C++ | Ruby |
+|-----|------|
+| `cv::IMREAD_*` | `Cv::ImreadModes::IMREAD_*` |
+| `cv::IMWRITE_*` | `Cv::ImwriteFlags::IMWRITE_*` |
+| `cv::COLOR_*` | `Cv::ColorConversionCodes::COLOR_*` |
+| `cv::THRESH_*` | `Cv::ThresholdTypes::THRESH_*` |
+| `cv::MORPH_*` | `Cv::MorphTypes::MORPH_*` |
+| `cv::BORDER_*` | `Cv::BorderTypes::BORDER_*` |
+| `cv::INTER_*` | `Cv::InterpolationFlags::INTER_*` |
+| `cv::RETR_*` | `Cv::RetrievalModes::RETR_*` |
+| `cv::CHAIN_APPROX_*` | `Cv::ContourApproximationModes::CHAIN_APPROX_*` |
+| `cv::LINE_*` | `Cv::LineTypes::LINE_*` |
+| `cv::FONT_*` | `Cv::HersheyFonts::FONT_*` |
+
+## Introspecting Types
+
+Use Ruby introspection to discover available types:
+
+```ruby
+require 'opencv-ruby'
+
+# List all classes in Cv module
+Cv.constants.select { |c| Cv.const_get(c).is_a?(Class) }
+
+# List methods on a class
+Cv::Mat.instance_methods(false)
+
+# List enum values
+Cv::ImreadModes.constants
+
+# Check class hierarchy
+Cv::ORB.ancestors
+```
+
+## See Also
+
+- [C++ to Ruby](cpp-to-ruby.md) - Translation guide
+- [API Coverage](api-coverage.md) - Module coverage summary
+- [API Reference](api/Cv/index.md) - Full class documentation

data/ext/CMakeLists.txt

@@ -0,0 +1,208 @@
+# =============================================================================
+# CMakeLists.txt - Builds opencv-ruby extension with Rice
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# CMake Version and C++ Standard
+# -----------------------------------------------------------------------------
+# CMake 3.26+ is required for modern FetchContent features and improved
+# Ruby detection. Rice requires C++17 for features like std::string_view,
+# structured bindings, and if-constexpr.
+
+cmake_minimum_required(VERSION 3.26)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_MESSAGE_LOG_LEVEL DEBUG)
+
+# -----------------------------------------------------------------------------
+# Project Definition
+# -----------------------------------------------------------------------------
+# Define the project name and specify that we only need a C++ compiler.
+# The project name is used throughout via ${CMAKE_PROJECT_NAME}.
+
+project("opencv_ruby" LANGUAGES CXX)
+
+# -----------------------------------------------------------------------------
+# Create the Extension Library
+# -----------------------------------------------------------------------------
+# IMPORTANT: Use MODULE instead of SHARED for Ruby extensions!
+#
+# - MODULE: Creates a loadable plugin that cannot be linked against.
+#           This is correct for Ruby extensions loaded via require/dlopen.
+# - SHARED: Creates a shared library that can be linked against.
+#           On macOS, this creates a .dylib which Ruby cannot load.
+
+if (MSVC)
+    # MSVC fails to recognize targets for debugging when using MODULE
+    add_library(${CMAKE_PROJECT_NAME} SHARED)
+else ()
+    add_library(${CMAKE_PROJECT_NAME} MODULE)
+endif ()
+
+# -----------------------------------------------------------------------------
+# Fetch Rice from GitHub
+# -----------------------------------------------------------------------------
+# Rice is a header-only library, so we use FetchContent to download it
+# automatically. This eliminates the need for users to manually install Rice.
+#
+# FetchContent downloads the repository at configure time and makes it
+# available as if it were part of your project.
+#
+# Note: For production gems, you may want to pin to a specific release tag
+# instead of 'dev' for reproducible builds.
+
+include(FetchContent)
+
+FetchContent_Declare(
+  rice
+  GIT_REPOSITORY https://github.com/ruby-rice/rice.git
+  GIT_TAG 4.9.1
+)
+FetchContent_MakeAvailable(rice)
+
+# -----------------------------------------------------------------------------
+# Configure Ruby Detection
+# -----------------------------------------------------------------------------
+# Rice provides an enhanced FindRuby.cmake that creates proper CMake targets
+# (Ruby::Ruby, Ruby::Module) instead of just setting variables. We prepend
+# Rice's module path so CMake finds this improved version.
+#
+# The upstream CMake FindRuby.cmake is being updated to support these targets,
+# but until that lands, we use Rice's version.
+
+list(PREPEND CMAKE_MODULE_PATH "${rice_SOURCE_DIR}")
+
+# -----------------------------------------------------------------------------
+# Find Ruby Installation
+# -----------------------------------------------------------------------------
+# find_package(Ruby) locates the Ruby installation and sets up:
+#   - Ruby::Ruby    - Target for embedding Ruby (links to libruby)
+#   - Ruby::Module  - Target for extensions (links to Ruby headers only)
+#
+# For extensions, always link to Ruby::Module, not Ruby::Ruby!
+# Extensions are loaded into an already-running Ruby process, so they
+# should not link against libruby (which could cause symbol conflicts).
+
+find_package(Ruby REQUIRED)
+
+target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE
+  Ruby::Module
+)
+
+# -----------------------------------------------------------------------------
+# Link to Rice
+# -----------------------------------------------------------------------------
+# The Rice::Rice target provides:
+#   - Include paths to Rice headers
+#   - Required compiler flags for Rice
+#
+# Rice is header-only, so this doesn't add any link-time dependencies.
+
+target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE
+  Rice::Rice
+)
+
+# -----------------------------------------------------------------------------
+# OpenCv
+# -----------------------------------------------------------------------------
+
+find_package(OpenCV CONFIG REQUIRED)
+target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE ${OpenCV_INCLUDE_DIRS})
+target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE ${OpenCV_LIBS})
+
+# -----------------------------------------------------------------------------
+# OpenCv
+# -----------------------------------------------------------------------------
+# FFI
+if (MSVC) # This will include Clang on Windows
+    find_package(unofficial-libffi CONFIG REQUIRED)
+    target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE unofficial::libffi::libffi)
+else()
+    # Use pkg-config on Unix-like systems (Linux, macOS, MinGW)
+    find_package(PkgConfig QUIET)
+    if (PkgConfig_FOUND)
+        pkg_check_modules(FFI REQUIRED IMPORTED_TARGET libffi)
+        target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE PkgConfig::FFI)
+    else()
+        # Fallback for systems without pkg-config
+        find_library(FFI_LIBRARY NAMES ffi REQUIRED)
+        target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE ${FFI_LIBRARY})
+    endif()
+endif()
+target_compile_definitions(${CMAKE_PROJECT_NAME} PRIVATE HAVE_LIBFFI)
+
+# -----------------------------------------------------------------------------
+# Include Directories for Project Headers
+# -----------------------------------------------------------------------------
+# Add the current directory (ext/) to the include path so we can find
+# our project's header files (BitmapPlusPlus.hpp, etc.)
+
+target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE .)
+
+# -----------------------------------------------------------------------------
+# Configure Extension Output
+# -----------------------------------------------------------------------------
+# Ruby extensions have specific naming requirements that vary by platform:
+#
+# Extension Suffix (from Ruby configuration):
+#   - Linux:   .so           (e.g., bitmap_plus_plus_ruby.so)
+#   - macOS:   .bundle       (e.g., bitmap_plus_plus_ruby.bundle)
+#   - Windows: .so           (e.g., bitmap_plus_plus_ruby.so)
+#
+# Note: Windows uses .so (not .dll) for Ruby extensions by convention.
+#
+# PREFIX "": Ruby extensions have no 'lib' prefix (unlike regular shared libs)
+#
+# Visibility Settings:
+#   - CXX_VISIBILITY_PRESET hidden: Hide all symbols by default
+#   - VISIBILITY_INLINES_HIDDEN ON: Hide inline function symbols
+#   - WINDOWS_EXPORT_ALL_SYMBOLS OFF: Don't auto-export on Windows
+#
+# These settings ensure only the Init_* function is exported, reducing
+# binary size and avoiding symbol conflicts with other extensions.
+#
+# Output Directories:
+#   - RUNTIME_OUTPUT_DIRECTORY: Where Windows puts .dll/.so files
+#   - LIBRARY_OUTPUT_DIRECTORY: Where Unix puts .so/.bundle files
+#
+# On Windows, we place the extension in a Ruby version-specific subdirectory
+# (e.g., lib/3.3/) to support multiple Ruby versions simultaneously.
+
+get_target_property(RUBY_EXT_SUFFIX Ruby::Ruby INTERFACE_RUBY_EXTENSION_SUFFIX)
+
+set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES
+  PREFIX ""
+  SUFFIX "${RUBY_EXT_SUFFIX}"
+  OUTPUT_NAME "opencv_ruby"
+  CXX_VISIBILITY_PRESET hidden
+  VISIBILITY_INLINES_HIDDEN ON
+  WINDOWS_EXPORT_ALL_SYMBOLS OFF
+  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/../lib/${Ruby_VERSION_MAJOR}.${Ruby_VERSION_MINOR}" # Windows
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/../lib" # Linxux/macOS
+)
+
+# -----------------------------------------------------------------------------
+# Compiler Settings
+# -----------------------------------------------------------------------------
+target_compile_definitions(${CMAKE_PROJECT_NAME} PRIVATE
+                           CVAPI_EXPORTS)
+
+# Fixes error G5FE2FDFE:  __attribute__((noreturn))' cannot be used prior to '::' because it has no members
+if (CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+    target_compile_definitions(${CMAKE_PROJECT_NAME} PUBLIC CV_NORETURN=)
+elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang" AND CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC")
+    target_compile_definitions(${CMAKE_PROJECT_NAME} PUBLIC CV_NORETURN="__declspec(noreturn)")
+elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+    target_compile_definitions(${CMAKE_PROJECT_NAME} PUBLIC CV_NORETURN=)
+endif()
+
+# -----------------------------------------------------------------------------
+# Source Files
+# -----------------------------------------------------------------------------
+# Add source files
+target_sources(${CMAKE_PROJECT_NAME} PUBLIC
+               "opencv_ruby-rb.cpp")
+
+# Add subdirectories
+add_subdirectory ("opencv2")