Milestone XProtect Integration (U-Filter)

A tutorial is available in video format as well, here: https://youtu.be/94CzSsepyJ4

Before you start

In this guide it is assumed that Milestone XProtect is installed on a computer in your network, and you know how to configure it when using it without U-Filter. For further details, please visit the official site of Milestone.

Requirements:

• U-Filter Server is up and running and reachable from the computer network where Milestone XProtect is running. The network address of the U-Filter server is required for the process.
• Please make sure that each camera you would like to utilise U-Filter is registered in Milestone XProtect, as described in the Milestone documentation.
• You have administrator privileges on the device running Milestone XProtect (both for Windows and within Milestone XProtect).
• If using the Essential+ edition of Milestone XProtect: make sure that the machine running Milestone XProtect is able to reach the Milestone License servers, as the Essential+ edition lacks an offline activation method.

I. Install the U-Filter Milestone Plugin

NOTE: Before installing the U-Filter Plugin for Milestone XProtect, make sure to close both Milestone XProtect Smart Client and Milestone XProtect Management Client for all logged-in users. Do the same for the U-Filter Plugin when upgrading to newer versions of it.

1. Download the U-Filter Plugin installer from https://assets.ultinous.com/ufilter/U-Filter_installer_1.1.1.exe to the computer on which Milestone XProtect is installed.

2. Close Milestone XProtect and any Milestone services running on the computer.

3. Start the installer.

   

4. Go through the installation steps. It is recommended to create a desktop shortcut.

   NOTE: If you did not close Milestone XProtect before, the installer can try to close them. If closing some of these services is unsuccessful, retry it until it succeeds or close them manually (in the Windows Task Manager, for instance).

   

5. After the installation is complete you can launch the U-Filter Manager. Its icon will be visible on the system tray.

   

6. The icon indicates the following states:

• Running
• Pending
• Stopped

II. Give access to Milestone XProtect

U-Filter requires access to Milestone XProtect, therefore a new user should be created with administrator privileges.

II. a. Create a User in Milestone XProtect

1. Open the Milestone XProtect Management Client.

2. Go to the Site Navigation panel => Security => Roles.

3. Click on Administrators in the Roles panel.

4. Find the Users and Groups tab at the bottom of the Role Settings panel. Click the Add... dropdown and select the Basic user option.

5. In the Select Basic Users to add to Role pop-up, click the New button.
6. A new pop-up appears. Fill in the form with new user credentials and click OK. Use a complex password with capital and small letters, numbers and special characters. Remember the password, as it will be used later in the U-Filter Manager.

7. Add this basic user to the Administrators by clicking OK.

II. b. Set the credentials for the U-Filter Plugin

1. Start the U-Filter Manager. If it is already started double click its icon on the system tray.

   The U-Filter Manager is part of the U-Filter Milestone Plugin. Its icon indicates the following states:

   • Running
   • Pending
   • Stopped

   NOTE: If the icon can not be found, please start U-Filter Manager with its shortcut or from the Windows Start menu.

   

2. Type the URL of Milestone XProtect Event Server (usually this computer).

3. Set the Authentication mode to Custom credentials. Set the username and the password you have created in Milestone XProtect above.

   As an alternative you can use the Default authentication for the current Windows user. This is only recommended for advanced users with system administrator skills.

   • The current user should be able to log in into Milestone XProtect and has Administrator privileges in Milestone XProtect.
   • The current user should be authorized to run the U-Filter Manager service in the Windows Services settings.

4. When everything is set, click the Start Server button. The Server status will indicate its state, as Running.

   NOTE: After you change any settings in Milestone XProtect, as described in chapter III, please restart the U-Filter Manager service by pressing the Stop server, then Start server buttons.

   

5. Done. You can close this window. Make sure that the tray icon indicates the service as running.

III. Configure input and output events for U-Filter

In this step we will create one or more Rules that define:

• which events in your existing security system should trigger filtering by U-Filter,
• how do we get samples from the camera streams.

In order to define such Rules we have to create its building blocks: After setting up the input for U-Filter, we will define the output events, which can later be converted to Alarms, E-mail or other types of notifications.

III. a. Set up the triggering event of your choice

Please make sure that you have read the chapter How does U-Filter work? at the beginning of this guide and that you understand what a "triggering event" is.

For this step, it must be ensured that a triggering event is available in Milestone XProtect.

• For setting up motion detection, please refer to the corresponding Milestone XProtect documentation about Motion detection at https://doc.milestonesys.com/2020R3/en-US/standard_features/sf_mc/sf_mcnodes/sf_3devices/mc_sitenavigationdevices.htm?#Motiontabdevices. You can set up the motion grid, sensitivity and more. Motion detection is reliable for detecting intruders, however it is liable to create a large number of false alarms. It is advised to use more advanced triggering events if possible for optimal resource consumption.
• If any other sophisticated events are available in your existing security system, like Person detection or Intrusion, now is the time to set them up. These events are typically triggered by a camera, another sensor or by a specific feature in Milestone XProtect. Most of such features can create an unacceptable amount of false alarms, which U-Filter can filter.

If the settings are finished, please proceed to the next paragraph.

III. b. Create a U-Filter configuration

Consult the table below for recommended configuration.

	Once	Start-Stop event
Duration (seconds):	3	-
Analysis Frame Rate:	1-3	1
Cooldown (seconds):	60	60
Overload cooldown (seconds):	120	120
Request timeout (seconds):	10	10

1. In the Milestone XProtect Management Client, go to the Site Navigation panel => MIP Plug-ins => U-Filter => U-Filter configurations.

2. Right-click on the U-Filter configurations panel => Add new.

   

3. Fill the form. Create a Name for this configuration.

4. Set the server Hostname to the network address of the U-Filter Server.

Make sure to delete the / (forward-slash) character at the end of the URL.

5. Select the Forwarding mode depending on the event which will trigger the filtering. This choice will determine other setting options.

   Understanding the Forwarding mode

   Please make sure that you have read the chapter How does U-Filter work? at the beginning of this guide and that you understand what the "triggering event" is.

   Triggering events can be a single occurrence (such as a Person detection) or events with a certain duration (such as Motion started / Motion stopped).

   • Once: If the triggering event of your choice is a single occurrence with no end signal, please choose the once option for Forwarding mode. In this case, the Duration and Analysis frame rate settings will determine the sampling. After the triggering event one or multiple number of snapshots will be sent one by one to the U-Filter server until a positive response is received from U-Filter OR until the last sample is sent (whichever happens first). The sampling frame rate is determined by the Analysis frame rate setting while the Duration setting determines how long to sample.
   • Start-stop event: If there is an event which determines the start of the possible incident and another one which determines the end of it, please choose the option Start-Stop event option for Forwarding mode. In this case the Cooldown and the Analysis frame rate settings will determine the sampling. After the triggering event occurs, snapshots will be sent one by one to the U-Filter server until another event determining the end of the incident is triggered. The sampling frame rate is determined by the Analysis frame rate setting. Upon a positive response from U-Filter, it is possible to avoid continuous event sending for a while. This duration is determined by the Cooldown setting. This feature may use a lot of CPU resources, especially if U-Filter uses a large amount of cameras in this Milestone instance - If you experience performance issues, consider choosing the once option instead.

6. Duration (only applicable to the Once forwarding mode): Sets a duration for the analysis time, in seconds.

7. Analysis frame rate: Determines how many snapshots get sent to be analysed by U-Filter, per second. It is recommended to keep this at a low value.

8. Cooldown: Set it to the number of seconds that have to pass between analysis periods. No snapshots will be sent from the triggering camera during this timeframe between events.

9. Overload cooldown: In case the U-Filter server gets overloaded with requests, this parameter controls how many seconds has to pass until new ones get accepted.

10. Request timeout: Determines how much time a single request should wait at most for filtering. It is recommended to set it to 10. After that time elapses without reply, the U-Filter server is considered to be busy. However, unfiltered events are not lost: they can be investigated as U-Filter unfiltered Analytic events.

11. Class Settings: Select the object types of your interest by setting their Sensitivity from OFF up to Very High. Tick Moving only to filter stationary objects.

12. Size filtering:

    You can customise the minimum and maximum height size of detections, in pixels, here (min. 32 pixels, max. 1000 pixels by default), to filter out objects of undesired sizes. Note that this applies to all objects, regardless of class. This setting can optionally be overridden by setting custom size filters on a camera-by-camera basis. Proceed to section III. c. to learn about camera-specific ROI / Size filtering.

13. Click Save.

NOTE: If you would like to use different triggering events in your system for different cameras, you should create multiple U-Filter configurations. Repeat all steps in this paragraph for each configuration you create.

III. c. ROI and Size Filter settings (optional)

Use case example:

I would like to set up U-Filter so that one entrance should not be used by cars, while the other should not be used by people.

U-Filter allows you to define ROI (Regions Of Interest) and object size filters. In some rare cases, different ROI should be associated with different classes or confidence threshold settings: this can be solved by multiple U-Filter Configuration instances. It is also possible to set ROI without size filtering and vice versa.

Concerning Analysis:

If a camera in a Milestone XProtect rule has no ROI / size filtering configured in the U-Filter Configuration, analysis is done on the entire image according to the settings in the General tab of the U-Filter Configuration. Registered ROI / size filtering affects analysis. If there are any ROI / size filters belonging to cameras not present in the Milestone XProtect rule, they are ignored.

• A single U-Filter Configuration may contain ROI/Size settings for multiple cameras.
• A single camera may have only one ROI / size filter configured per U-Filter Configuration.
• A single camera may have multiple ROI / size filters across multiple U-Filter Configurations. In this case, each Configuration must be added in separate rules. Note that different U-Filter Configurations can have different forwarding modes, this is however not advised.

1. Select the ROI & Size tab at the bottom of the screen.

   

2. Click Add Camera => Select a camera from the list of registered devices.

   

3. Click OK in the popup => The camera will have appeared in the list below.

   

Note: If you add a camera in the ROI & Size tab of your Configuration, make sure to only save your changes once you have pasted the required data, below. Otherwise, saving while a camera is missing its data will result in an error. In that case, simply follow the steps below to finalise your changes, then press Save again.

3. Click Open Editor => The U-Filter Stream Configurator will open in the browser you have configured as default.

   

ROI drawing

1. When the U-Filter Stream Configurator is first opened, the button is selected by default. Otherwise, select it.

2. Define an area by simply clicking on the canvas to create nodes.

• Each step can be undone with a right-click.
• Click on the starting point to finish drawing the area (or double-click the last point).

3. The new Positive ROI will appear in the Shapes list.

4. You can draw more Areas: a camera can have an unlimited number of them.

Negative Areas

All detections will be ignored in a Negative Area.

1. Double-click an existing ROI (or select it from the Shapes list).
2. Click the Set to Negative button. Clicking the button again will change the area back to positive.
3. Click the Finish editing current button at the top of the Shapes panel or click anywhere on the background to exit edit mode.
4. The Area will turn white, indicating that it is a Negative Area.

Once all ROI have been added, you can either set up custom size filters, or finish editing by clicking the button. Follow the steps below to finalise your changes or to add site filters.

Size filtering

1. Click the button.
2. Click on the canvas, then move the cursor up or down to start drawing - use the popup to help you define an exact maximum size in pixels. Finish drawing by simply clicking.
3. Click the button.
4. Click on the canvas, then move the cursor up or down to start drawing - use the popup to help you define an exact maximum size in pixels. Finish drawing by simply clicking.

Any object defined in the U-Filter Configuration that falls outside the minimum and maximum size set here will be ignored.

Background

By clicking the button, a detachable window will open, giving you the following options:

• The opacity of the background.
• Upload a custom background image.
• Configure the background grid.

Measure

Clicking the button enters into the Measuring mode. Left click sets the starting point and displays the distance between the starting point and the cursor location. It also calculates the size and perimeter of the rectangle where the ruler is the diagonal.

Applying ROI & Size Filter settings

1. Once you have made your desired changes in the U-Filter Stream Configurator, click the button.

2. A window will appear containing the data of your changes.

   

3. Copy all data included, by pressing Ctrl+A then Ctrl+C on your keyboard.

4. In the ROI & Size tab in Milestone XProtect, select your camera that you have just edited.

   

5. Double-click on its row under the Configuration tab => Paste the data you copied above by pressing Ctrl+V on your keyboard. Press Enter.

6. Click the Save button in the top left corner or press Ctrl + S to save.

Editing an existing ROI / Size filter configuration:

Note that in the current version of U-Filter (Milestone XProtect), reopening the Stream Configurator will reset the canvas to its default, empty state. Therefore, it is advisable to make all your changes in one go. You may otherwise freely overwrite your existing configurations as you see fit.

III. d. Create Rules for filtering

1. In the Milestone XProtect Management Client, go to the Site Navigation panel => Rules and Events => Rules.

2. Right-click on the Rules panel => Add Rule.

   

3. Set any Name e.g. U-Filter event start rule.

4. As the Type of rule, select Perform action on event. Click on the blue underlined "event" word in the lower panel.

   

5. In the Select an Event pop-up find the triggering event of your choice in section III. b. Click the event then click the OK button.

   In order to use Milestone XProtect's built-in Motion detector choose Events => Devices => Predefined Events => Motion Started.

6. In the Manage Rule pop-up click on the blue underlined "devices/..." line in the lower panel (after "from").

7. In the pop-up select Cameras => All cameras. Click the Add button. Click OK.

   You can choose any subset of your cameras in this step which should use the same triggering event for filtering. Make sure that one camera has only one triggering event and rule.

   

8. Click Next.

9. Skip the Conditions Step (2) by clicking Next again.

10. In the Actions Step (3) select Forward video to U-Filter server. Click on the blue underlined "Camera" word in the lower panel.

    

11. In the pop-up, select Use triggering device. Click OK.

12. Click on the blue underlined "U-Filter configuration" word in the lower panel. In the new pop-up, select a U-Filter Configuration you have created in chapter III. b. Click the Add button and click OK.

    

13. Click Next.

14. Stop criteria Step (4):

• If the U-Filter Configuration you have created in chapter III. b. uses once as a Forwarding Mode, select the No actions performed on rule end option, then click Finish - you may proceed to chapter III. e.

• If the Forwarding mode was set to Start-Stop event, select Perform an action on event as the Stop criteria. Perform an action on "Motion Stopped" should automatically be selected in the lower panel. Click Next to proceed to the Stop Actions (5) step below.

15. In the Stop actions Step (5), as the Stop Action, select Stop forwarding video to U-Filter server. Click on the blue underlined "Camera" word in the lower panel => Select Use triggering device. Click OK then click Finish - you may proceed to chapter III. e.

    

NOTE: If you do not have the above option shown, your Milestone XProtect version does not support configuring a Stop action within the same Rule. In this case, an additional Rule must be defined in order to stop sending events. To do so, create a new one by repeating the steps of this chapter with the following exceptions:

• When selecting a triggering event in the Select an Event pop-up, select a different event which is associated with the end of a potential incident.

  (To use Milestone XProtect's built-in motion detector, choose Events => Devices => Predefined Events => Motion Stopped.)

• Actions Step: select Stop Forwarding video to U-Filter server.

• The selected U-Filter configuration must be identical to the starter event's U-Filter configuration.

16. You can define multiple rules, depending on how many types of triggering events you would like to exploit. After you have a rule for each camera, you can proceed to the next chapter.

NOTE: If you edit any of these Rules later on, please make sure to restart the U-Filter Manager server (see chapter II.b for more details).

III. e. Create output Events for U-Filter

U-Filter will eventually emit events as its output upon confirmed or rejected intrusions, server overloads or errors.

1. In the Milestone XProtect Management Client, open Tools in the upper menu bar => Options => select the Analytics Events tab.

2. Under Analytics events, tick the box beside Enabled then press OK.

   

3. Go to the Site Navigation panel => Rules and Events => Analytics Events.

4. Right-click on the Analytics Events panel => Add New.

   

5. The name should be U-Filter .

   Note: It is very important to set this exact name without the dot or any white spaces. The same applies to the other two U-Filter analytics event names, below.

6. Click the Save button in the top left corner or press Ctrl + S to save.

7. Repeat the steps of this paragraph with all event names listed below.

U-Filter creates events not only when an incident is confirmed but on other occasions as well. These are the following:

• U-Filter is the name of the default positive event. Events with this name are triggered upon intrusions confirmed by U-Filter.
• U-Filter negative is emitted when U-Filter did not detect any intruders on the image. This event has testing or debugging purposes.
• U-Filter unfiltered is triggered whenever the U-Filter server responds with an error. This can happen if the U-Filter server was too busy to fulfil the filtering request or if the server is unhealthy. If you can not afford to lose any requests, it is recommended to register this event.

NOTE: If you modify any of these events, make sure you update all corresponding Alarms, Rules and other dependencies.

IV. Using the output of U-Filter

At this point, 3 types of U-Filter events are available in Milestone XProtect. Feel free to use these as you wish. In this chapter you will learn the most common ways of usage.

IV. a. Convert U-Filter events to Alarms

Now an Alarm has to be configured in Milestone XProtect.

1. In the Milestone XProtect Management Client go to the Site Navigation panel => Alarms => Alarm Definitions.

2. Right-click on the Alarm Definitions panel => Add new.

3. Fill the form. Make sure that the alarm is Enabled.

4. Set any Name for the alarm. This alarm will represent positive notifications coming from U-Filter.

5. Set the Triggering event to Analytics Events, then set U-Filter in the drop-down list below.

   If you would like to receive and monitor U-Filter negative and U-Filter unfiltered events coming from U-Filter, create a separate Alarm for each by repeating the steps in this chapter.

6. At the Sources setting, click the Select... button. A pop-up will appear.

7. Click on the Servers tab. Select the All Cameras node and click the Add button. Click OK.

   You can choose only a subset of these cameras too.

   

8. If you are familiar with Milestone XProtect, you can configure the rest of the settings as you wish or leave them as they are.

9. Click the Save button in the top left corner.

All done. You will receive alarms in the Alarm Manager.

IV. b. Receiving alarms by e-mail

Besides the Alarm Manager, Milestone XProtect has an additional way of viewing received alarms: in e-mail format with optional image and/or video attachments.

Follow the steps below to have a working e-mail notification setup.

Mail server

1. In the Milestone XProtect Management Client, go to the Options in the upper menu bar => Mail Server.

   

2. Type in the sender address.

3. Type in the SMTP address of the sender in Mail server address.

4. Click OK.

Notification Profile

Now let us create a profile for sending the e-mail notifications.

1. In the Milestone XProtect Management Client go to the Site Navigation panel => Rules and Events => Notification Profiles.

   

2. Right-click on the Notification Profiles icon in the right-side panel => Add new.

3. Set U-Filter email as the Name of the profile. You may fill the Description field as well (optional).

   

4. Click Next.

   

5. Fill in the Recipients field with the e-mail addresses of your recipients, separated by semicolons.

6. Set any name for the e-mail Subject.

7. Type in any text for the e-mail.

Optional:

By clicking on any of the items under Add system information, the e-mail body will automatically include them as additional information. You may also set a minimum time interval between the e-mails sent, in seconds.

Under Data, you may add and configure images and videos (the latter in AVI format) of the alarms by ticking their respective boxes. You can include the images as attachment, or embedded in the e-mail by ticking the Embed images in e-mail box.

8. If you would like to test the settings you just configured, click Test E-mail.

9. Click Finish to save the profile, which will appear under Notification Profiles of the Site Navigation Panel.

   

E-mail Rule

1. In the Milestone XProtect Management Client, go to the Site Navigation panel => Rules and Events => Rules.

2. Right-click on the Rules panel => Add Rule.

   

3. Set any Name.

4. In the Type of rule Step (1), select Perform action on event. Click on the blue underlined "event" word in the lower panel.

   

5. In the pop-up, select Events => Analytics Events => U-Filter.

   If you would like to use other events coming from U-Filter, create a separate Rule for each one by repeating the steps in this chapter.

6. Click OK.

7. Click on the blue underlined "devices/..." line in the lower panel (after "from").

8. In the pop-up, select Cameras => All cameras. Click the Add button. Click OK.

   You can use any subset of your cameras.

   

9. Click Next.

10. Skip the Conditions Step (2). Click Next again.

11. In the Actions Step (3), select Send notification to profile. Click on the blue underlined "profile" word in the lower panel.

    

12. In the pop-up, select U-Filter email under Notification Profiles. Click OK.

    

13. Click on the blue underlined "recording device" word in the lower panel.

14. In the pop-up, select Use devices from metadata. Click OK.

    

15. Click the Next button.

16. In the Stop Criteria (4) step, select No actions performed on rule end.

    

17. Click Finish. The new rule is created and Milestone XProtect is ready to send alarms via e-mail from U-Filter.

All done! Recipients will receive emails upon a triggered alarm.

V. Receiving alarms in Milestone XProtect

V. a. Alarms through the Alarm Manager

Whenever an Alarm is triggered by U-Filter, it should be visible in Milestone XProtect Smart Client under the Alarm Manager tab with annotations.

NOTE: As of now, the Alarm Manager is only available out-of-the-box in editions XProtect Express+ and above. In XProtect Essential+, receiving alarms are possible either by E-mail notification or by manually creating a view to replicate the functionality of the Alarm Manager.

The metadata in the alarms:

• Name: The name of the alarm in Milestone XProtect.
• Message: U-Filter, U-Filter negative or U-Filter unfiltered (cannot be changed).

V. b. Alarms via E-mail

Recipients are receiving alarms according to the E-mail notification settings in Chapter IV. b.

V. c. Creating a custom view in Smart Client

This method could be useful if using the Essential+ edition of Milestone XProtect, which lacks the Alarm Manager - follow the steps below to replicate its functionality. In editions above XProtect Essential+, you do not need to do this.

1. In the Milestone XProtect Smart Client, open the LIVE tab of the window.

Note that from version 2023 R1 of Milestone XProtect, the Live and Playback tabs have been merged into the Views tab.

2. Click the Setup button in the upper right corner of the window -> Certain elements of the interface will turn orange, indicating that they are now editable.

   

3. On the left sidebar, select a View Group -> click Create new view. Choose any layout that contains at least one wide rectangle; in this example, layout 1+1+4 under category 4:3.

   

4. On the left sidebar, under System overview, open Alarms -> click and drag the Alarm List and Alarm Preview items into the wide rectangles you created in the above step (into the two left-side rectangles in our example of a 1+1+4 grid).

   

5. From the Camera menu on the left sidebar, drag any cameras of your choosing into the remaining rectangles.

6. Click the Setup button in the upper right corner of the window to exit editing and save your changes to the interface.

   

VI. License

License information about the U-Filter plugin for Milestone XProtect can be accessed from two places, both accessible via the Site Navigation sidebar on the left:

• License Information page, under Basics, listing the Milestone XProtect and the U-Filter plugin licenses.

  

• U-Filter information page, under MIP Plugins.

  

Both pages list the following information:

• License validity
• License expiration date
• Maximum number of streams supported by the U-Filter license
• Number of streams currently utilising the U-Filter plugin's functionality

Additionally, the License information page shows the U-Filter plugin version number. The U-Filter page lists all streams associated with a Rule configured to forward video to a U-Filter configuration.

VII. Support

Should you encounter any issues, please visit our support page on https://ultinous.atlassian.net/servicedesk/customer/portals or contact your account manager.