VidGear Docs: Minor Updates

abhiTronix · Jun 12, 2020 · e200566 · e200566
1 parent 55ce12c
commit e200566
Show file tree

Hide file tree

Showing 8 changed files with 100 additions and 7 deletions.
diff --git a/docs/gears/camgear/advanced/source_params.md b/docs/gears/camgear/advanced/source_params.md
@@ -0,0 +1,93 @@
+<!--
+===============================================
+vidgear library source-code is deployed under the Apache 2.0 License:
+
+Copyright (c) 2019-2020 Abhishek Thakur(@abhiTronix) <[email protected]>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+===============================================
+-->
+
+# Source Tweak Parameters for CamGear API 
+
+## Overview
+
+The CamGear API's [`option`](https://github.com/abhiTronix/vidgear/wiki/CamGear#parameters-and-attributes-wrench) dictionary parameter, provides the ability to alter various **Source Tweak Parameters** available within [OpenCV's VideoCapture Class](https://docs.opencv.org/master/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80). These tweak parameters can be used to manipulate input source Camera-Device properties _(such as its brightness, saturation, size, iso, gain etc.)_ seemlessly. Thereby, All Source Tweak Parameters supported by CamGear API are disscussed in this document.
+
+
+!!! warning "Remember, Not all parameters are supported by all cameras devices, which is one of the most troublesome thing with OpenCV library. Each camera type, from android cameras, to USB cameras , to professional ones, offers a different interface to modify its parameters. Therefore, there are many branches in OpenCV code to support as many of them, but of course, not all possible devices are covered, and thereby works. Furthermore, OpenCV does not return any helpful error messages regarding this problem, so it’s pretty much based on _trial and error_."
+
+
+!!! tip "You can easily check parameter values supported by your webcam, by hooking it to a Linux machine, and using the command `#!sh v4l2-ctl -d 0 --list-formats-ext` _(where 0 is an index of the given camera)_ to list the supported video parameters and their values. If that doesn't works, refer to its datasheet _(if available)_."
+
+
+&nbsp; 
+
+
+## Supported Source Tweak Parameters
+
+**All Source Tweak Parameters supported by CamGear API are as follows:**
+
+!!! info "These parameters can be passed to CamGear's [`option`](../../params/#options) dictionary parameter by formatting them as its string attributes."
+
+!!! tip "Its complete usage example is [here ➶](../../usage/#using-camgear-with-variable-camera-properties)"
+
+|Values|Description|
+|:--------------------------------------:	|:--------------------------------------------------------------------------------------------------------------------	|
+| CAP_PROP_POS_MSEC 	| Current position of the video file in milliseconds. 	|
+| CAP_PROP_POS_FRAMES 	| 0-based index of the frame to be decoded/captured next. 	|
+| CAP_PROP_POS_AVI_RATIO 	| Relative position of the video file: 0=start of the film, 1=end of the film. 	|
+| CAP_PROP_FRAME_WIDTH 	| Width of the frames in the video stream. 	|
+| CAP_PROP_FRAME_HEIGHT 	| Height of the frames in the video stream. 	|
+| CAP_PROP_FPS 	| Frame rate. 	|
+| CAP_PROP_FOURCC 	| 4-character code of codec. see [VideoWriter::fourcc](https://docs.opencv.org/master/dd/d9e/classcv_1_1VideoWriter.html#afec93f94dc6c0b3e28f4dd153bc5a7f0). 	|
+| CAP_PROP_FRAME_COUNT 	| Number of frames in the video file. 	|
+| CAP_PROP_FORMAT 	| Format of the Mat objects returned by [VideoCapture::retrieve()](https://docs.opencv.org/master/d8/dfe/classcv_1_1VideoCapture.html#a9ac7f4b1cdfe624663478568486e6712). 	|
+| CAP_PROP_MODE 	| Backend-specific value indicating the current capture mode. 	|
+| CAP_PROP_BRIGHTNESS 	| Brightness of the image (only for those cameras that support). 	|
+| CAP_PROP_CONTRAST 	| Contrast of the image (only for cameras). 	|
+| CAP_PROP_SATURATION 	| Saturation of the image (only for cameras). 	|
+| CAP_PROP_HUE 	| Hue of the image (only for cameras). 	|
+| CAP_PROP_GAIN 	| Gain of the image (only for those cameras that support). 	|
+| CAP_PROP_EXPOSURE 	| Exposure (only for those cameras that support). 	|
+| CAP_PROP_CONVERT_RGB 	| Boolean flags indicating whether images should be converted to RGB. 	|
+| CAP_PROP_WHITE_BALANCE_BLUE_U 	| Currently unsupported. 	|
+| CAP_PROP_RECTIFICATION 	| Rectification flag for stereo cameras (note: only supported by DC1394 v 2.x backend currently). 	|
+| CAP_PROP_MONOCHROME 	|  	|
+| CAP_PROP_SHARPNESS 	|  	|
+| CAP_PROP_AUTO_EXPOSURE 	| DC1394: exposure control done by camera, user can adjust reference level using this feature. 	|
+| CAP_PROP_GAMMA 	|  	|
+| CAP_PROP_TEMPERATURE 	|  	|
+| CAP_PROP_TRIGGER 	|  	|
+| CAP_PROP_TRIGGER_DELAY 	|  	|
+| CAP_PROP_WHITE_BALANCE_RED_V 	|  	|
+| CAP_PROP_ZOOM 	|  	|
+| CAP_PROP_FOCUS 	|  	|
+| CAP_PROP_GUID 	|  	|
+| CAP_PROP_ISO_SPEED 	|  	|
+| CAP_PROP_BACKLIGHT 	|  	|
+| CAP_PROP_PAN 	|  	|
+| CAP_PROP_TILT 	|  	|
+| CAP_PROP_ROLL 	|  	|
+| CAP_PROP_IRIS 	|  	|
+| CAP_PROP_SETTINGS 	| Pop up video/camera filter dialog (note: only supported by DSHOW backend currently. The property value is ignored) 	|
+| CAP_PROP_BUFFERSIZE 	|  	|
+| CAP_PROP_AUTOFOCUS 	|  	|
+| CAP_PROP_SAR_NUM 	| Sample aspect ratio: num/den (num) 	|
+| CAP_PROP_SAR_DEN 	| Sample aspect ratio: num/den (den) 	|
+| CAP_PROP_BACKEND 	| Current backend (enum VideoCaptureAPIs). Read-only property. 	|
+| CAP_PROP_CHANNEL 	| Video input or Channel Number (only for those cameras that support) 	|
+| CAP_PROP_AUTO_WB 	| enable/ disable auto white-balance 	|
+| CAP_PROP_WB_TEMPERATURE 	| white-balance color temperature 	|
+
+&nbsp; 
diff --git a/docs/gears/camgear/overview.md b/docs/gears/camgear/overview.md
@@ -32,7 +32,7 @@ limitations under the License.
 
 CamGear supports a diverse range of video streams which can handle/control video stream almost any IP/USB Cameras,  multimedia video file format ([_upto 4k tested_](https://github.com/abhiTronix/vidgear/blob/62f32ad6663c871ec6aa4890ca1b55cd1286511a/vidgear/tests/benchmark_tests/test_benchmark_playback.py#L31-L71)), any network stream URL such as `http(s), rtp, rstp, rtmp, mms, etc.` In addition to this, it also supports live [Gstreamer's RAW pipelines](https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/using.html) and [YouTube video/livestreams URLs](../usage/#using-camgear-with-youtube-videos).
 
-CamGear API provides a flexible, high-level multi-threaded wrapper around OpenCV's *[VideoCapture API](https://docs.opencv.org/master/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80)* with direct access to almost all of its available [*parameters*](../source_params/) and also internally employs `pafy` with `youtube-dl` backend for seamless live [*YouTube streaming*](../usage/#using-camgear-with-youtube-videos). 
+CamGear API provides a flexible, high-level multi-threaded wrapper around OpenCV's *[VideoCapture API](https://docs.opencv.org/master/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80)* with direct access to almost all of its available [*parameters*](../advanced/source_params/) and also internally employs `pafy` with `youtube-dl` backend for seamless live [*YouTube streaming*](../usage/#using-camgear-with-youtube-videos). 
 
 CamGear relies exclusively on [**Threaded Queue mode**](../../../bonus/TQM/) for threaded, error-free and synchronized frame handling.
 

diff --git a/docs/gears/camgear/params.md b/docs/gears/camgear/params.md
@@ -164,7 +164,7 @@ This parameter provides the ability to alter various **Source Tweak Parameters**
 
 **Usage:**
 
-!!! tip "All supported parameters are listed [here ➶](../source_params/)"
+!!! tip "All supported parameters are listed [here ➶](../advanced/source_params/)"
 
 The desired parameters can be passed to CamGear API by formatting them as this parameter's attributes, as follows:
 

diff --git a/docs/gears/camgear/usage.md b/docs/gears/camgear/usage.md
@@ -122,7 +122,7 @@ stream.stop()
 CamGear API also flexibly support various **Source Tweak Parameters** available within [OpenCV's VideoCapture API](https://docs.opencv.org/master/d4/d15/group__videoio__flags__base.html#gaeb8dd9c89c10a5c63c139bf7c4f5704d). These parameters can be easily applied to source stream in CamGear API through its `options` dictionary parameter by formatting them as its attributes. The complete usage example is as follows:
 
 
-!!! tip "All the supported Source Tweak Parameters can be found [here ➶](../source_params/#source-tweak-parameters-for-camgear-api)"
+!!! tip "All the supported Source Tweak Parameters can be found [here ➶](../advanced/source_params/#source-tweak-parameters-for-camgear-api)"
 
 
 ```python

diff --git a/docs/gears/netgear_async/params.md b/docs/gears/netgear_async/params.md
@@ -337,7 +337,7 @@ This parameter provides the ability to alter various **Source Tweak Parameters**
 
 **Usage:**
 
-!!! tip "All supported parameters are listed [here ➶](../../camgear/source_params/)"
+!!! tip "All supported parameters are listed [here ➶](../../camgear/advanced/source_params/)"
 
 The desired parameters can be passed to NetGear_Async API by formatting them as this parameter's attributes, as follows:
 

diff --git a/docs/gears/videogear/params.md b/docs/gears/videogear/params.md
@@ -227,7 +227,7 @@ This parameter provides the ability to alter various **Source Tweak Parameters**
 
 **Usage:**
 
-!!! tip "All supported parameters are listed [here ➶](../../camgear/source_params/)"
+!!! tip "All supported parameters are listed [here ➶](../../camgear/advanced/source_params/)"
 
 The desired parameters can be passed to VideoGear API by formatting them as this parameter's attributes, as follows:
 

diff --git a/docs/gears/webgear/params.md b/docs/gears/webgear/params.md
@@ -128,7 +128,7 @@ This parameter can be used to pass user-defined parameter to WebGear API by form
 
 ### CamGear Specific attributes
 
-!!! tip "All supported parameters are listed [here ➶](../../camgear/source_params/#supported-source-tweak-parameters)"
+!!! tip "All supported parameters are listed [here ➶](../../camgear/advanced/source_params/#supported-source-tweak-parameters)"
 
 The desired parameters can be passed to VideoGear API by formatting them as this parameter's attributes, as follows:
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -142,7 +142,7 @@ nav:
       - Overview: gears/camgear/overview.md
       - Usage Examples: gears/camgear/usage.md
       - Advanced Usage:
-        - Source Tweak Parameters: gears/camgear/source_params.md
+        - Source Tweak Parameters: gears/camgear/advanced/source_params.md
       - Parameters: gears/camgear/params.md
       - Reference: bonus/reference/camgear.md
     - PiGear: