Skip to content

Settings in LUNA Configurator service#

The LUNA Configurator service stores general settings for:

See "Use FaceStream with LUNA Configurator" for details on how the LUNA Configurator service interacts with FaceStream.

FaceStream settings#

Settings configuration is performed by editing parameters in the "FACE_STREAM_CONFIG" section in the Configurator service (see "Use FaceStream with Configurator");

You can also setting up FaceStream by editing the configuration file "fs3Config.conf" in the mode of working without the Configurator service (see "Use FaceStream with configuration files").

Below are the settings divided into logical blocks depending on the main functions performed by the block.

Logging section#

Settings section of the application logging process. It is responsible for message output on errors and/or current state of the application.

Severity parameter#

Severity parameter defines which information the user receives in logs. There are three information filter options:

0 - outputs all the information,

1 - outputs system warnings only,

2 - outputs errors only.

Tags parameter#

Tags enable you to get information about the processing of frames and errors that occur only for FaceStream processes of interest.

This parameter enables you to list tags that are associated with logging of relevant information.

If a corresponding tag is not specified, the information is not logged.

Information on specified tags is displayed according to the severity parameter value.

Logs text includes the corresponding tag. It can be used for logs filtration.

Errors are always written in the log. They do not require additional tags.

Tags description

Tag Description
streams Information about LUNA Streams operation
common General information
ffmpeg Information about FFMPEG library operation
liveness Information about the presence of a living person in the frame ("liveness" section): is there enough information for liveness check, and does the frame pass the liveness check
primary-track Information about the primary track ("primary_track_policy" section): the frame passed the specified thresholds and what track is selected as primary
bestshot Information about the best shot selection: best shot occurrence, its change and sending to external service
angles Information about filtration by head pose
ags Information corresponding to the frames quality. The information is used for further processing using LUNA PLATFORM
mouth-occlusion Information about mouth occlusion is recorded to the log file
statistics Information about performance, the number of frames processed per second, and the number of frames skipped
http_api Information about API requests sent to FaceStream in server mode and received responses
client Information about sending messages to LUNA PLATFORM and the responses received
json Information about processing parameters from configuration files and the Configurator service
debug Debug information. It is recommended to use this tag when debugging only and not during FS operation. It provides a large amount of debugging information

Mode parameter#

Mode parameter sets the logging mode of the application: file or console. There are three modes available:

  • "l2c" – output information to console only;

  • "l2f" – output information to file only;

  • "l2b" – output to both, console and file.

In the FaceStream mode of working with configuration files, you can configure the directory to save logs when information is output to a file using the --log-dir launching parameter.

Sending section#

This section is used to send portraits in the form of HTTP-requests from FaceStream to external services.

Request_type section#

This parameter is used only for working with faces.

This parameter defines a type of query that is used to send portraits to external services. There are 2 supported types (to work with different versions of LUNA):

  • "jpeg" is used to send normalized images to VisionLabs LUNA PLATFORM;

  • "json" may be used to send portraits to custom user services for further image processing.

For a detailed description of the requests, see the table below.

Request types

Format Request type Authorization headers Body
JSON PUT Authorization: Basic, login/password(Base64) Media type: application/json; frame – the original frame in Base64 (if send_source_frame option is on); data – a portrait in Base64; identification – Cid parameter value. JSON example: {frame":"","data":"image_in_base_64","identification":"camera_1"}
JPEG POST Authorization: Basic, login/password(Base64) or X-Auth-Token: 11c59254-e83f-41a3-b0eb-28fae998f271(UUID4) Media type: image/jpeg

Portrait_type parameter#

This parameter is used only for working with faces.

This parameter defines the format of a detected face to send to an external service. Possible values:

  • "warp" - use a normalized image;

  • "gost" - do not use the transformation, cut the detected area from the source frame, considering indentation.

Properties of the normalized image (warp):

  • size of 250x250 pixels;

  • face is centered;

  • face should be aligned in the way that, if you draw an imaginary line connecting the corners of the eyes, it is close to horizontal.

Such image format when working with LUNA PLATFORM offers the following advantages:

  • a constant minimal predictable amount of data for network transfer;

  • face detecting phases in LUNA PLATFORM automatically turn off for such images, which leads to the significant reduction of interaction time.

Send_source_frame parameter#

This parameter enables to send a full source frame where the face was detected.

When sending image to LUNA PLATFORM you should specify the URL of LUNA Image Store service in the "frame_store" parameter.

For the collection of bestshots ("number_of_bestshots_to_send" > 1), only one source frame is sent, which is determined by FaceStream to be the best of all bestshots. For example, if the setting value "number_of_bestshots_to_send" is 3, then three bestshots will be sent to LP and only one source frame, which will be automatically selected from the three bestshots.

The source frame is sent to LP some time before the bestshot is sent. It is stored in the LUNA Events database and assigned a unique ID, which is stored in the "image_origin" field of the "face_detect_result"/"body_detect_result" table. Next, the bestshot is sent to the LP and an event is generated, where the "image_origin" field indicates the ID of the source frame taken from the LUNA Events database.

Size_source_frame parameter#

Parameter changes the width of the source frame to the specified value. Valid range is [0...1024]. The value "0" means that the width will not change. The fractional part of the input is affected.

Detection_path_length parameter#

This parameter is used only for working with bodies.

Parameter sets the maximum number of detections for the "minimal_body_track_length_to_send" parameter. Values from 1 to 100 inclusive are available.

The maximum number of detections cannot exceed 100. If there are more than 100 detections, then the FaceStream algorithm will remove unnecessary detections with some step.

Minimal_body_track_length_to_send parameter#

This parameter is used only for working with bodies.

This parameter enables you to send a specified number of detections with the coordinates of the human body - x, y, width and height along with the bestshots (see the "save event" request in the LUNA PLATFORM OpenAPI document). According to the sets of detections of the human body, it is possible to determine its path.

The parameter should be used in conjunction with the detection handler > handler_id parameter. When this parameter is enabled, in addition to generating the general event, one more event will be created, associated with the general one by "track_id". This event will contain the coordinates of the human body and basic information about the event (detection time, event creation time, account ID, etc.)

The detection with the bestshot is mandatory to be sent.

Sending detections
Sending detections

If the number of detections is less than the specified value, then these detections will not be sent. For example, if the number of detections is "3" and the value of "minimal_body_track_length_to_send" is "4", then no detections will be sent and the following message will be displayed in the FaceStream logs:

Track is too short and will not be sent. Length 3 < 4

If the parameter value is "0", then no detections will be sent.

Async_requests parameter#

The parameter specifies whether to execute requests asynchronously or synchronously in LUNA PLATFORM.

By default, the asynchronous mode is set, in which all requests to the LUNA PLATFORM are performed in parallel.

Aggregate_attr_requests parameter#

This parameter enables the bestshots aggregation to receive a single descriptor in LUNA PLATFORM.

Aggregation is performed if there is more than one bestshot sent. The number of frames to send is set by the "number_of_bestshots_to_send" parameter.

The accuracy of face and body recognition is higher when using an aggregated descriptor.

Jpeg_quality_level parameter#

JPEG quality for source frames sending:

  • 'best' - compression is not performed
  • 'good' - 75% of source quality
  • 'normal' - 50% of source quality
  • 'average' - 25% of source quality
  • 'bad' - 10% of source quality

The 'best' quality is set by default.

High quality images sending can affect the frames processing speed.

Lunastreams section#

This section describes how to send ready-made images as HTTP requests from FaceStream to the LUNA Streams service.

See "Interaction of FaceStream with LUNA Streams" section for details on how LUNA Streams works with FaceStream.

Origin parameter#

The address and port of the server where the LUNA Streams service is running.

Api_version parameter#

The parameter specifies the API version of the LUNA Streams service. At the moment, the API version "1" is supported.

The current version of the API can always be found in the API service documentation.

Max_number_streams parameter#

The parameter sets the upper bound on the number of streams. The value must be greater than 0.

Request_stream_period parameter#

The parameter sets the time period between requests to receive new streams from LUNA Streams in the range from 0.1 to 3600 seconds.

The default value is 1 second.

Send_feedback_period parameter#

The parameter sets the time period between sending reports on processed streams to LUNA Streams in the range from 1.0 to 3600 seconds.

The default value is 5 seconds.

The value of this parameter should not exceed the value of the "STREAM_STATUS_OBSOLETING_PERIOD" parameter, set in the LUNA Streams service settings.

Max_feedback_delay parameter#

The parameter sets the maximum report sending delay in the range from 1.0 to 3600 seconds. If the report has not been sent within the given time, then FaceStream will stop processing the current streams.

The default value is 10 seconds.

The value of this parameter should not be less than the value of the parameter ["send_feedback_period"] (settings-in-luna-configurator-service.md#send_feedback_period-parameter) and should not exceed the value of the parameter "STREAM_STATUS_OBSOLETING_PERIOD", set in the LUNA Streams service settings.

Performance section#

Stream_images_buffer_max_size parameter#

The parameter specifies the maximum size of buffer with images for a single stream.

When you increase the parameter value, the FaceStream performance increases. The higher is the value, the more memory is required.

We recommend setting this parameter to 40 when working with GPU, if there is enough GPU memory.

Enable_gpu_processing parameter#

This parameter enables you to utilize GPU instead of CPU for calculations.

GPU enables you to speed up calculations, but it increases the consumption of RAM.

GPU calculations are supported for FaceDetV3 only. See "defaultDetectorType" parameter in the FaceEngine configuration ("faceengine.conf").

Convert_full_frame parameter#

If this parameter is enabled, the frame is immediately converted to an RGB image of the required size after decoding. This results in a better image quality but reduces the speed of frames processing.

If this parameter is disabled, the image is scaled according to the settings in the TrackEngine configuration (standard behavior for releases 3.2.4 and earlier).

This parameter is similar to frame_processing_mode parameter, but it is set for all FaceStream instances at once.

Monitoring section#

Monitoring settings are set in this section. The organization, bucket and token settings should be set at the start of the InfluxDB container as follows:

docker run \
-e DOCKER_INFLUXDB_INIT_BUCKET=facestream_monitoring \
-e DOCKER_INFLUXDB_INIT_ORG=facestream \
-e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=token \

Storage_type parameter#

This parameter enables to select the type of data storage for monitoring. For now, only the Influx database can be used.

Send_data parameter#

This parameter enables sending monitoring. Disabled by default.

Organization parameter#

This parameter specifies the InfluxDB 2.x workspace.

The workspace is created by passing the corresponding argument at the start of the Influx container.

Bucket parameter#

This parameter sets the InfluxDB 2.x bucket.

The bucket is not created automatically. It can be created using the Influx UI or by passing the appropriate argument at the start of the Influx container.

Token parameter#

This parameter specifies the InfluxDB 2.x authentication token.

Origin parameter#

This parameter specifies the IP address and port of the server with InfluxDB 2.x.

The default address is "127.0.0.1". Such an address means that InfluxDB 2.x, located on a server with LUNA Configurator, will be used. If InfluxDB 2.x is located on a different server, then in this parameter you need to specify the correct IP address of InfluxDB 2.x.

"origin": "http://127.0.0.1:8086/"

Flushing_period parameter#

This parameter sets frequency of sending monitoring data to InfluxDB (in seconds).

The default is 1 second.

TrackEngine settings#

This section describes the parameters of the TrackEngine configuration file that are used to configure FaceStream.

Settings configuration is performed by editing parameters in the "TRACK_ENGINE_CONFIG" configuration in the Configurator service (see "Use FaceStream with Configurator");

You can also setting up TrackEngine by editing the configuration file "trackengine.conf" in the mode of operation without the Configurator service (see "Use FaceStream with configuration files").

Use-face-detector and use-body-detector parameters#

These parameters enable you to change the detection of faces to bodies and vice versa. Simultaneous detection of faces and bodies is not possible.

It should be remembered that in order to successfully change the detection, it is necessary to set the appropriate FaceStream settings and settings of stream sources.

<!-- use-face-detector: Flag to use or not face detection -->
<param name="use-face-detector" type="Value::Int1" x="1" />

<!-- use-body-detector: Flag to use or not body detection -->
<param name="use-body-detector" type="Value::Int1" x="0" />

Detector-step parameter#

The "detector-step" parameter enables you to specify the number of frames on which face redetection will be performed in the specified area before face detection is performed. Redetection requires fewer resources, but the face may be lost if you set a large number of frames for redetection.

<!-- detector-step: The count of frames between frames with full detection, [0 .. 30] ('7' by default). -->
<param name="detector-step" type="Value::Int1" x="7" />

Detector-scaling parameter#

The "detector-scaling" parameter enables you to scale the frame before processing.

<!-- detector-scaling: Scale frame before detection for performance reasons, [0, 1] ('0' by default). -->
<param name="detector-scaling" type="Value::Int1" x="0" />

Scale-result-size parameter#

The "scale-result-size" parameter sets the maximum frame size after scaling the largest side of the frame. If the source frame had a size of 1920x1080 and the value of "scale-result-size" is equal to 640, then FaceStream will process the frame of 640x360 size.

If the frame was cut out using the "roi" parameter, the scaling will be applied to this cropped frame. In this case, you should specify the "scale-result-size" parameter value according to the greater ROI side.

You should gradually scale the frame and check whether face or body detection occurs on the frame, to select the optimal "scale-result-size" value. You should set the minimum image size at which all objects in the area of interest are detected.

Further extending our example, images below depict a video frame without resize (at original 1920x1080 resolution) and after resize to 960x640 with face detections visualized as bounding boxes.

Six faces can be detected when the source image resolution is 1920x1080.

Detections in image 1920X1080
Detections in image 1920X1080

Three faces are detected after the image is scaled to the 960x640 resolution. The faces in the background are smaller in size and are of poor quality.

Detections in image 960X640
Detections in image 960X640

The smaller the frame resolution, the less resources are consumed.

When working with bodies, this parameter works the same way.

<!-- scale-result-size: If scaling is enable, frame will be scaled to this size in pixels (by the max dimension - width or height). 
Upper scaling is not possible. ('640 by default') -->
<param name="scale-result-size" type="Value::Int1" x="640" />

Skip-frames parameter#

This parameter is used only for working with faces.

The "skip-frames" parameter sets the number of frames during which the system will wait for the object to reappear in the area where it disappeared.

Note that very high values may lead to performance degradation.

<!-- skip-frames: If track wasn't updated by detect/redetect for this number of frames, then track is finished ('36' by default). -->
<!-- note: very high values may lead to performance degradation. Parameter doesn't affect on human tracking. -->
<param name="skip-frames" type="Value::Int1" x="36" />

Frg-subtractor parameter#

When the "frg-subtractor" parameter is enabled, motion in the frame is considered. The following face and body detection will be performed in the area with motion, not in the entire frame.

The areas with motion are determined after the frame is scaled.

When the "frg-subtractor" is enabled, the performance of FaceStream is increased.

<!-- frg-subtractor: Use foreground subtractor for filter of frames, [0, 1] ('1' by default). -->
<param name="frg-subtractor" type="Value::Int1" x="1" />

Frg-regions-alignment parameter#

The "frg-regions-alignment" parameter enables you to set the alignment for the area with motion.

<!-- frg-regions-alignment: frg regions alignment. Useful for detector better batching utilization. -->
<!-- 0 or negative values mean using non aligned regions, (0 by default). -->
<param name="frg-regions-alignment" type="Value::Int1" x="0" />

Frg-regions-square-alignment parameter#

When the "frg-regions-square-alignment" parameter is enabled, the width and height of the area with motion will always be equal.

<!-- align frg regions to rect with equal sides (max side choosen). See frg-regions-alignment, [0, 1] ('1' by default). -->
<param name="frg-regions-square-alignment" type="Value::Int1" x="1" />

Batched-processing parameter#

The "batched-processing" parameter enables batch processing of frames.

When working with several video cameras, a frame is collected from each frame. Then the batch of frames is processed.

When the parameter is disabled, the frames are processed one by one.

When using batch processing mode, the delay before processing increases, but the processing itself is faster.

It is recommended to enable the parameter both when using the GPU and when using the CPU.

<!-- batched-processing: Process streams frames in batch or separately, [0, 1] ('1' by default). -->
<param name="batched-processing" type="Value::Int1" x="1" />

Min-frames-batch-size parameter#

The "min-frames-batch-size" parameter sets the minimal number of frames collected from all the cameras before processing.

It is recommended to set the "min-frames-batch-size" parameter value equal to the number of streams when using the GPU.

It is recommended to set the "min-frames-batch-size" parameter value equal to "2" when using the CPU.

<!-- min-frames-batch-size: stream frames min batch size value to process, ('0' by default). -->
<!-- higher values lead to higher processing latency but increase throughput and device utilization. -->
<!-- zero/negative values disable this feature, so any stream frames will be processed if they are available -->
<!-- note: this parameter should be regulated with 'max-frames-batch-gather-timeout' (see below) -->
<param name="min-frames-batch-size" type="Value::Int1" x="0" />

Max-frames-batch-gather-timeout parameter#

The "max-frames-batch-gather-timeout" parameter specifies the time between processing of the batches.

If a single frame is processed within the specified time and there is an additional time margin, FaceStream waits for additional frames to increase GPU utilization.

If the "max-frames-batch-gather-timeout" parameter is set to "20", this time is used to process the previous batch and collect a new one. After 20 seconds, the processing begins even if the number of frames equal to "min-frames-batch-size" was not collected. Processing of the next batch cannot begin before the processing of the previous one is finished.

There is no timeout for collecting frames to the batch if the parameter is set to "0" and "min-frames-batch-size" is ignored.

It is recommended to set the "max-frames-batch-gather-timeout" parameter value equal to "0" both when using the GPU and when using the CPU.

<!-- max-frames-batch-gather-timeout: max available timeout to gather next stream frames batch (see 'min-frames-batch-size') from last processing begin time point (measured in ms), ('-1' by default). -->
<!-- negative values disable this feature (no timeout, so only stream frames batches with size no less than 'min-frames-batch-size' value will be processed) -->
<!-- note: this parameter is complementary to 'min-frames-batch-size' and controls min average fps of stream frames batches processing -->
<param name="max-frames-batch-gather-timeout" type="Value::Int1" x="-1" />

LUNA Streams settings#

This section describes the parameters of the LUNA Streams service that are set in the LUNA Configurator service.

LUNA_STREAMS_DB section#

This section sets connection settings to the created LUNA Streams database.

Db_type parameter#

The parameter sets the type of database used. Two options are available - "postgres" or "oracle".

The default type is "postgres".

Db_user parameter#

The parameter specifies the database username.

The default username is "luna".

Db_password parameter#

The parameter sets the database password.

The default password is "luna".

Db_name parameter#

The parameter sets the database name for type "postgres" and the name of the SID for type "oracle" to connect to.

The default name is "luna_streams".

Db_host parameter#

The parameter sets the IP address of the server with the LUNA Streams database.

The default address is "127.0.0.1". This address means that the LUNA Streams database located on the server with LUNA Configurator will be used. If the database is located on another server, then in this parameter you should specify the correct IP address of the server with the database.

Db_port parameter#

The parameter sets LUNA Streams database listener port.

The default port is "5432" for "postgres" and "1521" for "oracle".

Connection_pool_size parameter#

The parameter sets the database connection pool size.

The default value is "5".

LUNA_STREAMS_LOGGER section#

This section sets the logging settings for the LUNA Streams service.

Log_level parameter#

The parameter sets the level of debug printing, by priority: "ERROR", "WARNING", "INFO", "DEBUG".

The default value is "INFO".

Folder_with_logs parameter#

The parameter sets the folder where the logs are stored (the relative path starts from the directory with the application).

The default value is "./".

Log_time parameter#

The parameter sets the time format used in log entries: "LOCAL" or "UTC".

The default value is "LOCAL".

Log_to_stdout parameter#

The parameter enables you to send the log to standard output (stdout). Two options are available - "true" or "false".

The default value is "true".

Log_to_file parameter#

The parameter enables you to send the log to a file. Two options are available - "true" or "false".

The default value is "false".

Multiline_stack_trace parameter#

The parameter enables or disables multi-line traces in logs. Two options are available - "true" or "false".

The default value is "true".

LUNA_LICENSES_ADDRESS section#

This section sets the settings for connecting to the LUNA Licenses service.

Origin parameter#

The parameter sets the protocol, IP address and port of the LUNA Licenses service. The IP address "127.0.0.1" means that the LUNA Licenses service located on the server with LUNA Configurator will be used. If the service is located on another server, then in this parameter you need to specify the correct IP address of the server running the LUNA Licenses service.

"origin": "http://127.0.0.1:5120",

The default value is "http://127.0.0.1:5120".

Api_version parameter#

This parameter sets the API version of the LUNA Licenses service. The available API version is "1".

STREAM_WORKER_ASYNC_LOCK_TIMEOUT parameter#

Parameter sets timeout of the LUNA Streams instance to lock a row in a database table in seconds in the range (0, 1]. The value of this setting should be increased if the stream statuses are not updated, which may be due to a slow connection from the service to the database.

The default value is "10".

STREAM_STATUS_OBSOLETING_PERIOD parameter#

This parameter sets stream status obsolescence period in seconds in range (0, 86400]. For this period of time, the FaceStream worker should transfer the LUNA Streams report. Otherwise, the status of the stream will be changed to "restart", and the belated report will be rejected.

The default value is "0.1".

LUNA_STREAMS_ACTIVE_PLUGINS parameter#

This parameter sets the list of active plugins (see the information about plugins workflow in the LUNA PLATFORM 5 administrator manual).

The default value is "[]".

STORAGE_TIME parameter#

This parameter sets time format used in LUNA Streams database records: "LOCAL" or "UTC".

The default value is "LOCAL".

INFLUX_MONITORING section#

In this section, settings for monitoring LUNA PLATFORM services are set.

Send_data_for_monitoring parameter#

This parameter enables you to enable or disable sending monitoring data to InfluxDB. Two options are available - "0" or "1".

The default value is "1".

Use_ssl parameter#

This parameter enables you to use HTTPS to connect to InfluxDB. Two options are available - "0" or "1".

The default value is "0".

Flushing_period parameter#

This parameter sets frequency of sending monitoring data to InfluxDB (in seconds).

The default is 1 second.

Host parameter#

This parameter sets IP address of server with InfluxDB 2.x.

The default address is "127.0.0.1". This address means that InfluxDB 2.x will be used, located on the server with LUNA Configurator. If InfluxDB 2.x is located on a different server, then you should specify the correct InfluxDB 2.x IP address in this parameter.

Port parameter#

This parameter sets InfluxDB 2.x port.

The default value is "8086".

Bucket parameter#

This parameter sets InfluxDB 2.x bucket name.

The default bucket name is "luna_monitoring".

Organization parameter#

This parameter sets InfluxDB 2.x workspace.

The default value is "luna".

Token parameter#

This parameter sets InfluxDB 2.x authentication token.