Skip to content
This repository was archived by the owner on Oct 18, 2023. It is now read-only.

Commit 8478884

Browse files
fixed some formatting issues
1 parent 36a01cd commit 8478884

File tree

1 file changed

+72
-66
lines changed

1 file changed

+72
-66
lines changed

CONTRIBUTING.md

+72-66
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
# Contribution Guide
2+
13
First of all, any kind of contribution is highly appreciated, you don't have to be a pro in C++, neither am I. If you are totally new to native Node.js development and would like to get started, you can have a look at my article series as a quick introduction:
24
<a href="https://medium.com/netscape/tutorial-building-native-c-modules-for-node-js-using-nan-part-1-755b07389c7c"><b>Tutorial to Native Node.js Modules with C++</b></a>
35

4-
56
Oftentimes adding bindings is done similarly to what already exists in the codebase. Thus, you can take the existing stuff as an example to help you to get started. In the following, you can find some basic guidelines for adding new OpenCV function bindings to the package.
67

78
## API Design
9+
810
The API is designed such that
911

1012
A: Parameters passed to a function call are type checked and appropriate messages are displayed to the user in case an error occured. Nobody wants passing garbage to a function by coincidence to fail silently, which may produce unexpected results.
@@ -16,6 +18,7 @@ void GaussianBlur(InputArray src, OutputArray dst, Size ksize, double sigmaX, do
1618
```
1719
1820
The function should be invokable in the following ways:
21+
1922
``` javascript
2023
const mat = new cv.Mat(...)
2124
@@ -53,11 +56,11 @@ In the .h file add the declaration of the bindings its' worker to the class defi
5356
``` c++
5457
class Mat : public Nan::ObjectWrap {
5558

56-
...
59+
...
5760

58-
struct GaussianBlurWorker;
59-
NAN_METHOD(GaussianBlur);
60-
NAN_METHOD(GaussianBlurAsync);
61+
struct GaussianBlurWorker;
62+
NAN_METHOD(GaussianBlur);
63+
NAN_METHOD(GaussianBlurAsync);
6164

6265
}
6366

@@ -69,81 +72,81 @@ In the .cc file add the implementation of the worker:
6972
struct Mat::GaussianBlurWorker : public SimpleWorker {
7073
public:
7174
// instance of the class exposing the method
72-
cv::Mat mat;
73-
GaussianBlurWorker(cv::Mat mat) {
74-
this->mat = mat;
75-
}
75+
cv::Mat mat;
76+
GaussianBlurWorker(cv::Mat mat) {
77+
this->mat = mat;
78+
}
7679
7780
// required function arguments
78-
cv::Size2d kSize;
79-
double sigmaX;
81+
cv::Size2d kSize;
82+
double sigmaX;
8083
// optional function arguments
81-
double sigmaY = 0;
82-
int borderType = cv::BORDER_CONSTANT;
84+
double sigmaY = 0;
85+
int borderType = cv::BORDER_CONSTANT;
8386
8487
// function return value
85-
cv::Mat blurMat;
88+
cv::Mat blurMat;
8689
8790
// here the main work is performed, the async worker will execute
8891
// this in a different thread
89-
const char* execute() {
90-
cv::GaussianBlur(mat, blurMat, kSize, sigmaX, sigmaY, borderType);
92+
const char* execute() {
93+
cv::GaussianBlur(mat, blurMat, kSize, sigmaX, sigmaY, borderType);
9194
// if you need to handle errors, you can return an error message here, which
9295
// will trigger the error callback if message is not empty
93-
return "";
94-
}
96+
return "";
97+
}
9598
9699
// return the native objects, handle all object wrapping stuff here
97-
v8::Local<v8::Value> getReturnValue() {
98-
return Mat::Converter::wrap(blurMat);
99-
}
100-
101-
// implement this method if function takes any required arguments
102-
bool unwrapRequiredArgs(Nan::NAN_METHOD_ARGS_TYPE info) {
103-
return (
104-
Size::Converter::arg(0, &kSize, info) ||
105-
DoubleConverter::arg(1, &sigmaX, info)
106-
);
107-
}
108-
109-
// implement this method if function takes any optional arguments
110-
bool unwrapOptionalArgs(Nan::NAN_METHOD_ARGS_TYPE info) {
111-
return (
112-
DoubleConverter::optArg(2, &sigmaY, info) ||
113-
IntConverter::optArg(3, &borderType, info)
114-
);
115-
}
116-
117-
// implement the following methods if function takes more than a single optional parameter
118-
119-
// check if a JSON object as the first argument after the required arguments
120-
bool hasOptArgsObject(Nan::NAN_METHOD_ARGS_TYPE info) {
121-
return FF_ARG_IS_OBJECT(2);
122-
}
123-
124-
// get the values from named properties of the JSON object
125-
bool unwrapOptionalArgsFromOpts(Nan::NAN_METHOD_ARGS_TYPE info) {
126-
FF_OBJ opts = info[2]->ToObject();
127-
return (
128-
DoubleConverter::optProp(&sigmaY, "sigmaY", opts) ||
129-
IntConverter::optProp(&borderType, "borderType", opts)
130-
);
131-
}
100+
v8::Local<v8::Value> getReturnValue() {
101+
return Mat::Converter::wrap(blurMat);
102+
}
103+
104+
// implement this method if function takes any required arguments
105+
bool unwrapRequiredArgs(Nan::NAN_METHOD_ARGS_TYPE info) {
106+
return (
107+
Size::Converter::arg(0, &kSize, info) ||
108+
DoubleConverter::arg(1, &sigmaX, info)
109+
);
110+
}
111+
112+
// implement this method if function takes any optional arguments
113+
bool unwrapOptionalArgs(Nan::NAN_METHOD_ARGS_TYPE info) {
114+
return (
115+
DoubleConverter::optArg(2, &sigmaY, info) ||
116+
IntConverter::optArg(3, &borderType, info)
117+
);
118+
}
119+
120+
// implement the following methods if function takes more than a single optional parameter
121+
122+
// check if a JSON object as the first argument after the required arguments
123+
bool hasOptArgsObject(Nan::NAN_METHOD_ARGS_TYPE info) {
124+
return FF_ARG_IS_OBJECT(2);
125+
}
126+
127+
// get the values from named properties of the JSON object
128+
bool unwrapOptionalArgsFromOpts(Nan::NAN_METHOD_ARGS_TYPE info) {
129+
FF_OBJ opts = info[2]->ToObject();
130+
return (
131+
DoubleConverter::optProp(&sigmaY, "sigmaY", opts) ||
132+
IntConverter::optProp(&borderType, "borderType", opts)
133+
);
134+
}
132135
};
133136
```
134137

135138
After you have set up the worker, implementing the bindings is as easy as follows:
136139

137140
``` c++
138141
NAN_METHOD(Mat::GaussianBlur) {
139-
GaussianBlurWorker worker(Mat::Converter::unwrap(info.This()));
140-
FF_WORKER_SYNC("Mat::GaussianBlur", worker);
141-
info.GetReturnValue().Set(worker.getReturnValue());
142+
GaussianBlurWorker worker(Mat::Converter::unwrap(info.This()));
143+
FF_WORKER_SYNC("Mat::GaussianBlur", worker);
144+
info.GetReturnValue().Set(worker.getReturnValue());
142145
}
143146

144147
NAN_METHOD(Mat::GaussianBlurAsync) {
145-
GaussianBlurWorker worker(Mat::Converter::unwrap(info.This()));
146-
FF_WORKER_ASYNC("Mat::GaussianBlurAsync", GaussianBlurWorker, worker);
148+
GaussianBlurWorker worker(Mat::Converter::unwrap(info.This()));
149+
FF_WORKER_ASYNC("Mat::GaussianBlurAsync", GaussianBlurWorker, worker);
147150
}
148151
```
149152
@@ -152,6 +155,7 @@ NAN_METHOD(Mat::GaussianBlurAsync) {
152155
For converting native types to v8 types and unwrapping/ wrapping objects and instances you can use the Converters. A Converter will perform type checking and throw an error if converting a value or unwrapping an object failed. If a converter returns true, an error was thrown. You should use the Converters in conjunction with a worker struct. Otherwise you will have to handle rethrowing the error manually. There are Converters for conversion of primitive types, for unwrapping/ wrapping class instances as well as arrays of primitive types and arrays of instances. For representation of a JS array in c++ we are using std::vector.
153156
154157
Some Usage examples:
158+
155159
``` c++
156160
// require arg 0 to be a Mat
157161
cv::Mat img;
@@ -191,25 +195,25 @@ v8::Local<v8::Array> jsPoints = ObjectArrayConverter<Point2, cv::Point2d>::wrap(
191195
// std::vector<cv::Point2i> you can use the third template parameter to specify a conversion type
192196
std::vector<cv::Point2i> points;
193197
v8::Local<v8::Array> jsPoints = ObjectArrayConverter<Point2, cv::Point2d, cv::Point2i>::wrap(points);
194-
ObjectArrayConverter<Point2, cv::Point2d, cv::Point2i>::wrap(points);
195198
```
196199

197200
A class can be made convertable if you you add the typedef for an InstanceConverter the class definition. Example for the Mat class wrapper:
201+
198202
``` c++
199203
class Mat : public Nan::ObjectWrap {
200204
public:
201205
cv::Mat mat;
202206

203-
...
207+
...
204208

205-
cv::Mat* getNativeObjectPtr() { return &mat; }
206-
cv::Mat getNativeObject() { return mat; }
209+
cv::Mat* getNativeObjectPtr() { return &mat; }
210+
cv::Mat getNativeObject() { return mat; }
207211

208-
typedef InstanceConverter<Mat, cv::Mat> Converter;
212+
typedef InstanceConverter<Mat, cv::Mat> Converter;
209213

210-
static const char* getClassName() {
211-
return "Mat";
212-
}
214+
static const char* getClassName() {
215+
return "Mat";
216+
}
213217
};
214218
```
215219
@@ -272,13 +276,15 @@ In the corresponding markdown file in the doc folder add some docs, so that peop
272276
<a name="gaussianBlur"></a>
273277

274278
### gaussianBlur
279+
275280
``` javascript
276281
Mat : mat.gaussianBlur(Size kSize, Number sigmaX, Number sigmaY = 0.0, Uint borderType = BORDER_CONSTANT)
277282
```
278283

279284
<a name="gaussianBlurAsync"></a>
280285

281286
### gaussianBlurAsync
287+
282288
``` javascript
283289
mat.gaussianBlurAsync(Size kSize, Number sigmaX, callback(Error err, Mat result))
284290
mat.gaussianBlurAsync(Size kSize, Number sigmaX, ...opts, callback(Error err, Mat result))

0 commit comments

Comments
 (0)