{"id":16871975,"url":"https://github.com/kylemcdonald/ofxcv","last_synced_at":"2025-05-16T19:08:19.462Z","repository":{"id":1024382,"uuid":"1549232","full_name":"kylemcdonald/ofxCv","owner":"kylemcdonald","description":"Alternative approach to interfacing with OpenCv from openFrameworks.","archived":false,"fork":false,"pushed_at":"2022-05-24T18:27:57.000Z","size":3468,"stargazers_count":663,"open_issues_count":50,"forks_count":275,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-05-16T19:07:48.518Z","etag":null,"topics":["addon","computer-vision","opencv","openframeworks","wrapper"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylemcdonald.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-03-31T03:11:15.000Z","updated_at":"2025-04-19T23:26:51.000Z","dependencies_parsed_at":"2022-08-06T10:01:23.958Z","dependency_job_id":null,"html_url":"https://github.com/kylemcdonald/ofxCv","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemcdonald%2FofxCv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemcdonald%2FofxCv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemcdonald%2FofxCv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemcdonald%2FofxCv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylemcdonald","download_url":"https://codeload.github.com/kylemcdonald/ofxCv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592393,"owners_count":22097013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["addon","computer-vision","opencv","openframeworks","wrapper"],"created_at":"2024-10-13T15:11:33.817Z","updated_at":"2025-05-16T19:08:19.443Z","avatar_url":"https://github.com/kylemcdonald.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nofxCv represents an alternative approach to wrapping OpenCV for openFrameworks.\n\n# Installation\n\nFirst, pick the branch that matches your version of openFrameworks:\n\n* OF [stable](https://github.com/openframeworks/openFrameworks/tree/stable) (0.9.8): use [ofxCv/stable](https://github.com/kylemcdonald/ofxCv/tree/stable)\n* OF [master](https://github.com/openframeworks/openFrameworks) (0.10.0): use [ofxCv/master](https://github.com/kylemcdonald/ofxCv/)\n\nEither clone out the source code using git:\n\n\t\u003e cd openFrameworks/addons/\n\t\u003e git clone https://github.com/kylemcdonald/ofxCv.git\n\nOr download the source from GitHub [here](https://github.com/kylemcdonald/ofxCv/archive/master.zip), unzip the folder, rename it from `ofxCv-master` to `ofxCv` and place it in your `openFrameworks/addons` folder.\n\nTo run the examples, import them into the project generator, create a new project, and open the project file in your IDE.\n\n# Goals\n\nofxCv has a few goals driving its development.\n\n### Wrap complex things in a helpful way\n\nSometimes this means: providing wrapper functions that require fewer arguments than the real CV functions, providing a smart interface that handles dynamic memory allocation to make things faster for you, or providing in place and out of place alternatives.\n\n### Present the power of OpenCv clearly\n\nThis means naming things in an intuitive way, and, more importantly, providing classes that have methods that transform the data represented by that class. It also means providing demos of CV functions, and generally being more useful than ofxOpenCv.\n\n### Interoperability of openFrameworks and OpenCv\n\nMaking it easy to work directly with CV by providing lightweight conversion functions, and providing wrappers for CV functions that do the conversions for you.\n\n### Elegant internal OpenCv code\n\nProvide clean implementations of all functions in order to provide a stepping stone to direct OpenCV use. This means using function names and variable names that follow the OpenCV documentation, and spending the time to learn proper CV usage so I can explain it clearly to others through code. Sometimes there will be heavy templating in order to make OF interoperable with OpenCV, but this should be avoided in favor of using straight OpenCV as often as possible.\n\n# Usage\n\nSometimes this readme will fall out of date. Please refer to the examples as the primary reference in that case.\n\n## Project setup\n\nUsing ofxCv requires:\n\n* ofxCv/libs/ofxCv/include/ Which contains all the ofxCv headers.\n* ofxCv/libs/ofxCv/src/ Which contains all the ofxCv source.\n* ofxCv/src/ Which ties together all of ofxCv into a single include.\n* opencv/include/ The OpenCv headers, located in addons/ofxOpenCv/\n* opencv/lib/ The precompiled static OpenCv libraries, located in addons/ofxOpenCv/\n\nYour linker will also need to know where the OpenCv headers are. In XCode this means modifying one line in Project.xconfig:\n\n\tHEADER_SEARCH_PATHS = $(OF_CORE_HEADERS) \"../../../addons/ofxOpenCv/libs/opencv/include/\" \"../../../addons/ofxCv/libs/ofxCv/include/\"\n\nAlternatively, I recommend using [OFXCodeMenu](https://github.com/openframeworks/OFXcodeMenu) to add ofxCv to your project.\n\n## Including ofxCv\n\nInside your ofApp.h you will need one include:\n\n\t#include \"ofxCv.h\"\n\nOpenCv uses the `cv` namespace, and ofxCv uses the `ofxCv` namespace. You can automatically import them by writing this in your `.cpp` files:\n\n\tusing namespace cv;\n\tusing namespace ofxCv;\n\nIf you look inside the ofxCv source, you'll find lots of cases of `ofxCv::` and `cv::`. In some rare cases, you'll need to write `cv::` in your code. For example, on OSX `Rect` and `Point` are defined by OpenCv, but also `MacTypes.h`. So if you're using an OpenCv `Rect` or `Point` you'll need to say so explicitly with `cv::Rect` or `cv::Point` to disambiguate.\n\nofxCv takes advantage of namespaces by using overloaded function names. This means that the ofxCv wrapper for `cv::Canny()` is also called `ofxCv::Canny()`. If you write simply `Canny()`, the correct function will be chosen based on the arguments you pass.\n\n## Working with ofxCv\n\nUnlike ofxOpenCv, ofxCv encourages you to use either native openFrameworks types or native OpenCv types, rather than introducing a third type like `ofxCvImage`. To work with OF and OpenCv types in a fluid way, ofxCv includes the `toCv()` and `toOf()` functions. They provide the ability to convert openFrameworks data to OpenCv data and vice versa. For large data, like images, this is done by wrapping the data rather than copying it. For small data, like vectors, this is done by copying the data.\n\nThe rest of ofxCv is mostly helper functions (for example, `threshold()`) and wrapper classes (for example, `Calibration`).\n\n### toCv() and copy()\n\n`toCv()` is used to convert openFrameworks data to OpenCv data. For example:\n\n\tofImage img;\n\timg.load(\"image.png\");\n\tMat imgMat = toCv(img);\n\nThis creates a wrapper for `img` called `imgMat`. To create a deep copy, use `clone()`:\n\n\tMat imgMatClone = toCv(img).clone();\n\nOr `copy()`, which works with any type supported by `toCv()`:\n\n\tMat imgCopy;\n\tcopy(img, imgCopy);\n\n`toCv()` is similar to ofxOpenCv's `ofxCvImage::getCvImage()` method, which returns an `IplImage*`. The biggest difference is that you can't always use `toCv()` \"in place\" when calling OpenCv code directly. In other words, you can always write this:\n\n\tMat imgMat = toCv(img);\n\tcv::someFunction(imgMat, ...);\n\nBut you should avoid using `toCv()` like this:\n\n\tcv::someFunction(toCv(img), ...);\n\nBecause there are cases where in place usage will cause a compile error. More specifically, calling `toCv()` in place will fail if the function requires a non-const reference for that parameter.\n\n### imitate()\n\n`imitate()` is primarily used internally by ofxCv. When doing CV, you regularly want to allocate multiple buffers of similar dimensions and channels. `imitate()` follows a kind of prototype pattern, where you pass a prototype image `original` and the image to be allocated `mirror` to `imitate(mirror, original)`. `imitate()` has two big advantages:\n\n* It works with `Mat`, `ofImage`, `ofPixels`, `ofVideoGrabber`, and anything else that extends `ofBaseHasPixels`.\n* It will only reallocate memory if necessary. This means it can be used liberally.\n\nIf you are writing a function that returns data, the ofxCv style is to call `imitate()` on the data to be returned from inside the function, allocating it as necessary.\n\n### drawMat() vs. toOf()\n\nSometimes you want to draw a `Mat` to the screen directly, as quickly and easily as possible, and `drawMat()` will do this for you. `drawMat()` is not the most optimal way of drawing images to the screen, because it creates a texture every time it draws. If you want to draw things efficiently, you should allocate a texture using `ofImage img;` *once* and draw it using `img.draw()`.\n\n1. Either use `Mat mat = toCv(img);` to treat the `ofImage` as a `Mat`, modify the `mat`, then `img.update()` to upload the modified pixels to the GPU.\n2. Alternatively; call `toOf(mat, img)` each time after modifying the `Mat`. This will only reallocate the texture if necessary, e.g. when the size has changed.\n\n\n# Working with OpenCv 2\n\nOpenCv 2 is an incredibly well designed API, and ofxCv encourages you to use it directly. Here are some hints on using OpenCv.\n\n### OpenCv Types\n\nOpenCv 2 uses the `Mat` class in place of the old `IplImage`. Memory allocation, copying, and deallocation are all handled automatically. `operator=` is a shallow, reference-counted copy. A `Mat` contains a collection of `Scalar` objects. A `Scalar` contains a collection of basic types (unsigned char, bool, double, etc.). `Scalar` is a short vector for representing color or other multidimensional information. The hierarchy is: `Mat` contains `Scalar`, `Scalar` contains basic types.\n\nDifferent functions accept `Mat` in different ways:\n\n* `Mat` will create a lightweight copy of the underlying data. It's easy to write, and it allows you to use `toCv()` \"in-place\" when passing arguments to the function.\n* `Mat\u0026` allows the function to modify the header passed in. This means the function can allocate if necessary.\n* `const Mat\u0026` means that the function isn't going to modify the underlying data. This should be used instead of `Mat` when possible. It also allows \"in-place\" `toCv()` usage.\n\n### Mat creation\n\nIf you're working with `Mat` directly, it's important to remember that OpenCv talks about `rows` and `cols` rather than `width` and `height`. This means that the arguments are \"backwards\" when they appear in the `Mat` constructor. Here's an example of creating a `Mat` wrapper for some grayscale `unsigned char* pixels` for which we know the `width` and `height`:\n\n\tMat mat = Mat(height, width, CV_8UC1, pixels, 0);\n\n### Mat operations\n\nBasic mathematical operations on `Mat` objects of the same size and type can be accomplished with matrix expressions. Matrix expressions are a collection of overloaded operators that accept `Mat`, `Scalar`, and basic types. A normal mathematical operation might look like:\n\n\tfloat x, a, b;\n\t...\n\tx = (a + b) * 10;\n\nA matrix operation looks similar:\n\n\tMat x, a, b;\n\t...\n\tx = (a + b) * 10;\n\nThis will add every element of `a` and `b`, then multiply the results by 10, and finally assign the result to `x`.\n\nAvailable matrix expressions include mathematical operators `+`, `-`, `/` (per element division), `*` (matrix multiplication), `.mul()` (per-element multiplication). As well as comparison operators `!=`, `==`, `\u003c`, `\u003e`, `\u003e=`, `\u003c=` (useful for thresholding). Binary operators `\u0026`, `|`, `^`, `~`. And a few others like `abs()`, `min()`, and `max()`. For the complete listing see the OpenCv documention or `mat.hpp`.\n\n# Code Style\n\nofxCv tries to have a consistent code style. It's most similar to the K\u0026R variant used for Java, and the indentation is primarily determined by XCode's auto-indent feature.\n\nMultiline comments are used for anything beyond two lines.\n\nCase statements have a `default:` fall-through with the last case.\n\nWhen two or three similar variables are initialized, commas are used instead of multiple lines. For example `Mat srcMat = toCv(src), dstMat = toCv(dst);`. This style was inherited from reading Jason Saragih's FaceTracker.\n\n- - --\n\n*ofxCv was developed with support from [Yamaguchi Center for Arts and Media](http://ycam.jp/).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylemcdonald%2Fofxcv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylemcdonald%2Fofxcv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylemcdonald%2Fofxcv/lists"}