rice 4.6.1 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7751b2018cc34ce9a256db07afdac1c1334f10df1c858e08943cfe65ccc3a0b0
-  data.tar.gz: a8e25ea390438e8ba30450501f955724e25a1fe6fcdc9b0504a393ac60af9585
+  metadata.gz: 75730bdd1cda9ed1d24be45b32d1cbe92b6dca8e021fdb39a8b681403fc1814a
+  data.tar.gz: eb653e187ef8d543007ad0ceb3e5712869d598466c21997d2fd759699742df19
 SHA512:
-  metadata.gz: 7ac0157d22f781cf34dd1d4704df142bc42e34d811c73c1e24ef3fbb3247161f2a0e76d80584aadc09eb6d97181dbb4a957518161a9afb89f61166cce08983bc
-  data.tar.gz: 38e129eb196928cba4bf2f003651fc7e273df2abaf605664d76cd036993d70c507e4c31fa4e09e61252c8ef71aa701390c80a2247f20419e95d37a674002be26
+  metadata.gz: 7c6a0d269f24af26c836ca71a7684d410d823a6661a26af1bb1ddb205b65067258119d49bcadabe9aa806884a4505213e5489d5638cdd3420b4edccd59e49928
+  data.tar.gz: 1a14760fb0e2903c594ae0e0a3d14077a806bf59c720323a30c6a8bc4958a0e35fd0c0436eedcd6b4a6451e8a7344098be0bab00113964127b4027c790159910

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 4.7.0 (2025-10-22)
+Updates:
+* Refactor Native wrappers - functions, methods, attributes and procs - to enable introspection API
+* Introduce Pointer<T> class to wrap pointers to fundamental types and arrays.
+* Add new methods Arg#setBuffer and Return#setBuffer to indicate that a C++ pointer references an array of objects versus a single object
+* Add a new Introspection API that exposes Rice internals to Ruby
+* Using the Introspection API, add support for generating RBS files for extensions. See bin/rice-rbs.rb
+* Using the Introspection API, add support for generating Markdown documentation for extensions. See bin/rice-doc.rb
+* Don't create attribute writers for const attributes
+* Support attribute setters for Enums
+* Support wrapping std::vector<std::unique_ptr<T>>
+* Update Array#push to not always copy C++ instances. This lays the foundation for extracting references and pointers from tuples, variants and optionals.
+* Add very basic support for creating std::filesystem::path instances
+* Remove toy samples and test libraries. These will be replaced by a new gem that wraps the BitMapPlusPlus library (https://github.com/baderouaich/BitmapPlusPlus)
+* Add support for std::runtime_error since some libraries use that as a base exception class (thus when Rice wraps custom exceptions it also needs to wrap the base class)
+* Improve std::vector indexing to more closely match Ruby for negative index values
+* Correctly encode UTF8 Ruby class names in exception messages
+* Add support for disabling Ruby's global interpreter lock (GIL) when calling native functions
+
+Breaking Changes:
+* Custom implementations of From_Ruby must include a custom constructor:
+    ```
+    explicit From_Ruby(Arg* arg)
+   ```
+* Custom implementations of To_Ruby must include a custom constructor:
+    ```
+    explicit To_Ruby(Return* returnInfo)
+   ```
+* You can no longer pass a Buffer<T> to an API that takes a pointer. Instead use Buffer<T>#data or Buffer<T>::release
+* The Rice_Init method has been removed.
+
 ## 4.6.1 (2025-06-25)
 * Improve attribute handling. Correctly deal with non-copyable/assignable attributes and return references instead of copies of objects
 * Improve Buffer implementation to deal with 4 cases:

data/CMakeLists.txt

@@ -25,7 +25,3 @@ endif ()
 
 # Include sub-projects.
 add_subdirectory ("test")
-add_subdirectory ("sample/callbacks")
-add_subdirectory ("sample/enum")
-add_subdirectory ("sample/inheritance")
-add_subdirectory ("sample/map")

data/Rakefile

@@ -17,13 +17,7 @@ is_mswin = !RbConfig::CONFIG['host_os'].match(/mswin/).nil?
 MAKE = is_mswin ? 'nmake' : 'make'
 
 unittest = File.join(__dir__, "test", "unittest#{RbConfig::CONFIG['EXEEXT']}")
-sample_callbacks = File.join(__dir__, "sample", "callbacks", "sample_callbacks.so")
-sample_enum = File.join(__dir__, "sample", "enum", "sample_enum.so")
-sample_inheritance = File.join(__dir__, "sample", "inheritance", "animals.so")
-sample_map = File.join(__dir__, "sample", "map", "map.so")
-test_ext1 = File.join(__dir__, "test", "ext", "t1", "t1.so")
-test_ext2 = File.join(__dir__, "test", "ext", "t2", "t2.so")
-binaries = [unittest, sample_callbacks, sample_enum, sample_inheritance, sample_map, test_ext1, test_ext2]
+binaries = [unittest]
 
 binaries.each do |asset|
   file asset  do
@@ -90,7 +84,7 @@ FileUtils.mkdir_p(include_dir) #unless File.exists?('include')
 desc "Update rice header files"
 task :headers do
   FileUtils.rm_rf(File.join(include_dir, "rice", "*"))
-  path = File.join(__dir__, 'lib', 'make_rice_headers.rb')
+  path = File.join(__dir__, 'lib', 'rice', 'make_rice_headers.rb')
   # Execute make_rice_headers.rb
   run_command(Gem.ruby, path)
 end

data/bin/rice-doc.rb

@@ -0,0 +1,212 @@
+require 'libxml-ruby'
+
+# Require rice
+require_relative '../lib/rice'
+require_relative '../lib/rice/doc'
+
+# Now setup option parser
+require 'ostruct'
+require 'optparse'
+
+module Rice
+	# == Synopsis
+	#
+	# Generates Mkdocs for a Rice extension
+	#
+	# == Usage
+	# rice-doc [options] <rice_extension_library>
+	#
+	# Options:
+	#    -o, --output=path                Output directory
+	#    -v, --version                    Show version (1.1.0)
+	#    -h, --help                       Show help message
+
+	class Cmd
+		# :enddoc:
+		attr_accessor :options
+
+		def option_parser
+			OptionParser.new do |opts|
+				opts.banner = "rice-doc #{Rice::VERSION}\n" +
+											"Usage: rice-doc [options] <rice_extension_library_path>"
+
+				opts.separator ""
+				opts.separator "Options:"
+
+				opts.on('-o path', '--output=path',
+								'Output generated mkdoc files to the specified directory') do |dir|
+					options.output = File.expand_path(dir)
+				end
+
+				opts.on_tail("-v version", "--version", "Show version (#{Rice::VERSION})") do
+					puts "ruby_prof " + Rice::VERSION
+					exit
+				end
+
+				opts.on_tail("-h", "--help", "Show help message") do
+					puts opts
+					exit
+				end
+			end
+		end
+
+		def parse_args
+			@options = OpenStruct.new
+			options.extension = nil
+			options.output = nil
+
+			# Make sure the user specified at least one file
+			if ARGV.length < 1 and not options.exec
+				puts self.option_parser
+				puts ""
+				puts "Must specify a rice extension"
+				exit(-1)
+			end
+
+			self.option_parser.parse! ARGV
+
+			if options.output.nil?
+				puts "Must specify an output directory with -o/--output option"
+				exit(-1)
+			elsif !Dir.exist?(options.output)
+				puts "Creating output directory '#{options.output}'"
+				Dir.mkdir(options.output)
+			end
+
+			options.extension = ARGV.shift
+
+			options
+		rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e
+			puts self.option_parser
+			puts e.message
+			exit(-1)
+		end
+	end
+end
+
+# Parse command line options
+cmd = Rice::Cmd.new
+options = cmd.parse_args
+
+# Load the extension
+require options.extension
+
+# Get modules and classes
+modules = Rice::Registries.instance.modules.modules
+klasses = Rice::Registries.instance.types.klasses
+
+# Doxygen documentation
+doxygen_root = "https://docs.opencv.org/4.x"
+doxygen_index = "https://docs.opencv.org/4.x/opencv.tag"
+#doxygen_index = "c:/Users/cfis/Downloads/opencv.tag"
+type_mappings = {/^enum\s*/i => '',
+								 /^union\s*/i => '',
+								 /<.*>/ => '',
+								 '::debug_build_guard' => ''}
+
+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'}
+}
+
+doxygen_resolver = Rice::Doc::Doxygen.new(doxygen_root, doxygen_index, type_mappings, method_mappings)
+
+# Setup resolvers per namespace
+resolvers = {nil => Rice::Doc::Ruby.new,
+						 'Cv' => doxygen_resolver,
+						 'Rice' => Rice::Doc::Rice.new,
+						 'Std' => Rice::Doc::CppReference.new}
+
+generator = Rice::Doc::Mkdocs.new(modules + klasses, resolvers, options.output)
+generator.generate

data/bin/rice-rbs.rb

@@ -0,0 +1,93 @@
+#! /usr/bin/env ruby
+
+require 'bundler/setup'
+
+# Require rice
+require 'rice'
+
+# Now setup option parser
+require 'ostruct'
+require 'optparse'
+
+module Rice
+	# == Synopsis
+	#
+	# Generates rbs files for a Rice extension
+	#
+	# == Usage
+	# rice-rbs [options] <rice_extension_library>
+	#
+	# Options:
+	#    -o, --output=path                Output directory
+	#    -v, --version                    Show version (1.1.0)
+	#    -h, --help                       Show help message
+
+	class Cmd
+		# :enddoc:
+		attr_accessor :options
+
+		def option_parser
+			OptionParser.new do |opts|
+				opts.banner = "rice-rbs #{Rice::VERSION}\n" +
+											"Usage: rice-rbs [options] <rice_extension_library_path>"
+
+				opts.separator ""
+				opts.separator "Options:"
+
+				opts.on('-o path', '--output=path',
+								'Output generated Rbs files to the specified directory') do |dir|
+					options.output = File.expand_path(dir)
+				end
+
+				opts.on_tail("-v version", "--version", "Show version (#{Rice::VERSION})") do
+					puts "ruby_prof " + Rice::VERSION
+					exit
+				end
+
+				opts.on_tail("-h", "--help", "Show help message") do
+					puts opts
+					exit
+				end
+			end
+		end
+
+		def parse_args
+			@options = OpenStruct.new
+			options.extension = nil
+			options.output = nil
+
+			# Make sure the user specified at least one file
+			if ARGV.length < 1 and not options.exec
+				puts self.option_parser
+				puts ""
+				puts "Must specify a rice extension"
+				exit(-1)
+			end
+
+			self.option_parser.parse! ARGV
+
+			if options.output.nil?
+				puts "Must specify an output directory with -o/--output option"
+				exit(-1)
+			elsif !Dir.exist?(options.output)
+				puts "Creating output directory '#{options.output}'"
+				Dir.mkdir(options.output)
+			end
+
+			options.extension = ARGV.shift
+
+			options
+		rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e
+			puts self.option_parser
+			puts e.message
+			exit(-1)
+		end
+	end
+end
+
+# Parse command line options
+cmd = Rice::Cmd.new
+options = cmd.parse_args
+
+rbs = Rice::Rbs.new(options.extension, options.output)
+rbs.generate