Noise_level, mask_file, threshold_maximum options

[AlexSunnyMan]

Greetigs!

I would like to talk about those options, its explanation in documentation. As I can see, in motion applied threading solution, e. g. an camera stream processing have its own processor thread (Thread 1, 2, motion_loop: Thread exiting in logs). This is good. With right motion configuration preview stream not lag. I need to make some changes for my motion configuration and I read the docs again. And I think, that some configuration options must be explained more detail. Ok. Noise_level option. Its current description:

BEGIN
The noise level is used as a threshold for distinguishing between noise and motion. This is different from the threshold parameter. This is changes at pixel level. The purpose is to eliminate the changes generated by electric noise in the camera. Especially in complete darkness you can see the noise as small grey dots that come randomly in the picture. This noise can create false motion detection. What this parameter means is that the intensity of a pixel must change more than +/- the noise threshold parameter to be counted.
NIGEB

As I understand, threshold and threshold_maximum is an pixels quantity interval. Lets call this pixels "motion" pixels. Noise_level - pixel color change delta. This is not a threshold, but it is limit delta. Camera streams frame flow (in h264 codec terms), which consists of, in main, I-frames аnd some number of frames with deltas of pixel color between those I-frames (B-, P-frames). Let suppose, for simple, that camera flows stream in grayscale - pixel color information encodes in one single byte (8 bit, from 1 to 255 in decimal). What is the "motion" pixel? This is the pixel in current inspected frame, absolute color value of which changed with relation with previous frame by the amount of more than noise_level value. Which previous frame: I-frame, P-frame, B-frame or, in general, previous absolute color value (the motion program restores whole frame form previous I-frame and current B- or P-frame?)? It seems that several methods of noise determinition are possible, and only one of them is the most efficient in terms of using processor time. If absolute color value of pixel changed by the amount less than noise_level value, then this pixel in current inspected frame called, for example, noise pixel. When the motion program starts an event and writes video? When number of "motion" pixels in current frame located between threshold and threshold_maximum values. If camera flow frames which pixel color are rgb-encoded (24 bit, 3 bytes), not grayscale-color how the motion program determines "motion" or noise pixels? How the motion program uses, applies nose_level in this situation?

---

About mask_file parameter. Current description:
BEGIN
The mask file must be a pgm format image file (portable gray map). Note that you must choose the BINARY 8-bit format.
To use this feature create an image of exact the same size as the ones you get from your camera. Then make it purely white for the areas you want detected and black for the areas you want ignored. You can also make gray areas where you want to lower the sensitivity to motion. Normally you will stick to pure black and white.
NIGEB
As described in description the main purpose of mask_file is to tell the motion program where on frame to detect motion, where not. But describes second purpose is: "You can also make gray areas where you want to lower the sensitivity to motion". For main purpose, as described here, also serves mask_privacy option. I think that main purpose for mask_file option is detection sensitivity ajusting. But how it works? From explanation that black color 100% forbids the motion program to detect and white color 100% allows motion to detect. How it works for increasing or decreasing detection sensitivity? Value of pixel color in pgm-mask is the noise_level value for each pixel or it absolute color value (in grayscale stream - color intensity, more bright, less bright) threshold, lower or higher on which motion not detects? So, when pgm-mask are applied it is already necessary to fulfill not one but two conditions in order for the pixel to receive the status of "motion" pixel: nose_level condition and pgm-mask-grayscale threshold condition. I think, that this needs more detailed explanation.

About auto tuning parameters like threshold_tune, noise_tune. For my motion program I was disable this options because could not fully understand how they work and what should be in result.

---

About frame frequency parameters, width and height. As I think that for work properly motion program needs to know actual input stream parameters (from ip-camera). For example, frame width, height, flow bitrate and other from current video stream settings of ip-camera. Motion can detect this parameters automatically or they may set up manually by user. For this purpose motion program have netcam_* options. For example, capture_rate parameter. Why capture_rate parameter, nor netcam_fps, netcam_bitrate, netcam_width, netcam_height? In motion configuration exists two frame rate parameters: main framerate in motion.conf and capture_rate. Why width and height sets up globally? It's a little confusing when you're trying to figure out what's what. What motion, in general, does?

1. Receives stream from camera
   For this motion program knows main initial parameters: width, height, bitrate, framerate and other details of input stream: like this: netcam_fps, netcam_bitrate, netcam_width, netcam_height similarly netcam_highres.
2. Perform detection operations (decode, compare and so on)
   for this operation no need setting up fps, bitrate, width, height, motion program simply uses normal cam (netcam_url) with it initial parameters for perfoming motion detection
3. Makes media operations (writes pictures, or videos)
   So in this step might want to set up custom parameters for output:
   for picture out:
   picture_out_pps (pps - pictures per second)
   picture_out_interval (if need more than 1 second between picture captures)
   picture_out_quality (by default 50%)
   picture_out_width (if not specified use input stream frame width)
   picture_out_height (if not specified use input stream frame height)
   picture_out_pps and picture_out_interval are mutual exclusive

for video out:
movie_out_fps (if not specified use input stream fps)
movie_out_bitrate (if not specified use input stream bitrate)
movie_out_width (if not specified use input stream frame width)
movie_out_height (if not specified use input stream frame height)

If all at once of these movie out parameters unspecified, or equal similar parameters of input stream and movie_out is "on" motion program writes movie in passthrough manner - without all cpu-expensive operatins, just copy input stream.

All of these parameters may be global (difined in motion.conf), or camera-specific (defined in camera.conf). If the input streams have different parameters, it is better that the video and image output parameters are specific to each camera or not specified at all. To avoid interpolating these parameters to the parameters set globally, which will lead to excessive resource consumption.

4. Web streaming for area realtime monitoring
   Web-streaming might be configured similarly movie out:
   webstream_fps (if not specified uses input stream fps)
   webstream_bitrate (if not specified uses input stream bitrate)
   webstream_width (if not specified uses input stream frame width)
   webstream_height (if not specified uses input stream frame height)
   Like movie parameters, if all at once of these webstream params not specified, or they are equal similar params of input stream motion performs passthrough web-streaming. Like picture or movie out params webstream parameters might be global or camera specifig.

And no global confusing parameters like framerate, with, height.

---

About quality parameters. There are quality parameters in percentages, there are quality parameters in bit rate. They are also a bit confusing. I think that setting the quality (compression ratio) as a percentage is enough to output images. For video output or web streaming, the quality of the video is determine bitrate, and the quality parameter in percentage no needs.

Thanks for patient