From af9ee90091a67bad24f8f7f188e6d8fbc242adbc Mon Sep 17 00:00:00 2001 From: Giles Payne Date: Thu, 16 Jul 2020 03:42:05 +0900 Subject: [PATCH] Merge pull request #17818 from komakai:documentation-improvements Documentation fixes/improvements * Documentation fixes/improvements * Remove HASH_UTILS defines --- modules/core/misc/objc/common/CVObjcUtil.h | 6 --- modules/core/misc/objc/common/DMatch.mm | 3 +- modules/core/misc/objc/common/KeyPoint.mm | 3 +- modules/core/misc/objc/common/Point2d.mm | 3 +- modules/core/misc/objc/common/Point2f.mm | 3 +- modules/core/misc/objc/common/Point3d.mm | 3 +- modules/core/misc/objc/common/Point3f.mm | 3 +- modules/core/misc/objc/common/Rect2d.mm | 3 +- modules/core/misc/objc/common/Rect2f.mm | 3 +- modules/core/misc/objc/common/RotatedRect.mm | 4 +- modules/core/misc/objc/common/Scalar.mm | 3 +- modules/core/misc/objc/common/Size2d.mm | 3 +- modules/core/misc/objc/common/Size2f.mm | 3 +- modules/core/misc/objc/common/TermCriteria.mm | 3 +- modules/objc/doc/README.md | 2 - modules/objc/generator/gen_objc.py | 48 ++++++++++++++----- platforms/ios/build_framework.py | 1 + 17 files changed, 64 insertions(+), 33 deletions(-) diff --git a/modules/core/misc/objc/common/CVObjcUtil.h b/modules/core/misc/objc/common/CVObjcUtil.h index 20581384cc..6d78ee39f8 100644 --- a/modules/core/misc/objc/common/CVObjcUtil.h +++ b/modules/core/misc/objc/common/CVObjcUtil.h @@ -6,12 +6,6 @@ #pragma once -typedef union { double d; int64_t l; } V64; -typedef union { float f; int32_t i; } V32; - -#define DOUBLE_TO_BITS(x) ((V64){ .d = x }).l -#define FLOAT_TO_BITS(x) ((V32){ .f = x }).i - #ifndef CV_EXPORTS #ifdef __cplusplus #define CV_EXPORTS __attribute__ ((visibility ("default"))) diff --git a/modules/core/misc/objc/common/DMatch.mm b/modules/core/misc/objc/common/DMatch.mm index 7d74f254ad..696bf111f4 100644 --- a/modules/core/misc/objc/common/DMatch.mm +++ b/modules/core/misc/objc/common/DMatch.mm @@ -5,7 +5,6 @@ // #import "DMatch.h" -#import "CVObjcUtil.h" @implementation DMatch { cv::DMatch native; @@ -90,6 +89,8 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/KeyPoint.mm b/modules/core/misc/objc/common/KeyPoint.mm index 8117910516..59d7c8b6e1 100644 --- a/modules/core/misc/objc/common/KeyPoint.mm +++ b/modules/core/misc/objc/common/KeyPoint.mm @@ -6,7 +6,6 @@ #import "KeyPoint.h" #import "Point2f.h" -#import "CVObjcUtil.h" @implementation KeyPoint { cv::KeyPoint native; @@ -75,6 +74,8 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Point2d.mm b/modules/core/misc/objc/common/Point2d.mm index 6c75cd233b..1e2acc1314 100644 --- a/modules/core/misc/objc/common/Point2d.mm +++ b/modules/core/misc/objc/common/Point2d.mm @@ -6,7 +6,6 @@ #import "Point2d.h" #import "Rect2d.h" -#import "CVObjcUtil.h" @implementation Point2d { cv::Point2d native; @@ -90,6 +89,8 @@ return [rect contains:self]; } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Point2f.mm b/modules/core/misc/objc/common/Point2f.mm index a43ed805b0..82e1beb0f2 100644 --- a/modules/core/misc/objc/common/Point2f.mm +++ b/modules/core/misc/objc/common/Point2f.mm @@ -6,7 +6,6 @@ #import "Point2f.h" #import "Rect2f.h" -#import "CVObjcUtil.h" @implementation Point2f { cv::Point2f native; @@ -90,6 +89,8 @@ return [rect contains:self]; } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Point3d.mm b/modules/core/misc/objc/common/Point3d.mm index a4770ddec4..5b0b5e59ab 100644 --- a/modules/core/misc/objc/common/Point3d.mm +++ b/modules/core/misc/objc/common/Point3d.mm @@ -6,7 +6,6 @@ #import "Point3d.h" #import "Point2d.h" -#import "CVObjcUtil.h" @implementation Point3d { cv::Point3d native; @@ -95,6 +94,8 @@ } } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Point3f.mm b/modules/core/misc/objc/common/Point3f.mm index bd03230f4b..89d17b31a0 100644 --- a/modules/core/misc/objc/common/Point3f.mm +++ b/modules/core/misc/objc/common/Point3f.mm @@ -6,7 +6,6 @@ #import "Point3f.h" #import "Point2f.h" -#import "CVObjcUtil.h" @implementation Point3f { cv::Point3f native; @@ -95,6 +94,8 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Rect2d.mm b/modules/core/misc/objc/common/Rect2d.mm index 20bd830ba5..e0aa8b2844 100644 --- a/modules/core/misc/objc/common/Rect2d.mm +++ b/modules/core/misc/objc/common/Rect2d.mm @@ -7,7 +7,6 @@ #import "Rect2d.h" #import "Point2d.h" #import "Size2d.h" -#import "CVObjcUtil.h" @implementation Rect2d { cv::Rect2d native; @@ -134,6 +133,8 @@ } } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Rect2f.mm b/modules/core/misc/objc/common/Rect2f.mm index 6f8b7c6fc4..243154fe1f 100644 --- a/modules/core/misc/objc/common/Rect2f.mm +++ b/modules/core/misc/objc/common/Rect2f.mm @@ -7,7 +7,6 @@ #import "Rect2f.h" #import "Point2f.h" #import "Size2f.h" -#import "CVObjcUtil.h" @implementation Rect2f { cv::Rect2f native; @@ -134,6 +133,8 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/RotatedRect.mm b/modules/core/misc/objc/common/RotatedRect.mm index e35002e1b3..a0ff793ace 100644 --- a/modules/core/misc/objc/common/RotatedRect.mm +++ b/modules/core/misc/objc/common/RotatedRect.mm @@ -8,7 +8,6 @@ #import "Point2f.h" #import "Size2f.h" #import "Rect2f.h" -#import "CVObjcUtil.h" #include @@ -94,6 +93,9 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Scalar.mm b/modules/core/misc/objc/common/Scalar.mm index 29a18a7991..2b7b4081f1 100644 --- a/modules/core/misc/objc/common/Scalar.mm +++ b/modules/core/misc/objc/common/Scalar.mm @@ -5,7 +5,6 @@ // #import "Scalar.h" -#import "CVObjcUtil.h" double getVal(NSArray* vals, int index) { return [vals count] > index ? vals[index].doubleValue : 0; @@ -94,6 +93,8 @@ double getVal(NSArray* vals, int index) { } } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; diff --git a/modules/core/misc/objc/common/Size2d.mm b/modules/core/misc/objc/common/Size2d.mm index cb9a8c25ea..1217f47c70 100644 --- a/modules/core/misc/objc/common/Size2d.mm +++ b/modules/core/misc/objc/common/Size2d.mm @@ -6,7 +6,6 @@ #import "Size2d.h" #import "Point2d.h" -#import "CVObjcUtil.h" @implementation Size2d { cv::Size2d native; @@ -93,6 +92,8 @@ } } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/Size2f.mm b/modules/core/misc/objc/common/Size2f.mm index 00ff5eec9f..399a3337f1 100644 --- a/modules/core/misc/objc/common/Size2f.mm +++ b/modules/core/misc/objc/common/Size2f.mm @@ -6,7 +6,6 @@ #import "Size2f.h" #import "Point2f.h" -#import "CVObjcUtil.h" @implementation Size2f { cv::Size2f native; @@ -93,6 +92,8 @@ } } +#define FLOAT_TO_BITS(x) ((Cv32suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/core/misc/objc/common/TermCriteria.mm b/modules/core/misc/objc/common/TermCriteria.mm index b7339cd523..0c3f6cefb5 100644 --- a/modules/core/misc/objc/common/TermCriteria.mm +++ b/modules/core/misc/objc/common/TermCriteria.mm @@ -5,7 +5,6 @@ // #import "TermCriteria.h" -#import "CVObjcUtil.h" @implementation TermCriteria { cv::TermCriteria native; @@ -102,6 +101,8 @@ } } +#define DOUBLE_TO_BITS(x) ((Cv64suf){ .f = x }).i + - (NSUInteger)hash { int prime = 31; uint32_t result = 1; diff --git a/modules/objc/doc/README.md b/modules/objc/doc/README.md index 640d8eb70b..79bedec02c 100644 --- a/modules/objc/doc/README.md +++ b/modules/objc/doc/README.md @@ -11,5 +11,3 @@ To get started: add the OpenCV framework to your project and add the following t ###Swift import OpenCV - -For details of core OpenCV functionality see: `Core`, `Mat`, `Imgproc` diff --git a/modules/objc/generator/gen_objc.py b/modules/objc/generator/gen_objc.py index 335f5985f3..6df15c8bf6 100755 --- a/modules/objc/generator/gen_objc.py +++ b/modules/objc/generator/gen_objc.py @@ -83,6 +83,8 @@ method_dict = { ("Mat", "dot") : "-dot:" } +modules = [] + def read_contents(fname): with open(fname, 'r') as f: data = f.read() @@ -124,7 +126,7 @@ class GeneralInfo(): docstring += sanitize_documentation_string(doc, type) elif type == "class": - docstring += "/**\n* The " + self.name + " module\n*/\n" + docstring += "/**\n * The " + self.name + " module\n */\n" self.docstring = docstring @@ -199,6 +201,19 @@ def cast_to(t): return type_dict[t]["cast_to"] return t +def gen_class_doc(docstring, module, members, enums): + lines = docstring.splitlines() + lines.insert(len(lines)-1, " *") + if len(members) > 0: + lines.insert(len(lines)-1, " * Member classes: " + ", ".join([("`" + m + "`") for m in members])) + lines.insert(len(lines)-1, " *") + else: + lines.insert(len(lines)-1, " * Member of `" + module + "`") + if len(enums) > 0: + lines.insert(len(lines)-1, " * Member enums: " + ", ".join([("`" + m + "`") for m in enums])) + + return "\n".join(lines) + class ClassPropInfo(): def __init__(self, decl): # [f_ctype, f_name, '', '/RW'] self.ctype = decl[0] @@ -232,6 +247,8 @@ class ClassInfo(GeneralInfo): self.base = '' self.is_base_class = True self.native_ptr_name = "nativePtr" + self.member_classes = [] # Only relevant for modules + self.member_enums = [] # Only relevant for modules if decl[1]: self.base = re.sub(r"^.*:", "", decl[1].split(",")[0]).strip().replace(self.objc_name, "") if self.base: @@ -347,7 +364,7 @@ class ClassInfo(GeneralInfo): objcName = self.objc_name, cName = self.cname, imports = "\n".join(self.getImports(M)), - docs = self.docstring, + docs = gen_class_doc(self.docstring, M, self.member_classes, self.member_enums), base = self.base) def generateObjcBodyCode(self, m, M): @@ -379,7 +396,7 @@ class ClassInfo(GeneralInfo): objcName = self.objc_name, cName = self.cname, imports = "\n".join(self.getImports(M)), - docs = self.docstring, + docs = gen_class_doc(self.docstring, M, self.member_classes, self.member_enums), base = self.base) class ArgInfo(): @@ -557,11 +574,13 @@ class ObjectiveCWrapperGenerator(object): self.skipped_func_list = [] self.def_args_hist = {} # { def_args_cnt : funcs_cnt } - def add_class(self, decl): + def add_class(self, decl, module): classinfo = ClassInfo(decl, namespaces=self.namespaces) if classinfo.name in class_ignore_list: logging.info('ignored: %s', classinfo) return + if classinfo.name != module: + self.classes[module].member_classes.append(classinfo.name) name = classinfo.name if self.isWrapped(name) and not classinfo.base: logging.warning('duplicated: %s', classinfo) @@ -620,7 +639,7 @@ class ObjectiveCWrapperGenerator(object): ci.addConst(constinfo) logging.info('ok: %s', constinfo) - def add_enum(self, decl, scope): # [ "enum cname", "", [], [] ] + def add_enum(self, decl): # [ "enum cname", "", [], [] ] enumType = decl[0].rsplit(" ", 1)[1] if enumType.endswith(""): enumType = None @@ -641,10 +660,12 @@ class ObjectiveCWrapperGenerator(object): "objc_type": objc_type, "is_enum": True, "import_module": import_module} + self.classes[self.Module].member_enums.append(objc_type) + const_decls = decl[3] for decl in const_decls: - self.add_const(decl, scope, enumType) + self.add_const(decl, self.Module, enumType) def add_func(self, decl): fi = FuncInfo(decl, namespaces=self.namespaces) @@ -688,7 +709,7 @@ class ObjectiveCWrapperGenerator(object): # TODO: support UMat versions of declarations (implement UMat-wrapper for Java) parser = hdr_parser.CppHeaderParser(generate_umat_decls=False) - self.add_class( ['class ' + self.Module, '', [], []] ) # [ 'class/struct cname', ':bases', [modlist] [props] ] + self.add_class( ['class ' + self.Module, '', [], []], self.Module ) # [ 'class/struct cname', ':bases', [modlist] [props] ] # scan the headers and build more descriptive maps of classes, consts, functions includes = [] @@ -708,12 +729,12 @@ class ObjectiveCWrapperGenerator(object): logging.info("\n--- Incoming ---\n%s", pformat(decl[:5], 4)) # without docstring name = decl[0] if name.startswith("struct") or name.startswith("class"): - self.add_class(decl) + self.add_class(decl, self.Module) elif name.startswith("const"): self.add_const(decl) elif name.startswith("enum"): # enum - self.add_enum(decl, self.Module) + self.add_enum(decl) else: # function self.add_func(decl) @@ -1139,14 +1160,18 @@ typedef NS_ENUM(int, {2}) {{ def finalize(self, output_objc_path): opencv_header_file = os.path.join(output_objc_path, framework_name + ".h") - self.save(opencv_header_file, '\n'.join(['#import "%s"' % os.path.basename(f) for f in self.header_files if os.path.basename(f) != "CVObjcUtil.h"])) + self.save(opencv_header_file, '\n'.join(['#import "%s"' % os.path.basename(f) for f in self.header_files])) cmakelist_template = read_contents(os.path.join(SCRIPT_DIR, 'templates/cmakelists.template')) cmakelist = Template(cmakelist_template).substitute(modules = ";".join(modules), framework = framework_name) self.save(os.path.join(dstdir, "CMakeLists.txt"), cmakelist) mkdir_p("./framework_build") mkdir_p("./test_build") mkdir_p("./doc_build") - copyfile(os.path.join(SCRIPT_DIR, '../doc/README.md'), "./doc_build/README.md") + with open(os.path.join(SCRIPT_DIR, '../doc/README.md')) as readme_in: + readme_body = readme_in.read() + readme_body += "\n\n\n##Modules\n\n" + ", ".join(["`" + m.capitalize() + "`" for m in modules]) + with open("./doc_build/README.md", "w") as readme_out: + readme_out.write(readme_body) if framework_name != "OpenCV": for dirname, dirs, files in os.walk(os.path.join(testdir, "test")): for filename in files: @@ -1305,7 +1330,6 @@ if __name__ == "__main__": generator = ObjectiveCWrapperGenerator() gen_dict_files = [] - modules = [] framework_name = args.framework print("Objective-C: Processing OpenCV modules: %d" % len(config['modules'])) diff --git a/platforms/ios/build_framework.py b/platforms/ios/build_framework.py index c498a462fb..0f96f018ca 100755 --- a/platforms/ios/build_framework.py +++ b/platforms/ios/build_framework.py @@ -373,6 +373,7 @@ class Builder: doc_path = os.path.join(builddirs[0], "modules", "objc", "doc_build", "docs") if os.path.exists(doc_path): shutil.copytree(doc_path, os.path.join(outdir, "docs")) + shutil.copyfile(os.path.join(self.opencv, "doc", "opencv.ico"), os.path.join(outdir, "docs", "favicon.ico")) def copy_samples(self, outdir): return