Overview

Phoenix system consists of several components: Phoenix, Camera Server and their dependencies. This manual describes installation process of Phoenix system and its settings.

Installation

Prepare Ubuntu 16.04

If you use CoreOS Linux you don’t need to follow steps in this section.
  • Install docker (version higher than 17.04). Use official manual to get instructions: https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-using-the-repository

  • Remove IPv6 records from /etc/hosts associated with hostname.

  • Install nvidia driver.

    sudo apt update
    sudo apt-get install nvidia-384
  • Reboot the system.

  • Install SAM util from deb-package

    wget http://dl.smilart.com/download.php?file=f2b73c1aa3eabc039c6097fe1caec148 -O sam-1.27.deb
    sudo  apt install ./sam-1.27.deb
  • Add Smilart repository to the SAM util

    sudo -i
    sam addrepo --default --name packages --server packages.smilart.com --username admin --password admin
  • Install base Smilart image

    sam install smilartos-install:1855.4.0_150
Now you can continue to install Phoenix system.

Because Phoenix system was not adapt to install on Ubuntu, you must to do following steps AFTER installation Phoenix system:

  • Check file /etc/hosts or check dns settings. Hostname mustn’t be resolved into 127.x.y.z.

  • The file /etc/hosts must contain the string: 172.17.0.1 <Hostname>

Online installation

  • Add Smilart repository to the SAM util (under root). Skip this step if you did it before.

    sam addrepo --default --name packages --server packages.smilart.com --username admin --password admin

Run installproduct command without parameters to run installation prouduct utility in interactive mode.

installproduct
To use this method your server must have internet connection. You should be ready to download about 5GB of data.
  • First window show the list of products. Choose Phoenix system;

  • Second window show the list of product versions. Choose 8.0.0 or another version which you want to install;

  • Confirm changes;

  • Wait finishing installation;

  • Reboot the system.

Products, installed before, will be removed.

Offline installation

Local registry method

Requirements: smilartos-install:1855.4.0_150

  • Install necessary version of registry-phoenix_system. The version of registry-phoenix_system must match with the version of Phoenix system which you want to install. To install _registry-phoenix_system from the Internet use command:

    sam in ./registry-phoenix_system-9.0.0_XX.tar.gz
You should write email to support@smilart.com to get file with _registry-phoenix_system.
Detail information about SAM util you can find in SAM util documentation.
  • Run installproduct localhost to start installation. Next steps are the same as in Online installation.

Remote registry method

This method provides to deploy registry on any computer and use it to install Phoenix system

docker must be installed on the computer where you want to deploy the registry.
  • Load file with registry into docker. Write request to support@smilart.com to get link to the file.

    docker load < <file>
  • Run registry

    docker run -d --name=smilart-registry -p 5000:5000 -p 5001:5001 smilart/registry-phoenix_system:9.0.0_XX
  • On the computer where you want to install Phoenix system you must turn on insecure mode for docker. To do that add { "insecure-registries":["<server address>:5000"] } setting to /etc/docker/daemon.json

  • Run installproduct with registry ip address.

    installproduct 192.168.10.56
  • Next steps are the same as in Online installation

Applications Launch Control

Once installed, the application will automatically start up and automatically restart in the event of an emergency shutdown. It will also start automatically when the server restarts.

To stop the application, you must execute the command:

$ systemctl stop phoenix

To start the application, you must execute the command:

$ systemctl start phoenix

To restart the application, you must execute the command:

$ systemctl restart phoenix

To view the status of the application (started, stopped, terminated with an error), you must execute the command:

$ systemctl status phoenix

To turn off the application autorun, execute the command:

$ systemctl disable phoenix

To turn on the application autorun, execute the command:

$ systemctl enable phoenix

Helper Scripts

After Phoenix System is installed, these scripts will be available on the server.

The Phoenix should be running.

Adaptive Verification

Delete all sampled photos:

$ phoenix_remove_all_sampled_photos

Delete all sampled photos by camera pid:

$ phoenix_remove_sampled_photos_by_camera <CameraPid>

Delete all sampled photos by person id:

$ phoenix_remove_sampled_photos_by_person <PersonId>

Configuration

Two components of Phoenix system need configuration: Phoenix and Camera Server

Phoenix configuration

Phoenix provides configuration capability via set of configuration files.

Sysconfig

Rationale: low level configuration file only for Tech Support staff.
File modification policy: overwritten by the system every time the system is installed.
Typical reasons to change this file: switch from GPU to CPU daemons or change the number of the daemon instances.
Location: /etc/phoenix/current/sys.config.orig.
File post-modification action: systemctl restart phoenix.

Text after %% is a comment

[
  {sml_phoenix, [

    {limiter, [
%%        {max_fps, 10} %% FPS limmit
    ]},

    {daemons, [
    %% Demons description format
    % {DaemonModule,
    %   {varied_daemons, #{
    %     daemons=>
    %     % List of configs for daemons (daemons numbers = configs number)
    %     [
    %       #{name=> "daemon_name", % Required!
    %         GenDaemonSettings
    %       },...
    %     ]
    %   }
    %   % OR
    %   {similar_daemons, #{
    %     % Numbers of Daemons
    %     count=> 3,
    %     % Config for all these daemons
    %     GenDaemonSettings
    %   }}
    %   % when GenDaemonSettings has next format
    %   logging=> {default, debug | info | warning | error} | without_spec_file |
    %     {manual, #{file=>"daemons/fd/fd_gpu_o.log"}}, % See 'log_tracing' config
    %   exec=> {docker, #{
    %     docker_image => "smilart/daemon.fd_mtcnn.cuda.x86_64:1.1.3",
    %     docker_opts => #{privileged => true},
    %     daemon_args => [{"gpu", 0}]
    %   }}
    % }

      {fd_mtcnn, {varied_daemons, #{
        daemons => [
          #{
            name => "fd_gpu_0",
            logging => {default, info},
            exec => {docker, #{
              docker_image => "smilart/daemon.fd_mtcnn.cuda.x86_64:1.1.3",
              docker_opts => #{
                privileged => true,
                volume_from => ["nvidia-driver:ro"],
                env => ["LD_LIBRARY_PATH=/usr/local/lib/nvidia/opengl/"]
              },
              daemon_args => [
                {"gpu", 0}
              ]
            }}
          }
        ]
      }}},
      {fr_kenya, {varied_daemons, #{
        daemons => [
          #{name => "fr_gpu_0",
            logging => {default, info},
            exec => {docker, #{
              docker_image => "smilart/daemon.fr_kenya.cuda.x86_64:2.1.0",
              docker_opts => #{
                privileged => true,
                volume_from => ["nvidia-driver:ro"],
                env => ["LD_LIBRARY_PATH=/usr/local/lib/nvidia/opengl/"]
              },
              daemon_args => [
                {"gpu", 0}
              ]
            }}
          }
        ],
        max_base_size=>300000
      }}},
      {fpf, {similar_daemons, #{
        count => 3,
        logging => {default, info},
        exec => {docker, #{
          docker_image => "smilart/daemon.fpf.cpu.x86_64:2.0.1",
          docker_opts => #{},
          daemon_args => [
            {"openmp-max-threads", 1}
          ]
        }}
      }}},
      {shm_writer, {similar_daemons, #{
        count => 3,
        logging=> {default, info},
        exec=> {docker, #{
          docker_image => "smilart/daemon.shm_writer.cpu.x86_64:5.0.1",
          daemon_args => []
        }}
      }}},
      %% The following daemons ignore "count" settings
      {exif_reader, {similar_daemons, #{
        logging=> {default, info},
        exec=> {docker, #{docker_image => "smilart/daemon.exif_reader.cpu.x86_64:3.0.1"}}
      }}},
      {exif_writer, {similar_daemons, #{
        logging=> {default, info},
        exec=> {docker, #{docker_image => "smilart/daemon.exif_writer.cpu.x86_64:3.0.1"}}
      }}},
      {shm_reader, {similar_daemons, #{
        logging=> {default, info},
        exec=> {docker, #{docker_image => "smilart/daemon.shm_reader.cpu.x86_64:3.1.0"}}
      }}}
    ]},

    {log_tracing, [
      %% {trace_name, #{
      %   file=> "PathToLogFile.log",
      %% Next opts applied by default
      %   config=> [{formatter, lager_default_formatter},
      %     {formatter_config, [date, " ", time, " ", message, "\r\n"]},
      %     {size, 104857600}, {date, ""}, {count, 4}
      %   ],
      %   level=> debug
      % }},

      {api_router_amqp, #{file => "amqp_api/router.log"}},
      {api_camera_amqp, #{file => "amqp_api/camera.log"}},
      {api_person_amqp, #{file => "amqp_api/person.log"}},
      {api_photobooth_amqp, #{file => "amqp_api/photobooth.log"}},
      {api_verification_amqp, #{file => "amqp_api/verification.log"}},
      {api_vca_amqp, #{file => "amqp_api/vca.log"}},
      {api_ipa_amqp, #{file => "amqp_api/ipa.log"}},
      {api_adaptive_verification_amqp, #{file => "amqp_api/adaptive_verification.log"}},

      {api_cameras, #{file => "erl_api/camera.log"}},
      {api_cameras_sup, #{file => "erl_api/cameras_sup.log"}},
      {api_person, #{file => "erl_api/person.log"}},
      {api_photobooth, #{file => "erl_api/photobooth.log"}},
      {api_photobooth_event_sender, #{file => "erl_api/photobooth_event_sender.log"}},
      {api_ipa, #{file => "erl_api/ipa.log"}},
      {api_vca, #{file => "erl_api/vca.log"}},
      {api_vca_event_sender, #{file => "erl_api/vca_event_sender.log"}},
      {api_verification, #{file => "erl_api/verification.log"}},
      {api_verification_core, #{file => "erl_api/verification_core.log"}},
      {api_verification_event, #{file => "erl_api/verification_event.log"}},
      {api_verification_event_sender, #{file => "erl_api/verification_event_sender.log"}},
      {api_persons_event_sender, #{file => "erl_api/persons_event_sender.log"}},
      {api_adaptive_verification, #{file => "erl_api/adaptive_verification.log"}},

      {camera_mjpeg_stream, #{file => "http_api/camera_mjpeg_stream.log"}},
      {adaptive_verification_info, #{file => "adaptive_verification_info.log"}},
      {license, #{file => "license.log"}},
      {config, #{file => "config.log"}},
      {vitality, #{file => "vitality.log"}},
      {db_sync_service, #{file => "person_base_init.log"}}
    ]}
  ]},

  {sml_docker, [
    % {daemon_socket, "/var/run/docker.sock"} %% Path to docker.sock
  ]},

  {sml_multicast, [
    {reciver_opts, [
      {ip, {239, 10, 11, 12}},
      {port, 50000}
    ]},
    {sender_opts, [
      {ip, {239, 10, 11, 13}},
      {port, 50001}
    ]}
  ]},

  {sml_event_tracer, [ %% System events publishing
%    {tracing, {zipkin, [
%      {host, "${zipkin_host}"},
%      {tick_time, 1000},
%      {service_name, "phoenix"}
%    ]}},
    {event_sender, {influx_udp, [
      {host, "${influx_host}"},
      {port, 4444},
      {pool_size, 5},
      {max_overflow, 10}
    ]}}
  ]},

  {lager, [
    {log_root, "log"},
    {async_threshold, 100},
    {async_threshold_window, 25},
    {crash_log_size, 104857600},
    {crash_log_date, ""},
    {crash_log_count, 4},
    {handlers, [
%%      {lager_console_backend, error},
%%      {lager_file_backend, [{file, "debug.log"}, {level, debug}, {size, 104857600}, {date, ""}, {count, 4}]},
      {lager_file_backend, [{file, "info.log"}, {level, info}, {size, 104857600}, {date, ""}, {count, 4}]},
      {lager_file_backend, [{file, "warning.log"}, {level, warning}, {size, 104857600}, {date, ""}, {count, 4}]},
      {lager_file_backend, [{file, "error.log"}, {level, error}, {size, 104857600}, {date, ""}, {count, 4}]}
    ]},
    {extra_sinks, [
      {sml_lager_lager_event, [
        {async_threshold, 100},
        {async_threshold_window, 25}
      ]}
    ]}
  ]},
  {sasl, [
%    {sasl_error_logger, {file, "fdcam_sasl.log"}}
    {sasl_error_logger, false}
  ]}
].
Daemons

In this section gathered settings related to daemons. Each daemon has its own parameters set. Configuring a daemon may require professional assistance.

Name

Type

Description

fr_kenya.varied_daemons.daemons

object

fr_kenya daemon startup parameters. Number of daemons equals list size.

fd_mtcnn.varied_daemons.daemons

object

fd_mtcnn daemon startup parameters. Number of daemons equals list size.

fpf.similar_daemons.count

integer

Number of fpf daemons that will be started.

Example Config

Rationale: exploration of the default options and configuration scheme.
File modification policy: overwritten by the system every time the system is started.
Typical reasons to change this file: none, the content of this file does not affect the operation of the system.
Location: /etc/phoenix/config/example.config.
File post-modification action: none.

Text after %% is a comment

%% Workflow options.
{workflow, [
  {verification_and_identification, [
    {write_to_shm, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {write_exif, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {detect, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {create_template, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]}
  ]},

  {verification, [
    {correlation, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000},

      %% The value should have 'integer' type. Min value: 1.
      {limit,3}
    ]}
  ]},

  {photobooth, [
    {write_to_shm, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {write_exif, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {fpf, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]},

    {detect, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000}
    ]}
  ]},

  {identification, [
    %% The value should have 'float' type. Min value: 0. Max value: 1.
    {threshold,0.6},

    {correlation, [
      %% The value should have 'integer' type. Min value: 500.
      {request_timeout_ms,1000},

      %% The value should have 'integer' type. Min value: 1.
      {limit,10}
    ]}
  ]}
]}.

%% Http services options(blobstore and mjpeg).
{web_server, [
  %% The value should have 'integer' type. Min value: 1. Max value: 1000000.
  {port,"${BLOBSTORE_PORT}"},

  %% The value should have 'string' type. Min length: 1.
  {hostname,"${cowboy_host}"}
]}.

%% Photobooth Service options.
{photobooth, [
  %% The value should have 'integer' type. Min value: 1.
  {sampling_time_limit_seconds,20},

  %% The value should have 'mixed' type.
  {partitioning_scheme,{grid3x3,[
    %% The value should have 'enumeration' type. Possible values: [cross,horizontal,forward_turn,all_inner_poses].
    {stratums_of_interest,cross},

    %% The value should have 'mixed' type.
    {stratum_sampling,{rook,[
      %% The value should have 'float' type. Min value: 0. Max value: 1.
      {min_stratum_coverage_ratio,0.4}
    ]}},

    %% The value should have 'integer' type. Min value: 0. Max value: 90.
    {outer_square_side_size,60},

    %% The value should have 'integer' type. Min value: 0. Max value: 90.
    {inner_square_side_size,20}
  ]}},

  {fpf_extended_check, [
    %% The value should have 'integer' type. Min value: 0. Max value: 60.
    {max_angle_deviation_degrees,4},

    %% The value should have 'float' type. Min value: -1. Max value: 1.
    {face_quad_scaling_ratio,-0.05}
  ]}
]}.

%% Person Management Service options.
{person_management, [
  %% FR request settings.
  {fr_request_settings, [
    %% Maximum response time.
    %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
    {request_timeout_ms,1000}
  ]},

  %% FD request settings.
  {fd_request_settings, [
    %% Maximum response time.
    %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
    {request_timeout_ms,1000},

    {mtcnn, [
      %% The value should have 'float' type. Min value: 0. Max value: 1.
      {refine_net_threshold,0.9},

      %% The value should have 'float' type. Min value: 0. Max value: 1.
      {proposal_net_threshold,0.8},

      %% The value should have 'float' type. Min value: 0. Max value: 1.
      {output_net_threshold,0.9}
    ]},

    %% Minimum face quad side size.
    %% The value should have 'integer' type. Min value: 100. Max value: 1000000.
    {min_face_side_px,100},

    %% Maximum number of faces in FD response.
    %% The value should have 'integer' type. Min value: 1. Max value: 1000000.
    {max_searched_faces_on_frame,1000000},

    %% Maximum face quad side size.
    %% The value should have 'integer' type. Min value: 100. Max value: 1000000.
    {max_face_side_px,1000000}
  ]},

  %% Exif Writer request settings.
  {exif_writer_request_settings, [
    %% Maximum response time.
    %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
    {request_timeout_ms,1000}
  ]},

  %% Exif Reader request settings.
  {exif_reader_request_settings, [
    %% Maximum response time.
    %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
    {request_timeout_ms,1000}
  ]}
]}.

%% Full path to license.
%% The value should have 'string' type. Min length: 1.
{path_to_license,"/var/lib/smilart_srv/license/license"}.

%% Instant Photo Analytics Service options.
{ipa, [
  %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
  {request_timeout_ms,5000},

  %% The value should have 'integer' type. Min value: 1. Max value: 200.
  {queue_size,20},

  {identification, [
    %% The value should have 'float' type. Min value: 0. Max value: 1.
    {threshold,0.6}
  ]},

  {detect, [
    {fd_request_settings, [
      %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
      {request_timeout_ms,1000},

      {mtcnn, [
        %% The value should have 'float' type. Min value: 0. Max value: 1.
        {refine_net_threshold,0.9},

        %% The value should have 'float' type. Min value: 0. Max value: 1.
        {proposal_net_threshold,0.8},

        %% The value should have 'float' type. Min value: 0. Max value: 1.
        {output_net_threshold,0.9}
      ]},

      %% The value should have 'integer' type. Min value: 100. Max value: 1000000.
      {min_face_side_px,100},

      %% The value should have 'integer' type. Min value: 1. Max value: 1000000.
      {max_searched_faces_on_frame,1000000},

      %% The value should have 'integer' type. Min value: 100. Max value: 1000000.
      {max_face_side_px,1000000}
    ]},

    {exif_writer_request_settings, [
      %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
      {request_timeout_ms,1000}
    ]},

    {exif_reader_request_settings, [
      %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
      {request_timeout_ms,1000}
    ]},

    %% The value should have 'integer' type. Min value: 1. Max value: 1000000.
    {default_faces_limit,1000000}
  ]},

  %% The value should have 'integer' type. Min value: 1. Max value: 200.
  {count_workers,10},

  {correlation, [
    {fr_request_settings, [
      %% The value should have 'integer' type. Min value: 500. Max value: 1000000.
      {request_timeout_ms,1000},

      %% The value should have 'integer' type. Min value: 1. Max value: 1000000.
      {correlations_limit,10}
    ]}
  ]}
]}.

%% Identification options.
{identification, [
  %% The value should have 'integer' type. Min value: 1.
  {max_base_size,300000}
]}.

%% Persons storage options.
{database, [
  %% The value should have 'mixed' type.
  {installation_type,{master,[]}},

  %% The value should have 'mixed' type.
  {implementation,{mongodb,[
    %% The value should have 'string' type. Regular expression to check value: ^mongodb://.*.
    {uri,"mongodb://${mongodb_host}/smilart?readPreference=nearest"}
  ]}}
]}.

%% Camera Server connection options.
{camera_server, [
  %% Erlang Node name.
  %% The value should have 'string' type. Min length: 1.
  {node,"sml_camserver@camera_server"},

  %% Minimum time between reconnections.
  %% The value should have 'integer' type. Min value: 1.
  {min_resubscribe_timeout_ms,100},

  %% Maximum time between reconnections.
  %% The value should have 'integer' type. Min value: 1.
  {max_resubscribe_timeout_ms,60000},

  %% The value should have 'list' type. Min length: 1. List element type: (The value should have 'string' type. Min length: 1.).
  {groups,["phoenix"]},

  %% Cookie.
  %% The value should have 'string' type. Min length: 1.
  {cookie,"sml_camserver"}
]}.

%% Rules for camera groups.
%% The value should have 'list' type. List element type: (The value should have 'config' type. ).
{camera_rules,[]}.

%% In-memory blob storage.
{blobstore, [
  %% The value should have 'integer' type. Min value: 1000.
  {timeout_ms,30000},

  %% The value should have 'integer' type. Min value: 1024.
  {size_byte,52428800}
]}.

%% Amqp Api options.
{amqp_api, [
  {verification_event, [
    %% The value should have 'integer' type. Min value: 1000.
    {session_timeout_ms,30000},

    %% The value should have 'string' type. Min length: 1.
    {exchange_type,"direct"},

    %% The value should have 'string' type. Min length: 1.
    {exchange_name,"platform-api.verification"}
  ]},

  {verification, [
    %% The value should have 'integer' type. Min value: 1.
    {max_verification_timeout_seconds,30}
  ]},

  {vca, [
    %% The value should have 'integer' type. Min value: 1000.
    {session_timeout_ms,30000},

    %% The value should have 'string' type. Min length: 1.
    {exchange_type,"direct"},

    %% The value should have 'string' type. Min length: 1.
    {exchange_name,"platform-api.vca"}
  ]},

  {router, [
    %% The value should have 'string' type. Min length: 1.
    {routing_key,"#"},

    %% The value should have 'string' type. Min length: 1.
    {exchange_type,"fanout"},

    %% The value should have 'string' type. Min length: 1.
    {exchange_name,"platform-api"}
  ]},

  {photobooth, [
  ]},

  %% The parameter is responsible for the activity of the service.
  %% The value should have 'boolean' type.
  {enable,true},

  {amqp_settings, [
    %% The value should have 'string' type. Min length: 1.
    {user,"guest"},

    %% The value should have 'string' type. Min length: 1.
    {password,"guest"},

    %% The value should have 'string' type. Min length: 1.
    {host,"${rabbitmq_host}"}
  ]}
]}.

%% Adaptive Verification Service options.
{adaptive_verification, [
  %% Options for setting verification thresholds.
  {thresholds, [
    %% Type of photo selection.
    %% The value should have 'enumeration' type. Possible values: [person_photos_per_camera,all_person_photos].
    {selection_type,person_photos_per_camera},

    %% The influence of the selection size on the threshold name during verification.
    %% The value should have 'list' type. Min length: 1. List element type: (The value should have 'string' type. Min length: 1.). Can consist duplicated elements.
    {selection_size_to_verification_threshold_names,["UltraLow","Low","Normal"]}
  ]},

  {scoring, [
    %% The value should have 'integer' type. Min value: 0.
    {init_photo_time_score_sec,864000},

    %% The value should have 'integer' type. Min value: 0.
    {correlation_deviation_weight,80}
  ]},

  %% Restricting of the sampling of photos to add to a person.
  {sampling_restrictions, [
    %% The minimum time between adding a photo to a person for a camera.
    %% The value should have 'integer' type. Min value: 1.
    {sampling_throttle_sec,7200}
  ]},

  {photo_validation, [
    {fpf_check, [
      %% The value should have 'integer' type. Min value: 0. Max value: 60.
      {yaw,35},

      %% The value should have 'integer' type. Min value: 0. Max value: 60.
      {roll,30},

      %% The value should have 'integer' type. Min value: 0. Max value: 60.
      {pitch,25},

      %% The value should have 'integer' type. Min value: 0. Max value: 60.
      {max_angle_deviation_degrees,4},

      %% The value should have 'float' type. Min value: -1. Max value: 1.
      {face_quad_scaling_ratio,-0.05}
    ]}
  ]},

  %% The maximum number of photos that can be added to a person from one camera.
  %% The value should have 'integer' type. Min value: 1. Max value: 100.
  {max_photos_per_camera,5},

  %% The parameter is responsible for the activity of the service.
  %% The value should have 'boolean' type.
  {enable,false}
]}.
Adaptive Verification (adaptive_verification)

The following formula is used to calculate the score of a sampled photo:

score = init_photo_time_score_sec + last_verification_time_sec - now_sec + (correlation_deviation_weight * (average_verification_coeff - get_threshold_by_name("high")) + number_of_successful_verifications) * 86400

if score is less than 0 then this photo can be replaced by Adaptive Verification.

Name

Type

Description

enable

boolean

The parameter is responsible for the activity of the service.

thresholds

object

Options for setting verification thresholds.

thresholds.selection_type

enumeration

Type of photo selection, available values: person_photos_per_camera,all_person_photos.

thresholds.selection_size_to_verification_threshold_names

array of strings

The influence of the selection size on the threshold name during verification.

scoring

object

Options for scoring of sampled photos.

scoring.init_photo_time_score_sec

integer

Parameter used in calculating the score.

scoring.correlation_deviation_weight

integer

Parameter used in calculating the score.

sampling_restrictions

object

Restrictions settings for adding sampled photos.

sampling_restrictions.sampling_throttle_sec

integer

The minimum time between adding sampled photos for one camera per person.

photo_validation

object

Options for photo validation.

photo_validation.fpf_check

object

Options for fpf photo validation.

photo_validation.fpf_check.yaw

integer

The maximum deviation of the yaw angle from the central angle.

photo_validation.fpf_check.roll

integer

The maximum deviation of the roll angle from the central angle.

photo_validation.fpf_check.pitch

integer

The maximum deviation of the pitch angle from the central angle.

photo_validation.fpf_check.max_angle_deviation_degrees

integer

The maximum angle deviation from second result of fpf.

photo_validation.fpf_check.face_quad_scaling_ratio

float

Face scaling ratio option to get second result of fpf.

max_photos_per_camera

integer

The maximum number of photos that can be added to a person from one camera.

Amqp Api (amqp_api)

Parameters:

Name

Type

Description

enable

boolean

The parameter is responsible for the activity of the service.

amqp_settings

object

Connection settings for RabbitMQ

amqp_settings.host

string

RabbitMQ Host

amqp_settings.user

string

RabbitMQ User

amqp_settings.password

string

RabbitMQ Password

router

object

RPC Amqp Api options

router.routing_key

string

Routing key for Api

router.exchange_name

string

Name of exchange for Api

router.exchange_type

string

Type of exchange for Api

vca

object

Amqp VCA options

vca.exchange_name

string

Name of exchange

vca.exchange_type

string

Type of exchange

vca.session_timeout_ms

integer

The lifetime of a session without renewing subscription

verification

object

Amqp VCA options

verification.max_verification_timeout_seconds

integer

Maximum waiting time for a positive verification result

verification_event

object

Amqp Verification Event publishing Options

verification_event.exchange_name

string

Name of exchange

verification_event.exchange_type

string

Type of exchange

verification_event.session_timeout_ms

integer

The lifetime of a session without renewing subscription

Blobstore (blobstore)

Name

Type

Description

timeout_ms

integer

Maximum time to store a single item

size_byte

integer

Storage capacity

CameraServer (camera_server)

Name

Type

Description

node

string

Camera server node name in {NAME}@{HOST} format

cookie

string

Camera server erlang cookie.

min_resubscribe_timeout_ms

integer

Minimum interval between attempts to connect to camera server.

max_resubscribe_timeout_ms

integer

Maximum interval between attempts to connect to camera server.

groups

array of strings

Groups of cameras with which phoenix works.

Database (database)

Name

Type

Description

implementation

object

Database implementation used

installation_type

object

Installation type used

Implementation (implementation)

implementation is a type of database used in Phoenix. It can be one of those types:

  • mongodb — Default choice. It’s highly advisable to use this database.

  • memory — Stores data in memory, empties itself on restart. Can be used for a small dataset.

MongoDB settings

Name

Type

Description

uri

string

MongoDB connection string

URI string format:

mongodb://[username:password@]host1[:port1][,host2[:port2],…​[,hostN[:portN]]][/[database][?options]]

Available options:

Name

Type

w

custom

readPreference

enumeration

journal

bool

localThresholdMS

integer

connectTimeoutMS

integer

socketTimeoutMS

integer

serverSelectionTimeoutMS

integer

waitQueueTimeoutMS

integer

heartbeatFrequencyMS

integer

minPoolSize

integer

minHeartbeatFrequencyMS

integer

maxPoolSize

integer

wtimeoutMS

Installation Type (installation_type)

Type of Phoenix installation:

  • master — In this mode Phoenix node has exclusive access to person database manipulation. Available for any database type. Propagation of changes from the database to the entire system takes a finite time. In most cases this is almost instantaneous;

  • slave — In this mode Phoenix node synchronizes its state with database once in sync_timeout_sec seconds, and prohibited from manipulating person database. Propagation of changes from the database to the entire system is similar to eventual consistency. In most cases this takes about sync_timeout_sec seconds.

Slave options

Name

Type

Description

sync_timeout_sec

integer

Interval between synchronization attempts

Cluster mode settings:

To configure Phoenix in cluster mode one Phoenix must be chosen as a master node and will have the ability to manipulate persons. Machine with master Phoenix instance should also host master MongoDB instance.

To configure Phoenix instance as master`readPreference` parameter for this instance must be set to primary. Also this Phoenix instance must be connected to master node of MongoDB.

Hostname in MongoDB connection URI must be the same as a name of this MongoDB instance in cluster.
In cluster mode only one Phoenix master instance is allowed.

All other Phoenix instances must be configured in slave mode.

Identification (identification)

Name

Type

Description

max_base_size

integer

Maximum number of photos that can be loaded into face recognition daemon.

Instant Photo Analytics (ipa)

This section contains IPA settings.

Name

Type

Description

count_workers

integer

Number of workers to process requests parallel.

queue_size

integer

Request queue size.

request_timeout_ms

integer

Maximum response time in milliseconds.

detect

object

Detect settings.

detect.default_faces_limit

integer

Default number of faces to search for.

detect.fd_request_settings

object

FD request settings.

detect.fd_request_settings.max_searched_faces_on_frame

integer

Max number of faces in FD response.

detect.fd_request_settings.min_face_side_px

integer

Minimum face quad side size.

detect.fd_request_settings.max_face_side_px

integer

Maximum face quad side size.

detect.fd_request_settings.request_timeout_ms

integer

Maximum FD response time in milliseconds.

detect.fd_request_settings.mtcnn

object

MTCNN face detector options.

detect.fd_request_settings.mtcnn.proposal_net_threshold

float

MTCNN threshold for the proposal net.

detect.fd_request_settings.mtcnn.refine_net_threshold

float

MTCNN threshold for the refine net.

detect.fd_request_settings.mtcnn.output_net_threshold

float

MTCNN threshold for the output net.

detect.fpf_request_settings

object

FPF request settings.

detect.fpf_request_settings.request_timeout_ms

integer

Maximum FPF response time in milliseconds.

detect.exif_writer_request_settings

object

ExifWriter request settings.

detect.exif_writer_request_settings.request_timeout_ms

integer

Maximum ExifWriter response time in milliseconds.

detect.exif_reader_request_settings

object

ExifReader request settings.

detect.exif_reader_request_settings.request_timeout_ms

integer

Maximum ExifReader response time in milliseconds.

correlation

object

Correlation settings.

correlation.fr_request_settings

object

FR request settings.

correlation.fr_request_settings.correlations_limit

integer

Maximum number of correlations included in the correlation result.

correlation.fr_request_settings.request_timeout_ms

integer

Maximum FR response time in milliseconds.

identification

object

Identification settings.

identification.threshold

float

Identification threshold.

Person Management (person_management)

This section contains Person Management Service settings.

Name

Type

Description

exif_reader_request_settings

object

ExifReader request settings.

exif_reader_request_settings.request_timeout_ms

integer

Maximum ExifReader response time in milliseconds.

exif_writer_request_settings

object

ExifWriter request settings.

exif_writer_request_settings.request_timeout_ms

integer

Maximum ExifWriter response time in milliseconds.

fr_request_settings

object

FR request settings.

fr_request_settings.request_timeout_ms

integer

Maximum FR response time in milliseconds.

fd_request_settings

object

FD request settings.

fd_request_settings.request_timeout_ms

integer

Maximum FD response time in milliseconds.

fd_request_settings.max_searched_faces_on_frame

integer

Maximum number of faces in FD response.

fd_request_settings.min_face_side_px

integer

Minimum face quad side size.

fd_request_settings.max_face_side_px

integer

Maximum face quad side size.

fd_request_settings.mtcnn

object

MTCNN face detector options.

fd_request_settings.mtcnn.proposal_net_threshold

float

MTCNN threshold for the proposal net.

fd_request_settings.mtcnn.refine_net_threshold

float

MTCNN threshold for the refine net.

fd_request_settings.mtcnn.output_net_threshold

float

MTCNN threshold for the output net.

Photobooth (photobooth)

This section contains photobooth settings.

Name

Type

Description

partitioning_scheme

object

See below.

sampling_time_limit_seconds

integer

Maximum time photobooth will gather detects before it yelds result.

fpf_extended_check

object

Options for extended check.

fpf_extended_check.max_angle_deviation_degrees

integer

The maximum angle deviation from second result of fpf.

fpf_extended_check.face_quad_scaling_ratio

float

Face scaling ratio option to get second result of fpf.

partitioning_scheme grid3x3:

Name

Type

Description

stratums_of_interest

enumeration

Areas of interest, available values: cross, horizontal, forward_turn, all_inner_poses

stratum_sampling

object

Type of stratum sampling.

outer_square_side_size

integer

The size of the outer square of the partitioning scheme.

inner_square_side_size

integer

the size of the inner square of the partitioning scheme.

stratum_sampling rook

Name

Type

Description

min_stratum_coverage_ratio

float

Minimum stratum coverage ratio

WebServer (web_server)

Name

Type

Description

hostname

string

Name of a host that will be used in urls generated by Phoenix

port

integer

Port to access blobstore

If you change port in Phoenix setting you also need to change this port forwarding in systemd service file.
Workflow (workflow)

This section contains settings for Workflow.

Name

Type

Description

verification_and_identification

object

Verification and Identification settings.

verification_and_identification.write_to_shm

object

Write to shm request settings.

verification_and_identification.write_to_shm.request_timeout_ms

integer

Maximum response time in milliseconds.

verification_and_identification.detect

object

Detect request settings.

verification_and_identification.detect.request_timeout_ms

integer

Maximum response time in milliseconds.

verification_and_identification.write_exif

object

Write exif request settings.

verification_and_identification.write_exif.request_timeout_ms

integer

Maximum response time in milliseconds.

verification_and_identification.create_template

object

Create template request settings.

verification_and_identification.create_template.request_timeout_ms

integer

Maximum response time in milliseconds.

identification

object

Identification settings.

identification.threshold

float

Identification threshold.

identification.correlation

object

Correlation request settings.

identification.correlation.request_timeout_ms

integer

Maximum response time in milliseconds.

identification.correlation.limit

integer

Maximum number of correlations included in the correlation result.

verification

object

Verification settings.

verification.correlation

object

Correlation request settings.

verification.correlation.request_timeout_ms

integer

Maximum response time in milliseconds.

verification.correlation.limit

integer

Maximum number of correlations included in the correlation result.

photobooth

object

Photobooth settings.

photobooth.write_to_shm

object

Write to shm request settings.

photobooth.write_to_shm.request_timeout_ms

integer

Maximum response time in milliseconds.

photobooth.write_exif

object

Write exif request settings.

photobooth.write_exif.request_timeout_ms

integer

Maximum response time in milliseconds.

photobooth.detect

object

Detect request settings.

photobooth.detect.request_timeout_ms

integer

Maximum response time in milliseconds.

photobooth.fpf

object

FPF request settings.

photobooth.fpf.request_timeout_ms

integer

Maximum response time in milliseconds.

Camera rules (camera_rules)

Frame processing options by camera groups.

Please contact to Tech Support to change this options.

Options example:

{camera_rules, [
  #{
    one_of=>["phoenix"],
    then_apply=>#{
      fd=>#{
        min_face_side_px=>100,
        max_face_side_px=>1000000,
        max_searched_faces_on_frame=>1000000,
        mtcnn=>#{
          proposal_net_threshold=>0.8,
          refine_net_threshold=>0.9,
          output_net_threshold=>0.9
        }
      }
    }
  }
]}.

%% or

{camera_rules, [
  [
    {one_of, ["phoenix"]},
    {then_apply,[
      {fd,[
        {min_face_side_px,100},
        {max_face_side_px,1000000},
        {max_searched_faces_on_frame,1000000},
        {mtcnn,[
          {proposal_net_threshold,0.8},
          {refine_net_threshold,0.9},
          {output_net_threshold,0.9}
        ]}
      ]}
    ]}
  ]
]}.
Properties

Property Name

Value Type

Description

camera_rules

array

Ordered list of rules for frames processing for VCA and Verification services. First matching rule will be applied.

camera_rules[].one_of

array of strings

If camera belongs to one of these specified groups.

camera_rules[].then_apply

object

Then following options for frames processing will be applied.

camera_rules[].then_apply.fd

object

FD options.

camera_rules[].then_apply.fd.min_face_side_px

integer

Minimum face quad side size. default: 100, min: 100, max: 1000000.

camera_rules[].then_apply.fd.max_face_side_px

integer

Maximum face quad side size. default: 1000000, min: 100, max: 1000000.

camera_rules[].then_apply.fd.max_searched_faces_on_frame

integer

Max number of faces in FD response. default: 1000000, min: 1, max: 1000000.

camera_rules[].then_apply.fd.mtcnn

nested object

MTCNN face detector options.

camera_rules[].then_apply.fd.mtcnn.proposal_net_threshold

float

MTCNN threshold for the proposal net.

camera_rules[].then_apply.fd.mtcnn.refine_net_threshold

float

MTCNN threshold for the refine net.

camera_rules[].then_apply.fd.mtcnn.output_net_threshold

float

MTCNN threshold for the output net.

Basically face detection works in three steps. First, it searches for faces with face quad in [minFaceSizePx, maxFaceSizePx] and sorts faces found by size. Second, it applies maxSearchedFacesOnFrame and chooses only the biggest faces. And last, it confirms faces chosen in step two and because of this some faces can be discarded.

If there are three faces on frame and maxSearchedFacesOnFrame is equal to 1 and the biggest face would not be confirmed then the answer with no faces on frame will be received.
  • Decrease of maxFaceSizePx or maxSearchedFacesOnFrame parameters will reduce the number of detected faces and face detection time.

  • Increase of minFaceSizePx parameter will reduce the number of detected faces and face detection time.

  • Increase any of MTCNN thresholds will reduce the number of detected faces and face detection time.

Current Config

Rationale: preserve configuration changes between system updates. In the case of an empty file all system options will be set by default, which were displayed by the system in the Example Config.
File modification policy: each time the system starts up, it tries to preserve meaningfull specified options (except the unknown options) in this file, but can change its structure, which shouldn’t affect the desired behavior of the system.

Some changes to the service states that should be saved upon restart are also saved to this file.

Typical reasons to change this file: change system wide options for a regular system administrator.
Location: /etc/phoenix/config/current.config.
File post-modification action: systemctl restart phoenix.

Face Recognition Customization file

Rationale: preserve the recognition options associated with a particular version of the recognition (defined in the file name: fr-<version>.json) between system updates.
File modification policy: creates and fullfills with default values by the system if not exists.
Typical reasons to change this file: change recongition thresholds, define new threshold names in the system.

Please contact to Tech Support to change the options in this file and in the case of modification of the file associated with another version of recognition.

Location: /etc/phoenix/customizations/fr-3.json.
File post-modification action: systemctl restart phoenix.

File scheme:

{
  "defaultVerificationThreshold":float
  "verificationThresholds": {
     <thresholdName>:float
  }
}
Properties

Property Name

Value Type

Description

defaultVerificationThreshold

float

Default thresholds for verification. Will be used if no verification threshold name was specified in request.

verificationThresholds

object

Custom thresholds map for verification.

verificationThresholds.<thresholdName>

float

Defines verification threshold with name thresholdName.

It highly recommended to create new items in verificationThresholds instead of overriding defaultVerificationThreshold.

Camera Server configuration

You can manage Camera Server through Camera Server Admin Panel.

To access Admin Panel go to http://<your_server>:8082/ (you can change the port in Camera Server config)

By default there is no authorization for Admin Panel, but it is possible to add some.

  1. By using Nginx basic authorization.

  2. By using Keycloak (https://www.keycloak.org/).

Secure Admin Panel by Nginx basic access authentication

For instance we want to have access to Admin Panel by http://nginx-address/cs/. And assume that Nginx can get Admin Panel by http://192.168.1.39:8082

To get that you have to change file (/etc/nginx/nginx.conf) by adding location rules to your http server which on port 80.

#...
http {
#...
server {
    listen       80;
#...

# Next rule is to get Admin Panel resources files
location /cs/ {
    proxy_pass http://192.168.1.39:8082/; # note the trailing slash!
}

# Next used for interanl Camera Server API
location /cs/api/csi {
    proxy_pass http://192.168.1.39:8082/api/csi;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 2073600; #maximum supported is 24 days
}

#...
}
}
#...
Applying changes in the config needs restart Nginx by systemctl restart nginx.

After that follow next steps to close Camera Server Admin Panel port:

1) Create file /var/lib/iptables/rules-save and edit like in example below.

*filter
-A INPUT -p tcp -m tcp --dport 8082 -j DROP
COMMIT

2) Enable iptables-restore systemctl enable iptables-restore.

3) Reboot.

Secure Admin Panel by Keycloak

Change Camera Server config parameter admin_panel (/etc/camera_server/current/sys.config.orig).

% - makes comment until end of line
% ...
    {admin_panel, [
      %% {authentication, none | {keycloak, [ ...]} }
      {authentication,
        {keycloak, [
          {host, "${keycloak_host}"},
          {port, 8080},
          {role, "cs_admin"},
          {client_id, "cs_admin_panel"},
          {realm, "smilart"}
        ]}
      },
      {port, "${ADMIN_PANEL_PORT}"}
    ]},
% ...
Properties

Name

Type

Description

admin_panel

object

Settings for Admin Panel.

admin_panel.port

integer

Admin Panel port. By default will get from env. ${ADMIN_PANEL_PORT}, which is 8082 by default.

admin_panel.authentication

object

Can be none or keycloak.

admin_panel.authentication.keycloak.host

string

Host name of Keycloak. By default will get from env. ${keycloak_host}, which is hostname of station with the Camera Server.

admin_panel.authentication.keycloak.port

integer

Port of Keycloak. By default 8080.

admin_panel.authentication.keycloak.role

string

Required role of Keycloak user to access Admin Panel. By default cs_admin.

admin_panel.authentication.keycloak.client_id

string

Name of Keycloak 'Client' for Admin Panel. By default cs_admin_panel.

admin_panel.authentication.keycloak.realm

string

Keycloak realm to use. By default smilart.

If you change Admin Panel port you also need to change this port forwarding in systemd unit file (/etc/systemd/system/camera_server.service).
Host name and port of Keycloak must be reachable from camera_server docker container and from client side of Admin Panel.
Applying changes in the config needs restart Camera Server by systemctl restart camera_server.

Camera Server Admin Panel

User interface for administration of Camera Server.

Provides capabilities:

  • Add/Configure/Delete MJPEG, RTSP, Basler cameras.

  • View live stream from camera.

  • View license information.

  • View actual information about cameras.

image
Figure 1. Main page
image
Figure 2. Panel of MJPEG camera
image
Figure 3. Panel of RTSP camera
image
Figure 4. Panel of Basler camera