Macroscop SDK и API

Опубликовано 19.04.2023
 2

Оглавление
Общие сведения о Macroscop SDK ................................................................................................................. 4
Быстрый старт – типовые задачи ................................................................................................................... 5
Краткое описание проектов с примерами использования Macroscop SDK ................................................. 7
Плагины ........................................................................................................................................................... 9
Регистрация плагинов в Macroscop ...................................................................................................................... 9
Сериализуемые классы в плагинах .................................................................................................................... 11
Плагин Действие .................................................................................................................................................. 11
Плагин Видеоаналитика ...................................................................................................................................... 13
Плагин Трекер ...................................................................................................................................................... 20
Плагин Визуализатор ........................................................................................................................................... 20
Плагин Элемент меню ......................................................................................................................................... 22
Плагин Процессор событий ................................................................................................................................ 24
Плагин Получатель кадров ................................................................................................................................. 26
Macroscop API с интерфейсами HTTP и RTSP ............................................................................................... 41
HTTP-интерфейс для получения видео .............................................................................................................. 41
Получение видео реального времени и архива ....................................................................................... 41
Получение перекодированного видео в формате MJPEG. ...................................................................... 42
HTTP-интерфейс для получения данных............................................................................................................ 44
Получение конфигурации системы ........................................................................................................... 44
Получение профилей (предустановленные сетки) .................................................................................. 49
Получение списка доступных сеток на клиенте Macroscop ..................................................................... 50
Получение информации о текущей сетке в клиенте Macroscop ............................................................. 50
Получение времени компьютера, на котором работает сервер Macroscop .......................................... 51
Получение информации о наличии архива в указанный момент времени ........................................... 51
Получение списка интервалов с информацией о начале и окончании записи архива. ........................ 52
Скачивание фрагмента видео из архива в формате mp4 ........................................................................ 52
Получение информации о состоянии каналов. ........................................................................................ 52
Получение PTZ-возможностей устройства ................................................................................................ 54
Получение пресетов с PTZ-устройства ....................................................................................................... 55
HTTP-интерфейс для получения событий .......................................................................................................... 55
Получение списка всех зарегистрированных в системе событий ........................................................... 55
Получение событий в реальном времени ................................................................................................ 56
Получение списка специальных архивных событий ................................................................................ 60
Получение из архива распознанных автомобильных номеров .............................................................. 61
HTTP-интерфейс для отправки команд на сервер Macroscop.......................................................................... 63
Включение/выключение записи на канале .............................................................................................. 63
Синхронизация времени с другим компьютером в сети ......................................................................... 63
 3

Получение профилей (предустановленные сетки) .................................................................................. 63

Установка профиля на клиенте .................................................................................................................. 63
Смена сетки на клиенте .............................................................................................................................. 63
Очистка сетки ............................................................................................................................................... 63
Установка канала в ячейку сетки ............................................................................................................... 64
Удаление канала из ячейки сетки .............................................................................................................. 64
Команда PTZ для «непрерывного» движения .......................................................................................... 64
Команда PTZ для «непрерывного» изменения фокуса ............................................................................ 64
Команда PTZ для «непрерывного» зума ................................................................................................... 64
Команда PTZ остановки для «непрерывных» команд ............................................................................. 64
Команда PTZ установки пресета ................................................................................................................ 65
Команда PTZ автофокусировки .................................................................................................................. 65
Команда PTZ для выполнения центрирования ......................................................................................... 65
Команда PTZ для «шагового» движения ................................................................................................... 65
Команда PTZ для «шагового» зума ............................................................................................................ 65
Команда PTZ приближения выделенной области (AreaZoom) ................................................................ 65
Постановка канала на охрану ..................................................................................................................... 65
Отправка звука на камеру .......................................................................................................................... 66
Генерация события из внешней системы ................................................................................................. 66
RTSP-интерфейс для получения видео и звука ................................................................................................. 67
Macroscop API с интерфейсом XML .............................................................................................................. 71
Получение данных счётчика посетителей ......................................................................................................... 71
Организация вещания видео на сайт .......................................................................................................... 74
Вещание с помощью HTML5 ............................................................................................................................... 74
Вещание с помощью Flash (устарело) ................................................................................................................ 76
Вещание с помощью JavaScript (устарело) ........................................................................................................ 77
 4

Общие сведения о Macroscop SDK

Macroscop SDK – это инструментарий, позволяющий создавать программное
обеспечение, именуемое плагинами (внешними модулями), позволяющее расширять
существующие функциональные возможности программного комплекса Macroscop.
Данный инструментарий предназначен для .NET программистов, желающих создавать
плагины для Macroscop. Все исходные файлы инструментария и примеров написаны
для .NET на языке C#. В качестве среды разработки предполагается использование
Microsoft Visual Studio. Для понимания данного документа требуется владение
терминологией Macroscop на уровне опытного пользователя. При необходимости можно
обратиться к инструкциям оператора и администратора, поставляемых
в комплекте с Macroscop.
В Macroscop SDK каждый плагин представляет собой наследника одного из доступных
в инструментарии базовых классов (интерфейсов) и решает определенный ряд задач. На
данный момент в инструментарии имеются следующие основные базовые классы
(интерфейсы), которые могут быть использованы внешними разработчиками:
Имя плагина Название Описание
ExternalAction Действие Базовый класс, позволяющий добавлять новые
действия для сценариев и планировщика
задач по расписанию
VideoAnalyst Видеоаналити Базовый класс для осуществления
ка видеоаналитики на сервере
Tracker Трекер Базовый класс для создания трекера
PluginVisualiser Визуализатор Базовый класс визуализатора для
графического отображения специфической
информации на канале в приложении
Macroscop Клиент
IClientPluginMenuItem Элемент Интерфейс, позволяющий создавать
меню в приложении Macroscop Клиент
собственный подпункт в меню Настройка
EventProcessor Процессор Базовый класс процессора событий. Позволяет
событий регистрировать и генерировать собственные
события, получать события из Macroscop,
а также выполнять команды в канале.
Плагины данного типа могут быть
использованы для осуществления интеграции
с другими системами.
ICameraServiceProvider Получатель Интерфейс получателя кадров с IP-устройств.
кадров Позволяет получать с IP-устройств (камер)
видео, звук, данные детекции движения;
а также управлять поворотными камерами.
Указанные типы базовых классов (интерфейсов), а также некоторые другие
вспомогательные сущности подробно рассматриваются в соответствующих главах
данного документа. Все плагины существуют и работают в рамках канала Macroscop.
Таким образом, все экземпляры плагинов по умолчанию изолированы друг от друга,
однако имеется возможность обмениваться данными при необходимости через
статические поля плагина. Как правило, все плагины, решающие в совокупности одну
сложную задачу, находятся в одной сборке .NET. Такая сборка является динамически
подключаемой библиотекой (DLL), функционирующей в среде Macroscop. Подключение
сборок и регистрация плагинов происходит на этапе запуска отдельных компонентов
программного комплекса (см. Регистрация плагинов в Macroscop).
 5

Быстрый старт – типовые задачи

1. Интеграция IP-камер
Для подключения IP-устройства (камеры) достаточно реализовать плагин
Получатель кадров. Сведения о данном типе плагина предоставлены в разделе
Плагин-получатель кадров. Шаблон плагина размещен в папке
с примерами, в проекте [Link].
2. Интеграция со СКУД, ОПС, POS-терминалами и т.п.
Интеграция может быть выполнена через плагин Процессор событий, способный
получать события от Macroscop, генерировать в Macroscop собственные события
в процессе взаимодействия с другой системой, выполнять в Macroscop команды
в канале (включение/выключение записи, установка пресетов, ввод-вывод с
камер и др.), получать доступ к архиву Macroscop. Сведения о данном типе
плагина предоставлены в разделе Плагин Процессор событий. Пример плагина
размещен в папке с примерами, в проекте EP_PluginExample.csproj. Если
требуется получать только видео и звук
из Macroscop, то можно использовать более простой вариант, рассмотренный
в разделе HTTP-интерфейс для получения видео; пример получения видео по
HTTP размещен в папке с примерами, в проекте [Link].
3. Видеоаналитика
Любой алгоритм обработки видеопотока может быть реализован с помощью
плагина Видеоаналитика. Все результаты работы данного плагина
представляются событиями, которые могут быть далее интерпретированы
плагинами Визуализатор и Элемент меню. Указанные плагины описаны
в разделах Плагин Видеоаналитика, Плагин Визуализатор
и Плагин Элемент меню; пример использования размещен в папке
с примерами, в проекте Analyst_PluginExample.csproj.
6
 7

Краткое описание проектов с примерами

использования Macroscop SDK
Каждый проект имеет отдельное описание работы в файле [Link].
Также описание и примеры реализации некоторых плагинов находятся в нашем
репозитории на GitHub.

Название проекта Описание

Analyst_PluginExample Плагин добавляет интеллектуальный модуль Test Event
Module, который генерирует событие CounterEvent,
отображаемое в журнале событий Macroscop Клиента.
Camera Плагин добавляет возможность получать тестовое видео с
тестовой камеры: Macroscop Конфигуратор -> Камеры
-> Добавить камеру -> Производитель = Sample Brand,
Тип устройства = Камера, Модель = Sample Camera. В
качестве примера, на видео постоянно отображается
текст SAMPLE FRAME.
EP_PluginExample Плагин добавляет модуль External events generating
module, который генерирует событие CounterEvent,
отображаемое в журнале событий Macroscop Клиента.
В событии содержится значение счетчика, которое
инкрементируется в соответствии с заданной в
настройках частотой.

ExternalAction_PluginExample Плагин добавляет действие Test external action по

событию в сценариях и планировщике задач по
расписанию. Действие записывает сообщение в лог Test
external action [Link].

HttpInterface В примере реализовано отображение списка каналов

сервера, списка зарегистрированных событий. Также
доступно получение событий в реальном времени и
специальных архивных событий.
HttpVideo Пример демонстрирует получение видео (mjpeg) с
камеры с помощью HTTP-интерфейса.
MenuItem_PluginExample Плагин добавляет элемент меню в Клиенте (Левая
панель -> Дополнительно -> MENU ITEM EXAMPLE). При
нажатии на элемент меню происходит открытие окна, в
котором содержатся идентификаторы каналов.
RtVisualizer Плагин отображает информацию в ячейке наблюдения
камеры в Клиенте, при возникновении события тревоги
на камере.
8
 9

Плагины
В данной главе описан процесс регистрации плагинов, а также подробно рассмотрен
каждый тип плагина. Наиболее важные фрагменты кода отражены в тексте.

Регистрация плагинов в Macroscop

В момент запуска отдельных приложений — компонентов Macroscop (Сервер/Клиент/
Конфигуратор; далее в тексте — хост), — происходит поиск .NET сборок в папке
Plugins запускаемого приложения. В каждой найденной сборке должен быть реализован
интерфейс IPlugin, представленный ниже:
public interface IPlugin
{
/// <summary>
/// Возвращает уникальный идентификатор модуля
/// </summary>
Guid Id { get; }

/// <summary>
/// Возвращает название модуля
/// </summary>
string Name { get; }

/// <summary>
/// Возвращает название производителя модуля
/// </summary>
string Manufacturer { get; }

/// <summary>
/// Инициализация модуля.
/// Вызывается хостом на этапе регистрации модуля в системе.
/// </summary>
/// <param name="host">Интерфейс хоста</param>
void Initialize(IPluginHost host);
}
Пример реализации данного интерфейса:
public class ModuleDef : IPlugin
{
public Guid Id
{
get { return new Guid("17EE3457-8FC2-4C0F-B133-EF11D0C4F38C"); }
}

public string Name

{
get { return "Модуль поиска оставленных предметов"; }
}

public string Manufacturer

{
get { return "Macroscop"; }
}

public void Initialize(IPluginHost host)

{
[Link](typeof(AnalystExample));
[Link](typeof(ObjectLeftEvent));
}
}
 10

Как только указанный интерфейс был обнаружен хостом, вызывается метод

инициализации (Initialize), в качестве аргумента которому передается интерфейс
IPluginHost, предоставляющий сервисные методы хоста:
public interface IPluginHost : IService
{
/// <summary>
/// Получает интерфейс менеджера протоколов
/// </summary>
/// <returns></returns>
IMcLogMgr GetLogManager();

/// <summary>
/// Регистрация устройства.
/// </summary>
void RegisterDevType(DevType_RegInfo regInfo);

/// <summary>
/// Регистрирует внешнее событие
/// </summary>
void RegisterExternalEvent(Type eventType);

/// <summary>
/// Регистрирует внешнее действие
/// </summary>
void RegisterExternalAction(Type actionType);

/// <summary>
/// Регистрирует пункт меню в Macroscop клиенте
/// </summary>
void RegisterMenuItem(Type menuItemType, List<Guid> requiredPluginIDs);

// ... Прочие, не показанные здесь, функции регистрации

}

Сервисные методы хоста предоставляют следующие возможности:

● Протоколирование работы плагинов с помощью интерфейса IMcLogMgr,
получаемого соответствующим методом GetLogManager().
● Регистрация в системе плагинов для решения различных задач.
Для того чтобы указать, при каких условиях нужно регистрировать плагин, необходимо
создать текстовый файл с расширением *.dep и именем, совпадающим с названием
dll-библиотеки, содержащей реализацию плагина. Данный файл, описывающий
зависимости, может обладать, например, следующим содержанием:
<?xml version="1.0"?>
<PluginDependence xmlns:xsi="[Link]
xmlns:xsd="[Link]
<Files>
<DependenceFilename>[Link]</DependenceFilename>
<DependenceFilename>..\..\..\[Link]</DependenceFilename>
<DependenceFilename>..\..\abc*.dll</DependenceFilename>
</Files>
<DependenceRegistryKey>
HKEY_LOCAL_MACHINE\SOFTWARE\Macroscop
</DependenceRegistryKey>
<DependenceRegistryValue>Path</DependenceRegistryValue>
</PluginDependence>
 11

До версии Macroscop 1.9 данный файл является обязательным для регистрации плагина,
после — нет. Данный файл должен быть в той же папке, что и сам плагин,
для того, чтобы он имел действие. В теге <Files> может быть любое количество файлов.
Поддерживается символ *, обозначающий любое количество любых символов. Пара
тегов <DependenceRegistryKey> и <DependenceRegistryValue> имеют смысл
только вместе.

Сериализуемые классы в плагинах

Плагин может содержать сериализуемые классы, например наследники IAction,
RawEvent, классы настроек. Такие классы обычно помечены аттрибутом [Serializable]. В
плагинах такие классы дополнительно необходимо помечать аттрибутом
[AlarusSerializable].

Плагин Действие
Плагин действие позволяет расширить список функций в сценариях и планировщике
задач по расписанию. Для создания такого типа плагина необходимо наследоваться от
класса ExternalAction:
/// <summary>
/// Базовый класс действия.
/// </summary>
[Serializable][AlarusSerializable]
public abstract class ExternalAction : IAction
{
[NonSerialized]
protected IActionHost ActionHost;

/// <summary>
/// Инициализация. Вызывается хостом перед началом работы.
/// </summary>
/// <param name="host"></param>
public virtual void Initialize(IActionHost host)
{
ActionHost = host;
}

/// <summary>
/// Показывает правильно ли на данный момент
/// сконфигурировано ли действие
/// </summary>
public abstract bool IsConfigurated
{
get;
}

/// <summary>
/// Описание на основе текущих настроек
/// </summary>
public abstract string Description
{
get;
}

/// <summary>
/// Свойство показывает, привязано ли действие к
/// конкретному каналу. Иными словами, влияет ли действие каким-либо
/// образом на канал.
 12

/// </summary>
public virtual bool IsChannelIndependent
{
get
{
//по умолчанию действие к каналу никак не привязано
return true;
}
}

/// <summary>
/// Запуск действия на выполнение
/// </summary>
public abstract void Run(RawEvent rawEvent);

/// <summary>
/// Выполнение команд в канале. Заполняется сервером, может использоваться в
/// методе Run (см. выше)
/// </summary>
[NonSerialized]
public ExecuteCommandDelegate ExecuteCommand;

/// <summary>
/// Позволяет генерировать событие, заполняется хостом перед вызовом действия
/// </summary>
[NonSerialized]
public GenerateEventDelegate GenerateEvent;
}

В классе наследнике требуется задать следующие атрибуты:

● ActionGUIName — название действия, которое будет фигурировать в
графическом интерфейсе в конфигураторе.
● GuidAttribute — идентификатор действия.
Опционально может быть задан атрибут ActionNeedsEventArgument, который
показывает, что для вызова метода Run плагина со стороны сервера обязательно следует
передавать объект события. Это также означает, что действие выполняется только по
событию и не может выполняться в задачах по расписанию, при выполнении которых
события не возникают.
Также требуется определить (переопределить) методы базового класса. Рассмотрим
более подробно метод инициализации, в который передается интерфейс IActionHost со
стороны хоста. Интерфейс выглядит следующим образом:
/// <summary>
/// Интерфейс, предоставляющий возможности
/// хоста при инициализации плагина действия.
/// </summary>
public interface IActionHost
{
/// <summary>
/// Получение информации о канале,
/// в котором запущен текущий экземпляр
/// плагина действия.
/// </summary>
/// <returns></returns>
RawChannelInfo GetChannelInfo();

/// <summary>
/// Сохраняет любой сериализуемый объект в конфигурацию
/// Macroscop. Используется в конфигураторе.
/// </summary>
/// <param name="id">Идентификатор объекта</param>
 13

/// <param name="obj">Объект</param>

void SaveObject(Guid id, object obj);

/// <summary>
/// Получает ранее из сериалзиованный объект из конфигурации.
/// Используется в конфигураторе.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
object GetObject(Guid id);

/// <summary>
/// Отправляет команду плагину, работающего на сервере.
/// </summary>
/// <param name="pluginId">Идентификатор плагина</param>
/// <param name="channelsIds">Идентификаторы каналов</param>
/// <param name="command">Команда</param>
/// <returns>Возвращает результат от каждого канала. Ключ - идентификатор канала.
/// Значение - результат выполнения команды.</returns>
Dictionary<Guid, object> SendCommandToPlugin(Guid pluginId, List<Guid> channelsIds,
object command);
}

Данный интерфейс позволяет получить информацию о канале, к которому привязан

экземпляр плагина. Эта информация включает в себя имя канала и его идентификатор.
Идентификатор должен быть использован при выполнении команд в канале
(см. делегат ExecuteCommand). Подробная информация о доступных командах
приведена в разделе Плагин Процессор событий Кроме того, данный интерфейс с
помощью методов SaveObject и GetObject позволяет сохранять
и загружать любой сериализуемый объект по идентификатору на этапе задания
пользователем конфигурации Macroscop. Такой механизм позволяет сохранять
и извлекать настройки, которые являются одинаковыми для всех экземпляров плагинов.
Свойство IsConfigurated показывает, правильно ли пользователь сконфигурировал
действие в графическом интерфейсе; если неправильно, то конфигурацию невозможно
будет применить до тех пор, пока ошибки не будут исправлены.
Для регистрации Действие в системе, необходимо на этапе загрузки сборки с плагином
в методе инициализации класса, реализующего интерфейс IPlugin, вызвать метод
RegisterExternalAction интерфейса хоста (см. Регистрация плагинов в Macroscop).
Для действий, имеющих настройки в графическом интерфейсе, необходимо добавить
атрибут ActionAssemblyPluginHasSettingsControl в файл [Link].

Плагин Видеоаналитика
Данный тип плагина осуществляет покадровый анализ видеопотока, что позволяет
создавать сервисные детекторы, например, детектор оставленных предметов, детектор
саботажа и др. Для создания такого типа плагина, необходимо создать наследника
базового класса VideoAnalyst:
/// <summary>
/// Класс видеоаналитика. Используется для обработки кадров и карт движения.
/// </summary>
public abstract class VideoAnalyst : IDisposable
{
/// <summary>
/// Инициализация аналитика. Вызывается хостом перед началом процесса обработки.
/// </summary>
/// <param name="id">Идентификатор канала</param>
/// <param name="analystToolSet">Тул сет аналитики</param>
/// <param name="pluginEnv">Настройки плагина</param>
 14

public abstract void Initialize(Guid id, IPluginAnalystToolSet analystToolSet,

PluginEnvironment pluginEnv);

/// <summary>
/// Метод обработки кадра и карты движения. Вызывается хостом.
/// </summary>
/// <param name="image">Кадр</param>
/// <param name="motionMap">Карта движения, может быть null</param>
/// <param name="background">Фон от детектора движения. Равен null, если
///NeedBackground == false</param>
public abstract void Process(ImageData image, MotionMap motionMap, BackgroundImage
background);

/// <summary>
/// Генерирует в канале ранее зарегистрированное внешнее событие. Заполняется
/// хостом. Вызывается аналитиком.
/// </summary>
public GenerateEventDelegate GenerateEvent;

/// <summary>
/// Поддерживает ли аналитик работу с частично продекодированными кадрами.
/// True означает, что на вход могут подаваться уменьшенные видеокадры,
/// False означает, что на вход всегда будут подаваться видеокадры с оригинальным
/// разрешением.
/// </summary>
public virtual bool SupportsPartlyDecodedFrames => false;

public virtual bool NeedBackground => false;

public virtual TimeSpan MinTimeBetweenFrames => [Link];

public virtual TimeSpan MaxTimeBetweenFrames => [Link];

protected ServerRole ServerRoleForChannel { get; set; }

/// <summary>
/// Поддерживаемый формат пикселя
/// </summary>
public virtual VAPixelFormat PixelFormat => VAPixelFormat.BGR24;

/// <summary>
/// Выполняет команду.
/// </summary>
/// <param name="cmdObj"></param>
/// <returns></returns>
public virtual object ProcessCommand(object cmdObj)
{
return null;
}

public SendServerCommandDelegate SendServerCommand;

/// <summary>
/// Освобождение ресурсов
/// </summary>
public abstract void Dispose();

/// <summary>
/// Изменяет общие или специфические настройки аналитика, если это необходимо.
/// Вызов метода должен приводить к появлению пользовательского окна настройки.
/// Вызывается хостом (конфигуратором).
/// </summary>
 15

/// <param name="channel"></param>

/// <param name="settingsHost"></param>
/// <param name="settings">Текущие параметры аналитика</param>
/// <returns>Новые параметры аналитика</returns>
public abstract PluginSettings SetSettings(Guid channel, ISettingsHost
settingsHost, PluginSettings settings);

public virtual object GetAdditionalInfo()

{
return null;
}

public virtual object GetAdditionalInfo(params object[] parameters)

{
return null;
}

/// <summary>
/// Возвращает конфигурацию в виде массива байт
/// </summary>
/// <returns></returns>
public virtual byte[] GetBinarySettings()
{
return null;
}

/// <summary>
/// Изменяет общие или специфические настройки аналитика, если это необходимо.
/// </summary>
/// <param name="binarySettings">настройки аналитика в виде массива байт</param>
public virtual void SetSettings(byte[] binarySettings)
{
}

public virtual List<VideoAnalystZone> GetZones(object channelSpecificSettings)

{
return new List<VideoAnalystZone>();
}

public virtual bool NeedReferencedImage()

{
return false;
}

/// <summary>
/// Нужны ли вообще аналитику видеокадры? (Некоторые аналитики, например,
/// 3D-подсчет сейчас получают с камеры готовые данные. В этом случае видео тянуть
/// не надо).
/// </summary>
/// <returns></returns>
public virtual bool NeedVideoFrames()
{
return true;
}

/// <summary>
/// Конвертирует настройки аналитика из Json <paramref name="settingsJson"/> с
/// учетом текущих настроек из
/// конфигурации <paramref name="currentSettings"/> и возвращает новые настройки
/// аналитика.
/// </summary>
/// <param name="settingsJson">Новые настройки аналитика в формате Json</param>
 16

/// <param name="currentSettings">Текущие настройки аналитика</param>

/// <param name="converter">Json конвертер</param>
/// <returns>Новые настройки аналитика</returns>
public virtual PluginSettings ConvertJsonSettingsToPluginSettings(string
settingsJson,
PluginSettings currentSettings, IJsonConverter converter) =>
default(PluginSettings);

/// <summary>
/// Конвертирует текущие настройки аналитика <paramref name="currentSettings"/> в
/// Json и возвращает их.
/// </summary>
/// <param name="currentSettings">Текущие настройки аналитика</param>
/// <param name="converter">Json конвертер</param>
/// <returns>Настройки в формате Json</returns>
public virtual string ConvertToJsonSettings(PluginSettings currentSettings,
IJsonConverter converter) => null;
}
Класс наследник должен переопределить все абстрактные методы базового класса и, при
необходимости, виртуальные свойства. Кроме того, производный класс должен иметь
обязательный атрибут PluginGUINameAttribute, содержащего название аналитики,
отображаемой в графической оболочке приложения Macroscop Конфигуратор. Если
аналитика может быть настроена в конфигураторе, необходимо реализовать метод
настройки SetSettings, и указать атрибут PluginHasSettingsAttribute.
Данные изображений подаются на вход аналитики в виде класса ImageData.
Поскольку каждый аналитический плагин прикрепляется пользователем к тому или
иному каналу, в конфигураторе Macroscop объект настроек PluginSettings состоит из
2 частей:
1) настройки, связанные с текущим каналом безопасности
2) общие настройки аналитика, не зависящие от выбранного канала безопасности.
public struct PluginSettings
{
/// <summary>
/// Специфические настройки плагина, связанные с текущим каналом. Может быть null.
/// Объект настроек должен быть сериализуемым.
/// </summary>
public object channelSpecificSettings;

/// <summary>
/// Общие настройки плагина. Не зависят от текущего канала. Может быть null.
/// Объект настроек должен быть сериализуемым.
/// </summary>
public object generalSettings;
}
Если настройки аналитики едины для всех каналов, то достаточно заполнять только
объект общих настроек. В противоположном случае, когда все настройки аналитики
привязываются к конкретному каналу, достаточно заполнять только объект
специфических настроек канала. Объекты общих и специфических настроек являются
пользовательскими. Единственным требованием для них является возможность их
сериализации, поскольку все настройки аналитики хранятся в общей конфигурации
Macroscop.
 17

Рассмотрим также метод ProcessCommand, который позволяет аналитике выполнять

команды от плагина Элемент меню (см. Плагин Элемент меню). Данный метод получает
команду в виде сериализуемого объекта, который формируется на стороне плагина
Элемент меню. В качестве результата данный метод также должен возвращать
сериализуемый объект, который впоследствии получит и обработает плагин Элемент
меню. Такой механизм позволяет реализовать клиент-серверное взаимодействие,
поскольку плагин Видеоаналитика работает на сервере, а плагин Элемент меню —
всегда в клиенте.
В процессе обработки видеокадров аналитика должна передавать результаты своего
анализа серверу с помощью генерации событий. Для этого необходимо заранее
зарегистрировать на стороне хоста (см. Регистрация плагинов в Macroscop) внешнее
пользовательское событие, содержащее описание всех необходимых полей для
интерпретации результатов работы аналитика. Регистрируется событие с помощью
метода RegisterExternalEvent интерфейса IPluginHost на этапе инициализации
модуля. Пользовательское событие должно быть унаследовано от базового класса
RawEvent:
/// <summary>
/// Родительский класс в иерархии событий, происходящих в канале.
/// </summary>
[Serializable][AlarusSerializable]
public abstract class RawEvent : IDescribable
{
/// <summary>
/// ВременнАя метка события.
/// </summary>
[OptionalField]
public DateTime EventTime;

/// <summary>
/// Комментарий к событию.
/// </summary>
[OptionalField]
public string Comment;

public virtual EventTextDescription GetDescription(IToStringConverter converter)

{
return new EventTextDescription("");
}

public virtual object GetAttachments()

{
return null;
}

/// <summary>
/// Создание сырого события
/// </summary>
protected RawEvent()
{
EventTime = [Link];
}
}

Каждое пользовательское событие должно иметь ряд обязательных атрибутов:

● GuidAttribute — определяет в явном виде уникальный идентификатор события;
● Serializable и AlarusSerializable — позволяют выполнять сериализацию события.
 18

Кроме того, имеется ряд необязательных (опциональных) атрибутов:

● EventLocalizedName — задает название события в графическом интерфейсе
хоста. Если атрибут не задан, то событие не будет отображаться в конфигураторе
в разделе сценариев;
● EventSaveable — задает название таблицы в базе данных, в которую
будут сохраняться экземпляры события; атрибут должен использоваться в случае,
если у события есть поля, которые должны быть сохранены в БД (важно отметить,
что свойство события SaveMode должно принимать в этом случае значения
Special, UnifiedLog или SpecialAndUnifiedLog). Свойство события
GenerationFrequency задает частоту генерации данного события, требует
параметр EventGenerationFrequency (см. ниже). Данное свойство влияет на
работу сервера при сохранении событий в БД и имеет рекомендательный характер.
Если свойство не было указано, то по умолчанию используется режим Middle. Этот
режим является предпочтительным. Режим Low не рекомендуется для
использования, поскольку данные события записываются
в особую, критичную для функционирования, базу данных;
● EventGeneratesAlarmByDefault — событие по умолчанию является тревожным,
что означает автоматическую привязку к событию действия Генерация тревоги
при создании нового канала в конфигураторе Macroscop.

Если пользовательское событие имеет поля, которые должны сохраняться в БД,

необходимо для каждого из полей указывать атрибут
EventFieldSaveableOrScenariesUsable. В качестве параметров атрибут требует
указать orderNum (порядковый номер поля, отсчет начинается с 0) и indexable (флаг,
указывающий, нужно ли индексировать данное поле).
Поддерживаются следующие типы полей события, к которым применимы указанные
выше атрибуты: int, bool, long, double, DateTime, string, Guid, byte[].
Свойство SaveMode определяет, будет ли событие сохраняться в БД. Событие может
храниться как в базовой таблице, в которой находятся только поля класса RawEvent,
так и в специальной, содержащей все поля события.
Также имеется возможность сохранять событие в обе таблицы. Использование базовой
таблицы позволяет фиксировать сам факт возникновения события в системе.
В будущем пользователь может читать из базовой таблицы события штатными
средствами Macroscop.
 19

Пользовательское событие может быть представлено следующим образом:

[GuidAttribute("389EDCE2-54BB-4C2C-9984-51B7516A5DDF")]
[EventLocalizedName("Оставлен предмет")]
[EventSaveable([Link], "objectleft")]
[EventGeneratesAlarmByDefault]
[Serializable][AlarusSerializable]
public class ObjectLeftEvent : RawChannelEvent
{
[EventFieldSaveableOrScenariesUsable(0, true)]
[EventFieldLocalizedName("Предмет")]
private string objectName;

public ObjectLeftEvent(string objectName)

{
[Link] = objectName;
}

public override EventTextDescription GetDescription(IToStringConverter converter)

{
var eventText = "Оставлен предмет";
var eventDescription = new EventTextDescription(eventText);

return eventDescription;
}

Для регистрации плагина Видеоаналитика необходимо на этапе загрузки сборки

с плагином в методе инициализации класса, реализующего интерфейс IPlugin, вызвать
метод RegisterAnalyst интерфейса хоста (см. Регистрация плагинов в Macroscop).
 20

Плагин Трекер
Плагин данного типа позволяет сделать трекер для Macroscop. Для этого необходимо
создать наследника класса Tracker:
/// <summary>
/// Базовый класс для всех трэкеров.
/// </summary>
public abstract class Tracker
{
/// <summary>
/// Обработка кадра и карты движения.
/// Результатом обработки является измененная карта движения, на которой корректно
/// проставлены индексы движущихся объектов.
/// </summary>
/// <param name="width">Ширина кадра.</param>
/// <param name="height">Высота кадра.</param>
/// <param name="offset">Отступв в байтах до начала кадра в массиве байт.</param>
/// <param name="stride">Страйд.</param>
/// <param name="bgr24bytes">Байты с пикселами кадра.</param>
/// <param name="timestamp">Временная метка.</param>
/// <param name="detectedMap">Продетектированная карта движения. Значение может
/// измениться после обработки.</param>
public abstract void Process(int width, int height, int offset, int stride, byte[]
bgr24bytes, DateTime timestamp, ref MotionMap detectedMap);
}
Основная логика работы реализуется методом Process. Данному методу на вход
поступает кадр формата bgr24 (каналы Blue, Green, Red, 8 бит на каждый канал)
и карта движения MotionMap, полученная плагином Детектор движения. Результатом
работы плагина являются идентификаторы сопровождаемых объектов, которые должны
быть проставлены в карте движения.

Плагин Визуализатор
Плагин данного типа позволяет графически отображать информацию (например, рамки
движущихся объектов, распознанные номера, лица и др.) содержащуюся в событиях,
которые поступают в каналы приложения Macroscop Клиент. Для создания данного
типа плагина необходимо создать наследника класса PluginVisualiser:
/// <summary>
/// Класс визуализатора.
/// </summary>
public abstract class PluginVisualiser
{
public abstract DrawingVisual NullableDrawingVisual { get; }

/// <summary>
/// Панель для отрисовки примитивов, текста и другой информации на канале.
/// </summary>
protected IDrawingPanel DrawPanel;

/// <summary>
/// Контейнер графических элементов. Позволяет размещать отдельные
/// UserControl'ы в канале.
/// </summary>
protected Canvas ControlsContrainer;

protected IPluginClientToolSet PluginClientToolset;

public readonly Guid AnalystPluginId;

public bool ArchiveMode;

 21

public virtual IVideoTransformer VideoTransformer

{
get { return null; }
}

protected PluginVisualiser(Guid analystPluginId)

{
AnalystPluginId = analystPluginId;
ArchiveMode = false;
}

/// <summary>
/// заданы ли пользователем настройки визуализатора
/// </summary>
protected bool _hasUserSettings;

public bool HasUserSettings

{
get { return _hasUserSettings; }
}

/// <summary>
/// Инициализация визуализатора. Вызывается хостом.
/// </summary>
public virtual void Initialize(Guid channelId, IPluginClientToolSet
pluginClientToolset, IPluginVisualizerSet visualiserSet)
{
PluginClientToolset = pluginClientToolset;
DrawPanel = [Link];
ControlsContrainer = [Link];
RegisterPluginMenuAction = [Link];

if ([Link] == null)
_hasUserSettings = false;
else
_hasUserSettings = true;
}

/// <summary>
/// Обработка события визуалайзером. Специфическая отрисовка результатов события.
/// </summary>
/// <param name="channelId">Идентификатор канала</param>
/// <param name="chEv">Событие.</param>
/// <param name="isAlarm">Является ли событие тревожным</param>
public abstract void ProcessEvent(Guid channelId, RawEvent chEv, bool isAlarm);

/// <summary>
/// Делегат для регистрации подпункта во всплывающем меню канала в клиенте
/// Macroscop.
/// Заполняется хостом. Вызывается визуализатором.
/// </summary>
protected RegisterPluginMenuActionHandler RegisterPluginMenuAction;

/// <summary>
/// Очистка всего, что нарисовано визуализатором.
/// </summary>
public abstract void Clear();
/// <summary>
/// Освобождение всех ресурсов. В перегружаемых метода в наследниках обязательно
/// вызывать Release базового класса.
/// </summary>
 22

public virtual void Release()

{
// сделал, это чтобы очищались ресурсы визуализаторов, т.к. по факту реализации
// не перегружают Release,а копипастить неохото.
Clear();

DrawPanel = null;
ControlsContrainer = null;
PluginClientToolset = null;
}

public void SetPresentationModeIfNeed()

{
if (!HasUserSettings)
SetPresentationMode();
}

/// <summary>
/// Переопределить в визуализаторе плагина, если требуется автоматическое
/// отображение результатов/настроек плагина в демо-версии
/// </summary>
protected virtual void SetPresentationMode()
{

public virtual void SetDigitalZoomStatus(bool isDigitalZoomActive)

{
}
}

Каждый плагин Визуализатор должен определять метод ProcessEvent, на вход

которому передается очередное событие, поступившее в канал. Все события
генерируются Macroscop или другими плагинами.
Плагин может визуализировать любые типы событий, а их фильтрацию можно
осуществить с помощью оператора if и ключевого слова is, например:
if (chEv is CounterEvent)
{
...
}
Визуализатор может регистрировать свой подпункт во всплывающем меню,
отображаемом при щелчке правой кнопки мыши на канале в приложении Macroscop
Клиент. Это позволяет изменять логику работы визуализатора в зависимости
от предпочтений пользователя. Данная возможность предоставляется делегатом
RegisterPluginMenuAction.
Для регистрации плагина-визуализатора в системе, необходимо на этапе загрузки сборки
с плагином в методе инициализации класса, реализующего интерфейс IPlugin, вызвать
метод RegisterRTVisualizer интерфейса хоста (см. Регистрация плагинов в Macroscop).

Плагин Элемент меню

Плагин данного типа позволяет создавать собственный графический интерфейс,
открываемый через подпункт меню Дополнительно приложения Macroscop Клиент.
Типичное применение данного плагина заключается в организации клиент-серверного
взаимодействия с другими плагинами. Например, плагин может обрабатывать результаты
работы аналитических плагинов, работающих на сервере. Для создания плагина-
элемента меню необходимо реализовать интерфейс IClientPluginMenuItem:
public interface IClientPluginMenuItem
 23

{
void ShowWindow(IPluginClientToolSet pluginToolSet);

string Header { get; }

string ImageName { get; }

bool HasActivePlugins(IPluginClientToolSet pluginToolSet);

}
В классе-наследнике необходимо определить метод ShowWindow, в который со стороны
хоста (приложения Macroscop Клиент) передается интерфейс с сервисными
функциями. Эти функции позволяют получить идентификаторы каналов и их имена в
текущей конфигурации. Кроме того, они предоставляют доступ к архиву Macroscop,
возможность отправлять команды аналитическим плагинам на сервере и получать
результат
их исполнения. Имеется возможность подписываться на любые события, возникающие
в системе. Интерфейс представляется следующим образом:
/// <summary>
/// Интерфейс предоставляемый хостом для
/// доступа в архив, для отправки команд, для
/// подписки на события в системе.
/// </summary>
public interface IPluginClientToolSet
{
/// <summary>
/// Получает информацию о том, доступно ли текущему пользователю редактирование
/// данных в клиенте в интеллектуальных плагинах
/// </summary>
bool CanAccessEditingAnalystPluginsInClient { get; }

/// <summary>
/// Получает информацию о том, доступно ли текущему пользователю доступ к базам
/// данных
/// </summary>
bool CanUseDatabase { get; }

/// <summary>
/// Получает информацию о том, доступны ли текущему пользователю отчеты
/// </summary>
bool CanUseReports { get; }

/// <summary>
/// Получает интерфейс для чтения конфигурации
/// </summary>
/// <returns></returns>
IPluginsConfigReader ConfigReader { get; }

/// <summary>
/// Получает интерфейс для работы с архивом
/// </summary>
/// <returns></returns>
IArchiveEventsReader ArchiveEventsReader { get; }

/// <summary>
/// Предоставляет перевод идентификаторов сущностей(каналы, пользователи, модули
/// аналитики, события)
/// в строковое представления для GUI.
/// </summary>
IToStringConverter ToStringConverter { get; }

IImageResizer ImageResizer { get; }

 24

/// <summary>
/// Отправляет команду плагину,
/// работающего на сервере.
/// </summary>
/// <param name="pluginId">Идентификатор плагина</param>
/// <param name="channelsId">Идентификаторы каналов</param>
/// <param name="cmdObj">Команда</param>
/// <returns>Возвращает результат от каждого канала. Ключ - идентификатор канала.
/// Значение - результат выполнения команды.</returns>
Dictionary<Guid, object> SendChannelsCommand(Guid pluginId, List<Guid> channelsId,
object cmdObj);

/// <summary>
/// Устанавливает/удаляет обработчик событий, возникающих в канале.
/// </summary>
/// <param name="subscrId">Идентификатор подписчика</param>
/// <param name="channelId">Идентификатор канала</param>
/// <param name="eventsHandler">Обработчик. Если null, то ранее установленный
/// обработчик удаляется.</param>
void SetEventsHandler(Guid subscrId, Guid channelId, EventsHandler eventsHandler);

/// <summary>
/// Контроллер, отвечающий за взаимодействие различных GUI подсистем внутри
/// плагина.
/// </summary>
IGuiScreensInteractionController InteractionController { get; }
}

Свойство ArchiveEventsReader предоставляет интерфейс доступа к архиву. Подробные

сведение о данном интерфейсе размещены в исходных кодах Macroscop SDK.
Метод SendChannelsCommand отправляет команду разным экземплярам плагина
одного и того же типа по указанному списку каналов и получает результаты исполнения
команды. Метод SetEventsHandler устанавливает или удаляет обработчик событий на
заданном канале.
В методе ShowWindow должна быть реализована логика работы с пользователем через
графический интерфейс. Данный метод вызывается в момент щелчка клавиши мыши
(клавиатуры) по пункту меню, связанному с плагином.
Для регистрации плагина Элемент меню необходимо на этапе загрузки сборки с
плагином в методе инициализации класса, реализующего интерфейс IPlugin, вызвать
метод RegisterMenuItem интерфейса хоста (см. Регистрация плагинов в Macroscop).

Плагин Процессор событий

Плагин Процессор событий позволяет получать и обрабатывать сигналы от сторонних
систем. В процессе обработки сигналов данный тип плагина может как выполнять
команды в канале, в котором он существует, так и генерировать в этом канале события.
Данный плагин создается путем наследования от базового класса EventProcessor:
/// <summary>
/// Класс плагина для обработки событий системы, генерации команд и своих событий
/// </summary>
public abstract class EventProcessor : IDisposable
{
/// <summary>
/// Инициализация. Вызывается хостом.
/// </summary>
/// <param name="settings">Настройки плагина</param>
public abstract void Initialize(PluginSettings settings);
 25

/// <summary>
/// Генерирует в каналее ранее зарегистрированное внешнее событие. Заполняется
/// хостом. Вызывается плагином.
/// </summary>
public GenerateEventDelegate GenerateEvent;

/// <summary>
/// Запускает заданную команду на выполнение в канале. Заполняется хостом.
/// Вызывается плагином.
/// </summary>
public ExecuteCommandExDelegate ExecuteCommandSync;

/// <summary>
/// Позволяет подписываться на события, происходящие в канале. Заполняется плагином
/// при необходимости на этапе инициализации.
/// </summary>
public ReceiveEventDelegate OnChannelEventReceived;

/// <summary>
/// Изменяет общие или специфические настройки, если это необходимо.
/// Вызов метода должен приводить к появлению пользовательского окна настройки.
/// Вызывается хостом (конфигуратором).
/// </summary>
/// <param name="settings">Текущие настройки плагина.</param>
/// <returns>Новые настройки плагина.</returns>
public abstract PluginSettings SetSettings(PluginSettings settings);

public abstract void Dispose();

}
Производный класс должен иметь обязательный атрибут PluginGUINameAttribute,
содержащий название плагина, отображаемое в приложении Macroscop
Конфигуратор. Если плагин может быть настроена в конфигураторе, следует
реализовать метод настройки SetSettings и указать атрибут
PluginHasSettingsAttribute.
В метод инициализации Initialize со стороны хоста передается объект настроек плагина.
Поскольку каждый плагин прикрепляется пользователем к тому или иному каналу,
объект настроек PluginSettings состоит из 2 частей:
1) настройки, связанные с текущим каналом безопасности;
2) общие настройки, не зависящие от выбранного канала безопасности.
public struct PluginSettings
{
/// <summary>
/// Специфические настройки плагина, связанные с текущим каналом.
/// Объект настроек должен быть сериализуемым.
/// </summary>
public object channelSpecificSettings;

/// <summary>
/// Общие настройки плагина. Не зависят от текущего канала. Может быть null.
/// Объект настроек должен быть сериализуемым.
/// </summary>
public object generalSettings;
}
 26

Если настройки едины для всех каналов, то заполняется объект общих настроек. В
случае, когда все настройки плагина привязываются к конкретному каналу, достаточно
заполнять только объект специфических настроек канала. Объекты общих и
специфических настроек являются пользовательскими (объект настройки канала всегда
отличен от null); одним из требованием к ним является возможность сериализации,
поскольку все настройки плагина хранятся в общей конфигурации Macroscop. Если
плагину в качестве результата своей работы необходимо выполнить определенную
команду в канале (например, включить/выключить запись, установить пресет на камере,
повернуть камеру и т.д.), требуется создать объект команды.
На текущий момент реализованы следующие команды:
● RawEnableRecordingCommand — включает запись в канале, опционально
указывается интервал записи;
● RawDisableRecordingCommand — выключает запись в канале;
● RawGoToPresetPtzCommand — устанавливает пресет на камере;
● RawGoHomePtzCommand — устанавливает домашнее положение камеры;
● RawStopPtzCommand — останавливает выполнение ptz команд на камере;
● RawMovePtzCommand — перемещение на шаг;
● RawZoomPtzCommand — относительное приближение (зум);
● RawStartMovePtzCommand — непрерывное (желательно плавное) движение;
● RawMoveToPtzCommand — поворачивает камеру таким образом, что указанная
точка оказывается в центре области кадра;
● RawSetDigitalOutputCommand — устанавливает уровень сигнала на выходе
камеры;
● RawSetDigitalPulsesCommand — генерирует последовательность импульсов на
выходе камеры;
Плагин Процессор событий может подписываться на события, возникающие в канале.
Для этого на этапе своей инициализации плагин должен заполнить делегат
OnChannelEventReceived. Кроме того, плагин может генерировать собственные
события в канале.
Для регистрации плагина Процессор событий необходимо на этапе загрузки сборки
с плагином в методе инициализации класса, реализующего интерфейс IPlugin, вызвать
метод RegisterEventProcessor интерфейса хоста (см. Регистрация плагинов в
Macroscop).

Плагин Получатель кадров

Плагин данного типа позволяет получать видео и звук с IP-устройств (камер), данные
о детекции движения, управлять поворотными камерами, управлять входами/выходами
(I/O) IP-устройств. Для решения подзадачи получения кадров необходимо реализовать
интерфейс ICameraServiceProvider:
/// <summary>
/// Интерфейс получения кадров реального времени.
/// Используется для создания плагинов, получающих кадры
/// с IP-камер.
/// </summary>
public interface ICameraServiceProvider
{
/// <summary>
/// Асинхронное получение информации об устройстве
/// </summary>
/// <param name="callback"></param>
/// <param name="state"></param>
/// <returns></returns>
IAsyncResult BeginGetCapabilities(AsyncCallback callback, object state);

/// <summary>
 27

/// Завершает асинхронный запрос на получение информации об устройстве

/// </summary>
/// <param name="asyncResult"></param>
/// <returns></returns>
DeviceCapabilities EndGetCapabilities(IAsyncResult asyncResult);

/// <summary>
/// Обработчик события о приходе нового кадра.
/// Вызывается реализующей интерфейс стороной.
/// На событие подписывается хост.
/// </summary>
event NewRawFrameEventHandler NewRawFrame;

/// <summary>
/// Обработчик событий. Вызывается реализующей интерфейс стороной.
/// На обработчик подписывается хост.
/// </summary>
event NewRawEventHandler NewEvent;

/// <summary>
/// Является ли поток активным
/// </summary>
/// <param name="streamType">Тип потока</param>
/// <returns></returns>
bool IsStreamActive(ChannelStreamTypes streamType);

/// <summary>
/// Запускает поток указанного типа для получения кадров
/// </summary>
/// <param name="channelStreamType"></param>
void StartStream(ChannelStreamTypes channelStreamType);

/// <summary>
/// Останавливает поток указаного типа
/// </summary>
/// <param name="channelStreamType"></param>
void StopStream(ChannelStreamTypes channelStreamType);

/// <summary>
/// Отправляет звук на устройство (случай реализации дуплексного звука).
/// </summary>
/// <param name="frame"></param>
void SendSound(RawSoundFrame frame);

/// <summary>
/// Интерфейс работы с PTZ
/// </summary>
/// <returns></returns>
IPtzController GetPtzController();

/// <summary>
/// Интерфейс работы с цифровыми выходами
/// </summary>
/// <returns></returns>
IDigitalOutputsController GetDigitalOutputsController();

/// <summary>
/// Интрейфес для работы с архивом устройства
/// </summary>
/// <returns></returns>
IDeviceArchiveController GetDeviceArchiveController();
 28

/// <summary>
/// Освобождает все ресурсы. Закрывает все потоки.
/// </summary>
void Release();
}
При реализации данного интерфейса необходимо создать механизм работы с потоками
данных. Потоки данных представляют собой или последовательность кадров
определенного типа, или последовательность событий. В текущей версии Macroscop
SDK имеются следующие типы потоков данных:
/// <summary>
/// Типы потоков канала.
/// </summary>
[Flags]
public enum ChannelStreamTypes
{
/// <summary>
/// Главный поток видео
/// </summary>
[Description("[Link]")]
MainVideo = 1,

/// <summary>
/// Альтернативный поток видео
/// </summary>
[Description("[Link]")]
AlternativeVideo = 2,

/// <summary>
/// Поток звука, идущий с камеры.
/// </summary>
[Description("[Link]")]
MainSound = 4,

/// <summary>
/// Альтернативный звуковой поток
/// </summary>
[Description("[Link]")]
AlternativeSound = 8,

/// <summary>
/// Обратный поток звука.
/// </summary>
[Description("[Link]")]
OutputSound = 16,

/// <summary>
/// Поток данных детекции движения.
/// </summary>
[Description("[Link]")]
MotionDetection = 32,

/// <summary>
/// Поток данных от системы ввода-вывода камеры
/// </summary>
[Description("[Link]")]
IO = 64,

/// <summary>
/// Архивное видео
/// </summary>
[Description("[Link]")]
 29

ArchiveVideo = 128,

/// <summary>
/// Архинвый звук
/// </summary>
[Description("[Link]")]
ArchiveSound = 256,
}
В зависимости от возможностей подключаемого устройства, а также от настроек канала
в конфигураторе, необходимо генерировать те или иные потоки данных.
Потоки данных MainVideo и AlterntaiveVideo состоят из видеокадров RawVideoFrame,
получаемых с камеры.
Потоки данных MainSound и AlternativeSound, OutputSound состоят
из последовательности звуковых кадров RawSoundFrame.
Запуск потоков данных происходит со стороны хоста с помощью метода StartStream,
в котором производится необходимая инициализация очередного потока. Метод должен
сразу же возвращать управление хосту, а длительные операции (операции
ввода/вывода) выполнять в отдельных потоках. Остановка потоков и проверка
их активности методами StopStream и IsStreamActive также вызывается со стороны
хоста и должны выполняться немедленно без выполнения долгосрочных операций.
Результаты своей работы потоки должны возвращать хосту через вызовы обработчиков
кадров (NewRawFrame) и событий (NewEvent).
Например, если IP-устройство шлет MJPEG-кадры, то поток данных MainVideo
(или AlternativeVideo) должен вызывать NewRawFrame и в качестве одного
из аргументов передавать видеокадр RawMJPEGFrame:
/// <summary>
/// MJPEG кадр
/// </summary>
[Serializable][AlarusSerializable]
public class RawMJPEGFrame : RawVideoFrame
{
private bool _isNMjpegFrame;

public bool IsNMjpegFrame

{
get { return _isNMjpegFrame; }
set { _isNMjpegFrame = value; }
}

public RawMJPEGFrame()
{
}

public RawMJPEGFrame(IReferencedBytes refBytes)

{
UndecodedRefData = refBytes;
}
}
Аналогично для потока данных MainSound (или AlterntaiveSound) и звука в формате
G.711U, необходимо передавать кадр RawG711UFrame:
/// <summary>
/// Кадр стандарта G.711U
/// </summary>
[Serializable][AlarusSerializable]
public class RawG711UFrame : RawSoundFrame
{
public RawG711UFrame()
{
 30

/// <summary>
/// Данные кадра
/// </summary>
public RawG711UFrame(IReferencedBytes refBytes)
{
UndecodedRefData = refBytes;
SamplesPerSecond = 8000;
BitsPerSample = 16;
Channels = 1;
Bitrate = 64000;
}

/// <summary>
/// Размер фрэйма должен быть выравнен на размер минимального блока данных,
/// с которыми работает декодер
/// </summary>
/// <returns>Возвращает гранулярность фрэйма</returns>
public static int Granularity()
{
return 80;
}
}
Пример создания MJPEG-кадра доступен в проекте [Link].
В случае если в процессе получения потоков данных произошел обрыв связи
с IP- устройством, плагин Получатель кадров должен уведомить об этом хост путем
генерации события NoDataConnectionDeviceEvent с обязательно заполненным полем
StreamTypesMask, показывающим, в каких потоках данных произошел обрыв
соединения.
Для регистрации получателя кадров в системе необходимо заполнить регистрационную
информацию устройства DevType_RegInfo и регистрационную информацию потока
получения данных MediaStream_RegInfo. Ниже приведено описание класса
DevType_RegInfo:
/// <summary>
/// Регистрационная информация устройства.
/// используется при регистрации плагина,
/// получающего кадры.
/// </summary>
public class DevType_RegInfo
{
/// <summary>
/// Идентификатор устройства.
/// </summary>
public Guid DeviceTypeGuid;

/// <summary>
/// Альтернативные идентификаторы устройства, если есть
/// </summary>
public Guid[] DeviceAlternativeGuids;

/// <summary>
/// Имя производителя.
/// </summary>
public string DevTypeBrandName;

/// <summary>
/// Имя устройства.
/// </summary>
 31

public string DevTypeModelName;

/// <summary>
/// Список возможностей устройства в целом.
/// </summary>
public DevType_Capabilities Capabilities;

/// <summary>
/// Панорамные режимы.
/// </summary>
public PanoramicMode[] PanoramicModes;

/// <summary>
/// Список доступных разрешений для данного устройства.
/// </summary>
public List<Resolution> AvailableResolutions = new List<Resolution>();

/// <summary>
/// Делегат, позволяющий хосту изменять настройки на камере/видеосервере.
/// </summary>
public SetDeviceParametersDelegate SetDeviceParameters;

/// <summary>
/// Получение интерфейса ICameraServiceProvider.
/// </summary>
public GetCameraServiceDelegate GetCameraService;

/// <summary>
/// Получение доп. возможностей (доступные разрешения, фпс, кодеки) конкретного
/// устройства
/// </summary>
public GetAdditionalCapabilitiesDelegate GetAdditionalCapabilities;

/// <summary>
/// Описание портов, которые можно указывать плагину извне
/// </summary>
public List<ExternalNetworkPortDescriptor> ExternalNetworkPortDescriptors;

/// <summary>
/// Список поддерживаемых устройством кодеков при передаче звука
/// </summary>
public OutputSoundCodec SupportedOutputSoundCodec;

/// <summary>
/// Динамическое получение кодека передачи звука. SupportedOutputSoundCodecs должен
/// быть выставлен в Dynamic.
/// </summary>
public GetOutputSoundCodec GetOutputSoundCodec;

/// <summary>
/// Набор инструментов для автопоиска устройства
/// </summary>
public GetDiscoveryKitDelegate GetDiscoveryKit;

/// <summary>
/// Делегат для смены IP-адреса
/// </summary>
public ChangeIpAddressDelegate ChangeIpAddress;

/// <summary>
/// Требования для смены IP-адреса
 32

/// </summary>
public ChangeIpAddressRequirements ChangeIpAddressRequirements;

/// <summary>
/// Тип архива устройства
/// </summary>
public DeviceStorageType StorageType;

/// <summary>
/// Скорости воспроизведения архива
/// </summary>
public double[] ArchivePlaybackSpeeds;

/// <summary>
/// Список поддерживаемых аналитиков устройства.
/// </summary>
public CameraBuiltInAnalystDescription[] CameraBuiltInAnalystDescriptions;
}

Возможности IP-устройства, с которым работает плагин Получатель кадров,

описываются полем Capabilities:
/// <summary>
/// Перечень возможностей устройства
/// </summary>
[Flags]
public enum DevType_Capabilities : ulong
{
//Коды 512, 1024 и 2048 свободны

/// <summary>
/// Устройство работает только с камерами.
/// </summary>
SupportsCameras = 1,
/// <summary>
/// Устройство поддерживает камеры и видеосерверы.
/// </summary>
SupportsCamerasAndServers = 2,
/// <summary>
/// Устройство поддерживает работу с альтернативным потоком.
/// </summary>
SupportsAlternativeVideoStream = 4,
/// <summary>
/// Параметры (разрешение, фпс, компрессия), описываемые массивами
/// SupportedDeviceParameters/SupportedExtraParameters, не зависят от формата
/// потока (одинаковы для mjpeg, mpeg4, h264).
/// </summary>
/// <remarks>
/// Данный флаг НАДО ВЫСТАВЛЯТЬ, если медиапуть для выполнения CGi-запроса НЕ
/// СОДЕРЖИТ "mjpeg", "mpeg4", "h264". В противном случае (если флаг используется),
/// будет всегда дергаться функция SetCameraSettings у класса для подключения
/// MJPEG, а у других классов она будет игнорироваться (как например на Axis).
/// </remarks>
DeviceParametersFormatIndependent = 8,

/// <summary>
/// Устройство может иметь архив
/// </summary>
SupportsArchive = 16,

/// <summary>
/// Устройство поддерживает воспроизведение архива в обратном направлении
/// </summary>
 33

DeviceSupportsBackwardDirectionInArchive = 32,

/// <summary>
/// Устройство является видеорегистратором
/// </summary>
DeviceIsDvr = 64,

/// <summary>
/// Необходимо начинать отсчет каналов в регистраторе или видеосервере с одного, а
/// не с нуля как по умолчанию.
/// </summary>
ServerStartChannelFromOne = 128,

/// <summary>
/// Реализован метод явного получения возможностей устройства
/// </summary>
GettingCapabilitiesSupports = 256,

/// <summary>
/// Поддержка панорамных камер
/// </summary>
SupportsPanoramicCameras = 4096,

/// <summary>
/// Поддержка PTZ
/// </summary>
SupportsPtz = 8192,

/// <summary>
/// Поддержка цифровых выходов
/// </summary>
SupportsDigitalOutputs = 16384,

/// <summary>
/// Поддержка омывателя
/// </summary>
SupportsWasherAdjusting = 32768,

/// <summary>
/// Необходимость использования портов из внешних источников
/// </summary>
ExternalNetworkPortsRequired = 65536,

/// <summary>
/// Поддержка коррекции видео с SD-карты
/// </summary>
SupportsSDVideoCorrection = 131072,

/// <summary>
/// Поддержка стабилизации видео с SD-карты
/// </summary>
SupportsSDVideoStabilization = 262144,

/// <summary>
/// Поддержка множественного доступа к архиву устройства
/// </summary>
NotSupportsStorageConcurrentAccess = 524288,

/// <summary>
/// Поддержка домофонов
/// </summary>
SupportsDoorphone = 1048576,
 34

/// <summary>
/// Поддержка работы некоторых функций камеры по защищённому протоколу
/// </summary>
SupportsSecureConnection = 2097152
}

Если требуется решить задачу управления поворотной камерой или ее выходами,

необходимо реализовать соответствующие интерфейсы IPtzController и/или
IDigitalOutputsController:
/// <summary>
/// Унифицированный интерфейс реализации управления поворотной камерой.
/// </summary>
public interface IPtzController
{
/// <summary>
/// Инициализация камеры.
/// </summary>
/// <returns></returns>
void Reinitialization();

/// <summary>
/// Зачистка ресурсов
/// </summary>
void CleanUp();

/// <summary>
/// Возвращает возможности данной камеры.
/// </summary>
/// <returns></returns>
PtzCapabilities GetCapabilities();

/// <summary>
/// Возвращает названия пресетов, установленных на камере.
/// Количество элементов результирующего массива соответствует количеству пресетов.
/// Каждому пресету соответствует номер, равняющийся индексу в массиве.
/// </summary>
/// <returns>Названия пресетов, установленных на камере.</returns>
string[] GetPresetsNames();

/// <summary>
/// Устанавливает пресет по его номеру.
/// </summary>
/// <param name="presetIndex">Номер пресета.</param>
void SetPresetPosition(int presetIndex);

/// <summary>
/// Устанавливает камеру в "домашнее" положение.
/// </summary>
void MoveToHome();

/// <summary>
/// Прекращает выполнение любой команды PTZ.
/// </summary>
void Stop();

/// <summary>
/// Перемещение на шаг.
/// </summary>
/// <param name="panSpeed">Скорость по горизонтали. Интервал от -100 до
 35

/// 100.</param>
/// <param name="tiltSpeed">Скорость по вертикали. Интервал от -100 до 100.</param>
void StepMove(int panSpeed, int tiltSpeed);

/// <summary>
/// Непрерывное(желательно плавное) движение.
/// <para/>
/// Если горизонтальная и вертикальная скорость равны 0 - непрерывное движение
/// будет остановлено.
/// </summary>
/// <param name="panSpeed">Скорость по горизонтали. Интервал от -100 до
/// 100.</param>
/// <param name="tiltSpeed">Скорость по вертикали. Интервал от -100 до 100.</param>
void ContiniousMove(int panSpeed, int tiltSpeed);

/// <summary>
/// Относительное приближение.
/// </summary>
/// <param name="step">Шаг от 1 до 100.</param>
void StepZoomIn(int step);

/// <summary>
/// Относительное отдаление.
/// </summary>
/// <param name="step">Шаг от 1 до 100.</param>
void StepZoomOut(int step);

/// <summary>
/// Непрерывное (желательно плавное) приближение.
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Скорость равная 0 означает
/// остановку непрерывного зума.</param>
void ContiniousZoomIn(int speed);

/// <summary>
/// Непрерывное (желательно плавное) отдаление.
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Скорость равная 0 означает
/// остановку непрерывного зума.</param>
void ContiniousZoomOut(int speed);

/// <summary>
/// Возвращает максимальное увеличение камеры.
/// </summary>
/// <returns>Максимальное увеличение камеры. Если функция не поддерживается,
/// возвращает отрицательное число.</returns>
double GetMaxZoomFactor();

/// <summary>
/// Возвращает текущее увеличение камеры.
/// </summary>
/// <returns>Текущее увеличение камеры. Если функция не поддерживается, возвращает
/// отрицательное число.</returns>
double GetCurrentZoomFactor();

/// <summary>
/// Устанавливает абсолютное увеличение. Ничего не делает, если камера это не
/// поддерживает. См. PtzCapabilities.
/// </summary>
void SetZoomFactor(double factor);
 36

/// <summary>
/// Устанавливает максимальное увеличение.
/// </summary>
void ZoomTele();

/// <summary>
/// Устанавливает минимальное увеличение.
/// </summary>
void ZoomWide();

/// <summary>
/// Поворачивает камеру таким образом, что указанная точка оказывается в центре
/// области кадра.
/// </summary>
/// <param name="point">Точка изображения, которую необходимо поместить в центр
/// путём поворота камеры.
/// Задаётся в пикселях. Начало отсчета(0,0) - левый верхний угол кадра о</param>
/// <param name="frameSize">Размер кадра в пикселях</param>
void MoveTo([Link] point, [Link] frameSize);

/// <summary>
/// Поворачивает и масштабирует камеру таким образом,
/// что указанный прямоугольник занимает всю область кадра.
/// Если пропорции прямоугольника не соответсвуют пропорциям кадра, то
/// масштабирование производится таким образом, чтобы прямоугольник весь вошёл в
/// кадр.
/// Центр прямоугольника помещается в центр кадра.
/// </summary>
/// <param name="rect">Прямоугольник, задается в пикселях</param>
/// <param name="frameSize">Размер кадра в пикселях</param>
void ShowRect([Link] rect, [Link] frameSize);

/// <summary>
/// Устанавливает автоматическое управление фокусом
/// </summary>
void SetAutoFocus();

/// <summary>
/// Дальний фокус
/// </summary>
/// <param name="step">Шаг 1 до 100.</param>
void FocusFar(int step);

/// <summary>
/// Ближний фокус
/// </summary>
/// <param name="step">Шаг 1 до 100.</param>
void FocusNear(int step);

/// <summary>
/// Непрерывный (желательно плавный) дальний фокус
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Если скорость равна 0 -
/// непрерывный фокус будет остановлен.</param>
void ContiniousFocusFar(int speed);

/// <summary>
/// Непрерывный (желательно плавный) ближний фокус
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Если скорость равна 0
/// - непрерывный фокус будет остановлен.</param>
void ContiniousFocusNear(int speed);
 37

/// <summary>
/// Устанавливает автоматическое управление диафрагмой
/// </summary>
void SetAutoIris();

/// <summary>
/// Закрывает диафрагму.
/// </summary>
/// <param name="step">Шаг 1 до 100.</param>
void IrisOpen(int step);

/// <summary>
/// Приоткрывает дифаргаму.
/// </summary>
/// <param name="step">Шаг 1 до 100.</param>
void IrisClose(int step);

/// <summary>
/// Непрерывное (желательно плавное) открытие диафрагмы.
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Если скорость равна 0 -
/// непрерывное открытие диафрагмы будет остановлено.</param>
void ContiniousIrisOpen(int speed);

/// <summary>
/// Непрерывное (желательно плавное) закрытие диафрагмы.
/// </summary>
/// <param name="speed">Скорость. Интервал от 1 до 100. Если скорость равна 0 -
/// непрерывное закрытие диафрагмы будет остановлено.</param>
void ContiniousIrisClose(int speed);

/// <summary>
/// Включить подсветку
/// </summary>
void TurnOnInfraredLight();

/// <summary>
/// Выключить подсветку
/// </summary>
void TurnOffInfraredLight();

/// <summary>
/// Запустить стеклоочиститель
/// </summary>
void TurnOnWiper();

/// <summary>
/// Отстановить стеклоочиститель
/// </summary>
void TurnOffWiper();

/// <summary>
/// Запустить омыватель
/// </summary>
void RunWasher();
}

/// <summary>
/// Уинифицированный интерфейс реализации управления выходами камеры
/// </summary>
 38

public interface IDigitalOutputsController

{
/// <summary>
/// Инициализация
/// </summary>
/// <returns></returns>
void Reinitialization();

/// <summary>
/// Зачистка ресурсов
/// </summary>
void CleanUp();

/// <summary>
/// Возвращает возможности данной камеры.
/// </summary>
/// <returns></returns>
DigitalOutputsCapabilities GetCapabilities();

/// <summary>
/// Устанавливает заданное значение на выходе
/// </summary>
/// <param name="portId">Номер выхода</param>
/// <param name="value">1 или 0</param>
void SetOutput(int portId, int value);

/// <summary>
/// Выдает последовательность импульсов (ШИМ) на указанном выходе.
/// Поддерживается не всеми камерами.
/// </summary>
/// <param name="portId">Номер выхода</param>
/// <param name="pulses">Массив импульсов</param>
void SetOutput(int portId, DigitalImpulse[] pulses);

/// <summary>
/// Получить текущие состояния всех выходов
/// </summary>
List<DigitalPort> GetOutputsStates();
}
Возможности устройства должны возвращаться методом GetCapabilities() для
информирования хоста о том, какие методы опциональных возможностей (если
поддерживаются устройством) реализованы в интерфейсе.
Регистрационную информацию DevType_RegInfo устройства необходимо указывать на
этапе загрузки сборки с плагином в методе инициализации класса, реализующего
интерфейс IPlugin, вызывая метод RegisterDevType интерфейса хоста
(см. Регистрация плагинов в Macroscop).
Помимо DevType_RegInfo, необходимо также заполнить информацию о получателе
кадров MediaStream_RegInfo:
/// <summary>
/// Регистрационная информация потока получения данных
/// </summary>
public class MediaStream_RegInfo
{
/// <summary>
/// Идентификатор устройства
/// </summary>
public Guid DeviceTypeGuid;
/// <summary>
/// Формат потока данных
/// </summary>
 39

public VideoStreamFormats StreamFormat;

/// <summary>
/// Используемый протокол подключения
/// </summary>
public NetworkConnectionTypes ConnectionType;

/// <summary>
/// Возможности устройства при заданном формате StreamFormat
/// </summary>
public MediaStream_Capabilities Capabilities;
}
Данную информацию нужно задать столько раз, сколько различных форматов потока
поддерживает IP-устройство.
Аналогично DevType_RegInfo, информацию MediaStream_RegInfo необходимо
задавать
на этапе загрузки сборки с плагином в методе инициализации класса, реализующего
интерфейс IPlugin. Для этого достаточно вызвать метод RegisterMediaStreamInfo
интерфейса хоста.
Пример заполнения данных классов доступен в проекте [Link].
40
 41

Macroscop API с интерфейсами HTTP и RTSP

Macroscop API позволяет обращаться к серверу по HTTP или RTSP интерфейсам
для получения видеопотоков реального времени и из архива, а также по HTTP
интерфейсу для получения информации о системе и отправки команд системе на
выполнение определенных действий. Ниже описаны различные типы запросов.

Пароль пользователя (параметр password) передается в виде MD5-хэша

в верхнем регистре.

HTTP-интерфейс для получения видео

Получение видео реального времени и архива
Наиболее простым способом получения потоков данных из Macroscop является HTTP
интерфейс. Получение видео реального времени по HTTP осуществляется следующим
общего вида CGI-запросом на сервер:
<адрес и порт сервера macrosop>/video?channel=<название канала>
&login=<имя пользователя>&password=<хэш-строка MD5 пароля>[&sound=on]
[&streamtype=alternative]
или
{адрес и порт сервера macrosop}/video?channelid=<id канала>
&login={имя пользователя}&password=<хэш-строка MD5 пароля>

[&sound=on][&streamtype=alternative]
Если у пользователя нет пароля, то параметр password можно опустить или оставить
его значение пустым. Опциональный параметр sound со значением on позволяет вместе
с видео в том же соединении получать звук путем чередования кадров. Звуковые кадры
всегда приходят в формате G.711U. Опционально можно запрашивать альтернативный
поток, который, как правило, идет в меньшем разрешении и может быть использован для
отображения.
В результате на указанный выше запрос сервер шлет «бесконечный» HTTP ответ,
в котором идут видео (и аудио) кадры, разделенные заголовками. Типичный ответ
сервера на запрос:
HTTP/1.1 200 OK
…
Content-Type: multipart/x-mixed-replace; boundary=myboundary

-- myboundary
Content-Type: image/jpeg
Content-Length: 63125

<тело JPEG кадра>

или

-- myboundary
Content-Type: audio, PCMU
Content-Length: 1000

<тело G711U кадра>

 42

Если на канале установлен формат потока MJPEG, то в значении параметра Content-

Type содержится строка image/jpeg. В случае MPEG-4 передается Content-Type
равный video, mpeg4, I-frame для I-кадров и video, mpeg4, P-frame для P-кадров.
В каждом опорном I-кадре имеется инициализирующая информация для декодера MPEG-
4. Аналогично, в случае H.264, для I-кадров в поле Content-Type содержится значение
video, h264, I-frame и video, h264, P-frame. Как и в случае MPEG4, перед каждым
I-кадром встраивается инициализирующая информация для декодера H.264.
Пример запроса для получения видео реального времени:
[Link]
Во избежание коллизий, рекомендуется вместо имени канала передавать его
идентификатор в параметре channelid:
[Link]
&login=root&password=
Также для задания канала можно использовать его порядковый номер в конфигурации
(начинается с нуля):
[Link]
Номер канала может измениться при изменении конфигурации (например,
при перемещении каналов внутри объектов безопасности и изменении их порядка),
поэтому из трех вышеперечисленных вариантов задания канала рекомендуется
использовать его идентификатор (channelid).
Для того чтобы получить конфигурацию, содержащую идентификаторы каналов
и их настройки, необходимо выполнить запрос:
{адрес и порт сервера macrosop}/configex?login=<имя пользователя>
&password=<хэш-строка MD5 пароля>
Пример запроса:
[Link]
Подробнее запрос конфигурации описан в разделе Получение конфигурации системы.
Для доступа в архив по HTTP интерфейсу достаточно сформировать следующий
CGI-запрос на сервер:
<адрес и порт сервера macrosop>/video?mode=archive
&startTime=[Link]+hh:mm:ss[.fff][&speed=n]&channel=<название канала>
[&channelid=id]&login=<имя пользователя>&password=<хэш-строка MD5 пароля>[&sound=on]
Параметр startTime является стартовой позицией, с которой начинается
воспроизведение архива. Его значение представляется в виде комбинации даты и UTC-
времени.
Опциональный параметр speed задает скорость воспроизведения архива.
Диапазон принимаемых значений является непрерывным и изменяется от 0.1 до 20.
Значение по умолчанию — 1.0.
Пример запроса:
[Link]
&speed=1&channel=Канал 1&login=root&password=

Получение перекодированного видео в формате MJPEG.

При обращении к интерфейсу /video сервер Macroscop будет возвращать видео
в оригинальном (полученном от камеры) формате. Для некоторых приложений
и непроизводительных устройств декодирование видео в формате H.264
или отображение MJPEG-видео в оригинальном разрешении может составить проблему.
 43

Для таких случаев в Macroscop есть CGI-обработчик /mobile. При запросе к нему
с параметрами, аналогичными запросу /video (логин, пароль, имя/номер/
идентификатор канала, воспроизведение звука, параметры архива), сервер Macroscop
будет возвращать видео в формате MJPEG (в том числе и для потоков, которые
транслируются с камер в формате H.264 и MGEG-4) в фиксированном разрешении,
определенном в приложении Macroscop Конфигуратор (вкладка Серверы,
блок настроек Подключение мобильных устройств).

Параметры запросов /mobile и /video:

Параметр sound со значением on позволяет вместе с видео получать звук. Звуковые

кадры приходят в формате G.711U.

Параметр streamtype с возможными значениями

main/alternative/secondalternative/thirdalternative позволяет запрашивать
определённый поток видео.

Параметр soundformat используется только в /mobile, позволяет запрашивать формат

звуковых кадров pcm/g711u/g711a/aac, по умолчанию используется G711U;

Параметр fps позволяет задать желаемое количество кадров в секунду. Реальное

количество кадров может не совпадать с запрошенным, т.к. зависит от многих
параметров потока и экспорта;

Параметр oneframeonly позволяет получить только один кадр, после чего прерывает
соединение;

Параметр mode со значением realtime позволяет открыть канал для просмотра

реального времени, а со значением archive канал с доступом в архив;

Параметр speed позволяет задать скорость воспроизведения архива.

Диапазон принимаемых значений является непрерывным и изменяется от 0.1 до 20.
Значение по умолчанию — 1.0.

Параметр isforward со значением true / false позволяет воспроизводить архив в прямом

или обратном порядке.

Параметр starttime позволяет указать время, с которого начинается воспроизведение

архива. Это значение задается в виде комбинации даты и UTC-времени в следующем
формате [Link] H:mm:ss или [Link] H:mm:[Link].

Для отображения видеопотока в браузере необходимо задать в параметр

withcontenttype значение true. Значение по умолчанию — false.

Настройки перекодирования возвращаются в разделе MobileServerInfo

XML-конфигурации, получаемой по запросу /configex).
Получение перекодированного видео может быть запрещено для группы, в которой
состоит пользователь. В этом случае в XML-конфигурации (по запросу /configex)
в разделе UserGroup параметр CanGetTranscodedVideoFromMobileServer
будет иметь значение false.
 44

По умолчанию возвращается самое низкое разрешение. Более высокое разрешение

можно запросить, задав параметр resolutionx для ширины и resolutiony для высоты
(целое положительное число пикселей). Например:
[Link]
В этом случае будет возвращено наиболее подходящее из разрешений, определенных
в настройках мобильных подключений сервера.
Каждому разрешению соответствует максимальная частота кадров (определяется
в настройках). Клиент может запросить более низкую частотe кадров, задав в запросе
параметр fps (целое положительное — число кадров в секунду). Если задать параметр
fps больше максимального значения, или не задать вовсе, то видео сервера будет
передаваться с максимально возможной частотой для запрошенного разрешения.
Например:
[Link]
&login=root&resolutionx=640&resolutiony=480&fps=10

HTTP-интерфейс для получения данных

Запросы для получения данных в общем виде имеют следующий вид:
{адрес и порт сервера macrosop}/<команда>?login=<имя пользователя>
&password=<хэш-строка MD5 пароля>&<Параметр 1>&<Параметр 2>...
По умолчанию, данные возвращаются в формате XML. Однако, для части запросов
реализована возможность возвращать данные в формате JSON — для этого нужно указать
параметр responsetype=json или HTTP-заголовка “Accept: application/json”. Если в
описании запроса ниже явно не указана возможность возврата данных в JSON,
подразумевается, что данные возвращаются только в XML.

Получение конфигурации системы

XML: [Link]
JSON: [Link]
Параметры:
login – имя пользователя.
password – MD5-хэш от пароля.
Ответ на запрос в XML -формате:
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="[Link]
ServerVersion="2.0.15"
XMLProtocolVersion="2"
Timestamp="2015-05-20T12:19:21.8562773Z" Revision="71"
SenderId="23424773-aa6e-4088-a0d3-97d50fe76c5f"
Id="36b21916-1186-4ba0-8ad6-138f963140a6"
xmlns:xsi=[Link]
xmlns:xsd="[Link]
<Servers>
<ServerInfo Id="23424773-aa6e-4088-a0d3-97d50fe76c5f"
Url="[Link]:8080"
Name="Cервер 1" />
</Servers>
 45

<Channels>
<ChannelInfo Id="9bacefb4-4605-4813-940d-41c056248f8d"
Name="Канал 1"
ArchiveStreamType="Main"
ArchiveMode="MDandManual"
IsTransmitSoundOn="false"
IsPtzOn="false"
AllowedArchive="true"
AllowedRealtime="true"
IsSoundArchivingEnabled="false"
IsArchivingEnabled="true"
IsSoundOn="false"
IsDisabled="false"
AttachedToServer="23424773-aa6e-4088-a0d3-97d50fe76c5f"
DeviceInfo="LTV ICD(M,V)(x)-xxx"
Description="">
<Streams>
<StreamInfo RotationMode="None"
StreamFormat="H264"
StreamType="Main"/>
<StreamInfo RotationMode="None"
StreamFormat="MJPEG"
StreamType="Alternative"/>
</Streams>
</ChannelInfo>
</Channels>
<RootSecurityObject Id="9c7d175a-9c84-455e-b104-57cc12cb9d47">
<ChildSecurityObjects>
<SecObjectInfo Id="583f67a8-d173-4b59-8c49-5e774c99bcf9"
Name="Объект 1">
<ChildSecurityObjects/>
<ChildChannels>
<ChannelId>9bacefb4-4605-4813-940d-41c056248f8d</ChannelId>
</ChildChannels>
</SecObjectInfo>
</ChildSecurityObjects>
<ChildChannels/>
</RootSecurityObject>
<UserGroup>
<Id>464daa9e-755d-4491-a616-5fbda4423ac8</Id>
<Name>Администраторы</Name>
<CanConfigure>true</CanConfigure>
<CanConfigureWorkplace>false</CanConfigureWorkplace>
<CanShutdown>true</CanShutdown>
<CanChangeChannelMode>true</CanChangeChannelMode>
<CanManageRec>true</CanManageRec>
<CanAccessExpertMode>true</CanAccessExpertMode>
<CanPTZ>true</CanPTZ>
<CanReceiveSound>true</CanReceiveSound>
<CanTransmitSound>true</CanTransmitSound>
<CanAccessNewCamera>true</CanAccessNewCamera>
<CanGetTranscodedVideoFromMobileServer>
true
</CanGetTranscodedVideoFromMobileServer>
<CanAccessEditingAnalystPluginsInClient>
true
</CanAccessEditingAnalystPluginsInClient>
<CanAccessVideoViaWeb>true</CanAccessVideoViaWeb>
<CanAccessVideoViaSmartTV>true</CanAccessVideoViaSmartTV>
<CanExportVideoToAvi>true</CanExportVideoToAvi>
<CanReceiveMainStream>true</CanReceiveMainStream>
<AllowedArchiveDepth/>
 46

<IsAllForbidden>false</IsAllForbidden>
<CanAccessUnifiedLog>true</CanAccessUnifiedLog>
<CanAccessToAllUsersInUnifiedLog>true</CanAccessToAllUsersInUnifiedLog>
<CanReceiveMobilePush>true</CanReceiveMobilePush>
</UserGroup>
<MobileServerInfo HighResolution="800 x 480"
MiddleResolution="240 x 180"
LowResolution="120 x 90"
FpsLimit="0"
UsePFrames="false"
Port="8089"
IsMobilePushEnabled="false"
IsProxyEnabled="true"
IsEnabled="true">
<Resolutions>
<ResolutionInfo FpsLimit="15"
UsePFrames="true"
IsEnabled="true"
Type="High"
Height="480"
Width="800"/>
<ResolutionInfo FpsLimit="4"
UsePFrames="false"
IsEnabled="true"
Type="Middle"
Height="180"
Width="240"/>
<ResolutionInfo FpsLimit="4"
UsePFrames="false"
IsEnabled="false"
Type="Low"
Height="90"
Width="120"/>
</Resolutions>
</MobileServerInfo>
<RtspServerInfo IsEnabled="true"
IsMjpegEnabled="false"
TcpPort="554"/>
</Configuration>
Ответ на запрос в JSON -формате:
{
"Id": "36b21916-1186-4ba0-8ad6-138f963140a6",
"SenderId": "23424773-aa6e-4088-a0d3-97d50fe76c5f",
"RevNum": 70,
"Timestamp": "2015-05-20T12:13:37.6889429Z",
"XmlProtocolVersion": 2,
"ServerVersion": "2.0.15",
"Servers": [
{
"Id": "23424773-aa6e-4088-a0d3-97d50fe76c5f",
"Name": "Cервер 1",
"Url": "[Link]:8080",
"ConnectionUrl": null
}
],
"Channels": [
{
"Id": "9bacefb4-4605-4813-940d-41c056248f8d",
"Name": "Канал 1",
"Description": "",
"DeviceInfo": "LTV ICD(M,V)(x)-xxx",
 47

"AttachedToServer": "23424773-aa6e-4088-a0d3-97d50fe76c5f",
"IsDisabled": false,
"IsSoundOn": false,
"IsArchivingEnabled": true,
"IsSoundArchivingEnabled": false,
"AllowedRealtime": true,
"AllowedArchive": true,
"IsPtzOn": false,
"IsTransmitSoundOn": false,
"ArchiveMode": "MDandManual",
"Streams": [
{
"StreamType": 0,
"StreamFormat": 3,
"RotationMode": 0
},
{
"StreamType": 1,
"StreamFormat": 1,
"RotationMode": 0
}
],
"ArchiveStreamType": "Main"
}
],
"RootSecObject": {
"ChildSecObjects": [
{
"ChildSecObjects": [],
"ChildChannels": [
"9bacefb4-4605-4813-940d-41c056248f8d"
],
"Id": "583f67a8-d173-4b59-8c49-5e774c99bcf9",
"Name": "Объект 1"
}
],
"ChildChannels": [],
"Id": "9c7d175a-9c84-455e-b104-57cc12cb9d47",
"Name": null
},
"UserGroup": {
"Id": "464daa9e-755d-4491-a616-5fbda4423ac8",
"Name": "Администраторы",
"CanConfigure": true,
"CanConfigureWorkplace": false,
"CanShutdown": true,
"CanChangeChannelMode": true,
"CanManageRec": true,
"CanAccessExpertMode": true,
"CanPTZ": true,
"CanReceiveSound": true,
"CanTransmitSound": true,
"CanAccessNewCamera": true,
"CanGetTranscodedVideoFromMobileServer": true,
"CanAccessEditingAnalystPluginsInClient": true,
"CanAccessVideoViaWeb": true,
"CanAccessVideoViaSmartTV": true,
"CanExportVideoToAvi": true,
"CanReceiveMainStream": true,
 48

"AllowedArchiveDepth": "416.16:00:00",
"IsAllForbidden": false,
"CanAccessUnifiedLog": true,
"CanAccessToAllUsersInUnifiedLog": true,
"CanReceiveMobilePush": true
},
"MobileServerInfo": {
"IsEnabled": true,
"IsProxyEnabled": true,
"IsMobilePushEnabled": false,
"Port": 8089,
"UsePFrames": false,
"FpsLimit": 0,
"LowResolution": "120 x 90",
"MiddleResolution": "240 x 180",
"HighResolution": "800 x 480",
"Resolutions": [
{
"Width": 800,
"Height": 480,
"IsEnabled": true,
"FpsLimit": 15,
"UsePFrames": true,
"Type": 2
},
{
"Width": 240,
"Height": 180,
"IsEnabled": true,
"FpsLimit": 4,
"UsePFrames": false,
"Type": 1
},
{
"Width": 120,
"Height": 90,
"IsEnabled": false,
"FpsLimit": 4,
"UsePFrames": false,
"Type": 0
}
]
},
"RtspServerInfo": {
"IsEnabled": true,
"TcpPort": 554,
"IsMjpegEnabled": false
}
}
В ответе в элементе Configuration содержится:
● Версия протокола XMLProtocolVersion. На данный момент номер протокола
равняется 2, его смена в будущем предполагает появления новых элементов
и атрибутов в xml-ответе.
● Временная метка последнего применения конфигурации Timestamp.
● Уникальный идентификатор Id текущей конфигурации и номер ее ревизии
Revision. Номер ревизии увеличивается на единицу после каждого изменения
конфигурации.
● Идентификатор сервера SenderId, отправившего данный xml-ответ.
 49

В элементе Servers содержится описание серверов, входящих в текущую конфигурацию.

Каждый сервер описывается элементом ServerInfo, в который входят следующие
атрибуты:
● Уникальный идентификатор сервера Id.
● Его название Name в рамках текущей конфигурации.
● Url сервера/
В элементе Channels содержится описание настроек каналов текущей конфигурации.
Настройки каждого канала описываются элементом ChannelInfo, в котором содержатся
следующие атрибуты и элементы:
● Уникальный идентификатор Id канала, который может быть использован
в запросах на получение видео при задании параметра channelid.
● Идентификатор сервера AttachedToServer, к которому прикреплен канал.
● Информация о выбранном устройстве DeviceInfo.
● Параметр IsArchivingEnabled, показывающий включено ли на канале
архивирование видеоданных.
● Параметр IsSoundArchivingEnabled, показывающий включено ли архивирование
звуковых данных.
● Параметр ArchiveMode, показывающий режим записи в архив на канале
(если она включена). Возможные значения: AlwaysOn — всегда включена;
OnlyManual — только ручное управление, BySchedule — запись по расписанию;
MDandManual — автоматическое включение по детектору движения и ручное.
● Параметр IsSoundOn, показывающий включено ли получение звука на данном
канале. Если данный параметр равен false, то параметр IsSoundArchivingEnabled
может быть проигнорирован.
● Параметр AllowedRealtime, показывающий разрешено ли текущему пользователю
просматривать видео в реальном времени на данном канале.
● Параметр AllowedArchive, показывающий разрешено ли текущему пользователю
просматривать видео из архива на данном канале.
● Параметр IsDisabled, показывающий отключен ли канал в текущей конфигурации.
● Параметр Name, содержащий имя канала в конфигурации.
● Элемент Streams, содержащий настройки основного и альтернативного потоков
видеоданных. В описании потока StreamInfo содержится один из трех возможных
форматов потоков (H264, MPEG4, MJPEG) в поле StreamFormat;
а также тип потока, принимающий значение main (основной) или alternative
(альтернативный). Если альтернативный поток не включен на данном канале,
то его описание будет отсутствовать.
В элементе RootSecurityObject содержится информация о структуре дерева объектов
безопасности и принадлежности к ним каналов.
В элементе UserGroup содержится информация о правах группы, к которой принадлежит
пользователь, который запрашивает конфигурацию.
В элементе MobileServerInfo содержится информация о параметрах перекодирования
видео мобильным сервером.

Получение профилей (предустановленные сетки)

Примеры запроса:
XML: [Link]
JSON:
[Link]
 50

Пример ответа в JSON-формате в JSON:

[
{
"Id": "13851f3d-c7d3-4ec6-b0ff-2d66873bf118",
"Name": "Новый профиль 1"
}
]

Получение списка доступных сеток на клиенте Macroscop

XML:
[Link]
&password=
JSON:
[Link]
&password=&responsetype=json
В результате выполнения запроса возвращается список доступных сеток на конкретном
клиенте. Пример:
[
"1",
"4",
"6_1",
"7",
"8_1",
"9",
"10",
"13",
"16",
"25"
]
Первая цифра (до знака “_”) означает число ячеек в сетке, вторая (после “_”) — номер
конфигурации. Номер конфигурации введен только для сеток, обладающих одинаковым
числом ячеек, но отличающихся размером и расположением ячеек.

Получение информации о текущей сетке в клиенте Macroscop

XML: [Link]
&monitor=0
JSON: [Link]
&clientip=[Link]&monitor=0&responsetype=json
Параметры:
clientip — IP-адрес или URI клиента.
monitor — номер монитора на клиенте (начинается с 0).
В результате выполнения запроса возвращается тип текущей сетки и ее содержимое.
Пример:
{
"GridType": "4",
"Cells":
[
{
"Index": 0,
"IsEmpty": false,
"ChannelId": "483cd419-c03c-47b1-a3bb-ef5bce82d588",
"Viewer": "Realtime"
},
 51

{
"Index": 1,
"IsEmpty": false,
"ChannelId": "fe5e37d5-6da8-403c-ace8-10c4ba4c4b64",
"Viewer": "Realtime"
},
{
"Index": 2,
"IsEmpty": false,
"ChannelId": "edc2f629-4565-49a1-8c70-663e16ab0104",
"Viewer": "Realtime"
},
{
"Index": 3,
"IsEmpty": false,
"ChannelId": "1b6204af-f3ae-49ab-935f-878cbb3a9139",
"Viewer": "Realtime"
}
]
}
Где:
index — порядковый номер ячейки (отсчет с нуля);
isempty — пуста ли ячейка;
channeled – идентификатор канала;
viewer — тип содержимого в ячейке, принимает значения:
● none — ячейка пуста;
● realtime — реальное время;
● archive — архив;
● other — другое, на данный момент может быть только план помещения.
Тип сетки совпадает с описанным в разделе Получение списка доступных сеток на
клиенте Macroscop.

Получение времени компьютера, на котором работает сервер

Macroscop
XML: [Link]
JSON:
[Link]
В результате выполнения запроса приходит время в UTC. Пример:
"22.09.2014 3:33:06"

Получение информации о наличии архива в указанный момент

времени
XML: [Link]
&channelid=d96e8b67-3f13-44fd-b628-356d1f88a50c&searchTime=23.09.2014+06:10:00
JSON: [Link]
&channelid=d96e8b67-3f13-44fd-b628-356d1f88a50c&searchTime=23.09.2014+06:10:00
&responsetype=json
Время в параметре searchTime должно передаваться в UTC.
В результате выполнения запроса возвращается флаг наличия архива за указанное
время и временная метка ближайшего видеокадра. Пример:
{
"HasArchive": false,
"NearestFrameTimestamp": null
}
 52

Получение списка интервалов с информацией о начале и

окончании записи архива.
JSON: [Link]
f361-44b9-bbec-1e54eae777c0&fromtime=02.06.2022 08:47:05&totime=02.06.2022
08:49:05&responsetype=json
Возвращает массив, элементы которого содержат время начала и окончания записи
архива, например, когда запись велась по детектору движения.
Параметры:
● login – имя пользователя;
● password – MD5-хэш от пароля;
● channelid – идентификатор камеры;
● fromtime – время начала в UTC, в формате [Link] hh:mm:ss;
● totime – время начала в UTC, в формате [Link] hh:mm:ss.

Скачивание фрагмента видео из архива в формате mp4

MP4:
[Link]
bbec-1e54eae777c0&fromtime=02.06.2022 08:47:05&totime=02.06.2022 08:49:05
Функция поддерживается только для камер, архив которых записывается в кодеках H264,
H265 (HEVC), MjPEG.

Обязательные параметры:
• login – имя пользователя;
• password – MD5-хэш от пароля;
• channelid – идентификатор камеры;
• fromtime – время начала фрагмента в UTC, в формате [Link] hh:mm:ss;
• totime – время окончания фрагмента в UTC, в формате [Link] hh:mm:ss.

Опциональные параметры:
• usetimestamps (true|false) – позволяет накладывать поверх видео временную метку
с временем когда был записан текущий кадр;
• sound (on|off) – позволяет экспортировать звук (поддерживается только на
Windows-серверах);
• fromDevice (true|false) – позволяет экспортировать архив, хранящийся на камере
или регистраторе, если они поддерживают функцию доступа к архиву;
• addhvc1tagforhevc (true|false) (с версии 3.6 и выше) – позволяет воспроизводить
экспортируемый mp4 ролик на Apple-устройствах (нужен только для экспорта H.265,
увеличивает немного время экспорта).

Получение информации о состоянии каналов.

XML: [Link]
JSON: [Link]
&responsetype=json
 53

Пример ответа в JSON-формате:

[
{
"Id": "596ea82f-cf03-4e1f-9658-5aafbb1cb143",
"IsRecordingOn": false,
"StreamsStates":
[
{
"Type": "MainVideo",
"State": "Active"
},
{
"Type": "AlternativeVideo",
"State": "Stopped"
},
{
"Type": "MainSound",
"State": "Active"
},
{
"Type": "AlternativeSound",
"State": "Stopped"
},
{
"Type": "OutputSound",
"State": "Stopped"
},
{
"Type": "MotionDetection",
"State": "Stopped"
},
{
"Type": "IO",
"State": "Stopped"
},
{
"Type": "ArchiveVideo",
"State": "Stopped"
},
{
"Type": "ArchiveSound",
"State": "Stopped"
}
]
}
]
Где:
Id — идентификатор канала;
IsRecordingOn — включена ли запись на канале;
StreamStates — состояние потоков получения данных. У каждого потока есть тип Type
и состояние State.
 54

Type принимает значения:

● MainVideo — видео, основной поток, высокое разрешение;
● AlternativeVideo — видео, второй поток, среднее разрешение;
● MainSound — прием звука, основной поток;
● AlternativeSound — прием звука, альтернативный поток;
● OutputSound — передача звука;
● MotionDetection — встроенный детектор движения;
● IO — цифровые входы/выходы;
● ArchiveVideo — архивное видео;
● ArchiveSound — архивный звук.
State принимает значения:
● Stopped — поток остановлен, т.к. он не требуется системе;
● Active — поток находится в состоянии получения кадров и событий;
● NoConnection — в потоке произошел обрыв соединения с устройством.

Получение PTZ-возможностей устройства

XML: [Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
JSON: [Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
&responsetype=json
Пример ответа в JSON-формате:
{
"PtzCapabilities":
{
"HomePositionSupports": true,
"MoveToSupports": false,
"AreaZoomSupports": false,
"ZoomSupports": true,
"ContiniousZoomSupports": true,
"AutoFocusSupports": true,
"ManualFocusSupports": true,
"ContiniousFocusSupports": true,
"SupportedStepMoveDirections": 0,
"SupportedContiniousMoveDirections": 255
},
"Resolution":
{
"Width": 1920,
"Height": 1080
}
}
Где:
HomePositionSupports — поддерживается ли домашнее положение;
MoveToSupports — поддерживается ли центрирование (камера поворачивается
к заданной точке);
AreaZoomSupports — поддерживается ли функция приближения выделенной области;
ZoomSupports — поддерживаются ли «шаговый» зум (при отправке одной команды
однократное изменение зума);
ContiniousZoomSupports — поддерживается ли «непрерывный» зум (при отправке
команды зум идет до тех пор, пока не придет команда на остановку);
AutoFocusSupports — поддерживается ли функция автофокусировки;
ManualFocusSupports — возможность ручного управления фокусом;
 55

ContiniousFocusSupports — поддерживается ли «следящий» фокус;

SupportedStepMoveDirections — маска, описывающая доступные направления
для «шагового перемещения»;
SupportedContiniousMoveDirections — маска, описывающая доступные направления
для «непрерывного» движения;
Resolution — текущее разрешение кадра на основном потоке (необходимо для команд
moveto и areazoom, см. ниже).

Получение пресетов с PTZ-устройства

XML: [Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
JSON: [Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
&responsetype=json
Пример ответа в JSON-формате:
[
"Предуст. 1",
"Предуст. 2",
"Предуст. 3",
"Предуст. 4",
"Предуст. 8"
]

HTTP-интерфейс для получения событий

Помимо получения информации о текущей конфигурации системы, HTTP-интерфейс
позволяет также получать информацию об обнаруженных и созданных системой
событиях.

Получение списка всех зарегистрированных в системе

событий
Реализовано в Macroscop версии 2.1 и более поздних.
Для фильтрации информации при исполнении запросов на получение событий можно
использовать идентификаторы типов событий. Идентификаторы статичны и неизменны
для всех серверов.

Чтобы получить список существующих в системе типов событий, необходимо выполнить

команду следующего формата:
[Link]
sword>[&responsetype=json]
Где:
адрес — IP адрес или доменное имя сервера. Обязательный параметр;
порт — HTTP или HTTPS порт сервера. Обязательный параметр;
login — имя пользователя. Обязательный параметр;
password — MD5-хэш пароля пользователя. Обязательный параметр;
responsetype=json — Указание выводить результат в формате JSON вместо XML.
Опциональный параметр.
Если для пользователя не задан пароль, параметр password можно оставить
пустым или исключить из запроса.
 56

Пример запроса и ответа в формате XML:

[Link]
<EventInfo>
<Id>00000000-0000-0000-0000-000000000033</Id>
<GuiName>Движение</GuiName>
<AvailabilityModes>
<HttpEventAvailabilityMode>RealTime</HttpEventAvailabilityMode>
</AvailabilityModes>
</EventInfo>

Пример запроса и ответа в формате JSON:

[Link]
setype=json
{
"Id": "00000000-0000-0000-0000-000000000033",
"GuiName": "Движение",
"AvailabilityModes": [
"RealTime"
]
}

Некоторые типы событий доступны для получения только в режиме реального времени, в
связи с чем их нельзя получить при запросе за прошедшее время. Определить, какие
методы получения доступны для выбранного типа события позволяет параметр
AvailabilityModes.
Параметр может иметь следующие значения:
RealTime — события этого типа доступны для получения в режиме реального времени;
SpecialArchive — события этого типа доступны для получения из архива.

Пример события, доступного для получения как в реальном времени, так и из архива:
<EventInfo>
<Id>427f1cc3-2c2f-4f50-8865-56ae99c3610d</Id>
<GuiName>Обнаружено лицо (Модуль распознавания лиц)</GuiName>
<AvailabilityModes>
<HttpEventAvailabilityMode>RealTime</HttpEventAvailabilityMode>
<HttpEventAvailabilityMode>SpecialArchive</HttpEventAvailabilityMode>
</AvailabilityModes>
</EventInfo>

Получение событий в реальном времени

Реализовано в Macroscop версии 2.1 и более поздних.

Получение событий в режиме реального времени доступно в виде непрерывного
("бесконечного") HTTP-соединения.
При чтении полученного ответа необходимо учитывать, что информация
передаётся с использованием следующих механизмов:
Chunked transfer encoding для передачи динамически формируемого тела
ответа. Ввиду "бесконечности" запроса невозможно предугадать точный размер
тела ответа, в связи с чем ответ передаётся с заголовком "Transfer-encoded:
chunked".
 57

Newline delimited JSON streaming для разделения передаваемых объектов.

Разделение объектов в этом механизме осуществляется переводом следующего
объекта на новую строку вместо использования символьных разделителей.

Чтобы получить поток событий в режиме реального времени, необходимо выполнить

команду следующего формата:
[Link]
nelid=<channelid>][&responsetype=json]
Где:
адрес — IP адрес или доменное имя сервера. Обязательный параметр;
порт — HTTP или HTTPS порт сервера. Обязательный параметр;
login — имя пользователя. Обязательный параметр;
password — MD5-хэш пароля пользователя. Обязательный параметр;
filter — GUID типа события. Опциональный параметр;
channelid — GUID канала. Опциональный параметр;
responsetype=json — Указание выводить результат в формате JSON вместо XML.
Опциональный параметр.
Если для пользователя не задан пароль, параметр password можно оставить
пустым или исключить из запроса.

Пример запроса и ответа в формате JSON:

[Link]
{
"EventId" : "eb0bb455-b85f-4ac4-851f-f30a11797579",
"Timestamp" : "19.10.2022 09:58:55",
"BinaryTimestamp" : "5249703721781162729",
"ZonedTimestamp" : "19.10.2022 09:58:55.377 +05:00",
"EventDescription" : "Начало движения",
"IsAlarmEvent" : "False",
"ChannelId" : "e0391a80-c921-4ffc-9a69-107fcf28e34e",
"ChannelName" : "Камера 3",
"Comment" : "",
"EventType" : "Info",
"InitiatorName" : "System"
}
{
"EventId" : "e4b1f78d-35d6-4092-9fd8-72e66de82e01",
"Timestamp" : "19.10.2022 09:59:11",
"BinaryTimestamp" : "5249703721937844932",
"ZonedTimestamp" : "19.10.2022 09:59:11.045 +05:00",
"EventDescription" : "Окончание движения",
"IsAlarmEvent" : "False",
"ChannelId" : "e0391a80-c921-4ffc-9a69-107fcf28e34e",
"ChannelName" : "Камера 3",
"Comment" : "",
"EventType" : "Info",
"InitiatorName" : "System"
}

Параметры запроса filter и channelid применяются в случаях, когда необходимо

получить события только определённого типа и/или с определённого канала. Оба
параметра могут быть использованы в одном запросе одновременно, но каждый
параметр при этом может иметь только одно значение.

Пример корректного запроса:

 58

[Link]
107fcf28e34e&filter=00000000-0000-0000-0000-000000000033&responsetype=json

Пример некорректного запроса:

[Link]
107fcf28e34e&filter=00000000-0000-0000-0000-000000000033,e4b1f78d-35d6-4092-9fd8-
72e66de82e01&responsetype=json

При добавлении к запросу параметра mode=demo система начнёт генерировать

виртуальные события с типом события "Обнаружен автономер". Такие события не
сохраняются в журнал событий системы, не ассоциируются с какой-либо камерой и не
несут какой-либо действительной информации. Этот параметр может быть полезен для
изучения, тестирования и отладки механизмов получения и чтения событий.

Пример запроса и ответа виртуального события:

[Link]
{
"EventId" : "c9d6d086-c965-4cf8-aef6-85b3894e3a4a",
"Timestamp" : "19.10.2022 10:24:02",
"BinaryTimestamp" : "5249703736847974593",
"ZonedTimestamp" : "19.10.2022 10:24:02.058 +05:00",
"EventDescription" : "Обнаружен автономер",
"IsAlarmEvent" : "False",
"ChannelId" : "00000000-0000-0000-0000-000000000000",
"ChannelName" : "",
"Comment" : "",
"EventType" : "Info",
"InitiatorName" : "System",
"IsIdentified" : "False",
"plateText" : "",
"Speed" : "0",
"Reliability" : "0",
"Left" : "0",
"Top" : "0",
"lastName" : "",
"firstName" : "",
"patronymic" : "",
"carbrand" : "",
"carcolor" : "",
"additionalInfo" : "",
"groups" : "",
"direction" : ["Unknown"],
"ExternalId" : "",
"ExternalOwnerId" : "",
"Width" : "0",
"Height" : "0",
"Numberplate" : ""
}

В случае полного или временного отсутствия событий, соответствующих отправленному

запросу, система будет возвращать в ответ KeepAlive сообщения для сохранения
установленного соединения активным. Сообщение такого типа будет отображаться в
потоке даже если в запросе был задан фильтр по типу события.

Пример KeepAlive сообщения:

{
"EventId" : "e9e7a69c-7ee2-3fee-a530-9f8a88124fcc",
"Timestamp" : "19.10.2022 09:59:19",
 59

"BinaryTimestamp" : "5249703722021050198",
"ZonedTimestamp" : "19.10.2022 09:59:19.366 +05:00",
"EventDescription" : "",
"IsAlarmEvent" : "False",
"ChannelId" : "00000000-0000-0000-0000-000000000000",
"ChannelName" : "",
"Comment" : "KeepAlive",
"EventType" : "Info",
"InitiatorName" : "System"
}

В результате работы некоторых модулей аналитики системой регистрируются

координаты обнаруженного на кадре объекта (например, координаты лица для
Распознавания лиц). При запросе событий такого типа, в теле ответа передаются
относительные координаты рамки объекта в виде позиции на кадре левой верхней
точки рамки (Top, Left), а также её ширины и высоты (Width, Height).
Отсчёт координат осуществляется от левого верхнего угла кадра.

Пример ответа с координатами объекта:

{
"EventId" : "427f1cc3-2c2f-4f50-8865-56ae99c3610d",
"Timestamp" : "21.04.2021 04:33:19.555",
"BinaryTimestamp" : "5249231782422939709",
"ZonedTimestamp" : "21.04.2021 04:33:19.555 +05:00",
"EventDescription" : "Обнаружено лицо (Модуль распознавания лиц)",
"IsAlarmEvent" : "False",
"ChannelId" : "cb07636a-ec9f-4555-a1eb-7b3485e1285e",
"ChannelName" : "Камера 1",
"Comment" : "",
"IsIdentified" : "False",
"lastName" : "",
"firstName" : "",
"patronymic" : "",
"groups" : "",
"additionalInfo" : "",
"Left" : "0,0277343735098839",
"Top" : "0,0372685134410858",
"Width" : "0,25234375",
"Height" : "0,448611122369766",
"Similarity" : "0",
"Age" : "27",
"Gender" : "2",
"ExternalId" : "",
"TemperatureDegreesCelsius" : "0",
"ImageBytes" : "",
"Emotion" : ["Neutral"],
"EmotionConfidence" : "0,729602694511414",
"TrajectoryId" : "9351b23f-813f-42a4-b1ba-011dbbcce99b"
}

Для сортировки по времени возникновения события каждый объект имеет временную

метку, представленную в теле ответа в трёх форматах:
Timestamp - дата и время сервера в формате UTC без учёта часового пояса сервера;
ZonedTimestamp - дата и время сервера в формате UTC с указанием часового пояса
сервера;
BinaryTimestamp - дата и время сервера в бинарном представлении (метод
[Link]).
 60

Бинарное представление временной метки имеет наибольшие точность и удобство

интеграции, но осложняет задачу чтения временной метки человеком. Для
преобразования бинарного представления даты и времени в формат UTC используйте
метод [Link].

Получение списка специальных архивных событий

Реализовано в Macroscop версии 2.1 и более поздних.

Получение событий из архива доступно в виде списка зафиксированных системой за
заданное время событий. Максимальное количество событий на один запрос - 1000.
Для получения последующих событий необходимо начинать поиск с времени
последнего полученного события.
При чтении полученного ответа необходимо учитывать, что информация
передаётся с использованием механизма Newline delimited JSON streaming.
Разделение объектов в этом механизме осуществляется переводом следующего
объекта на новую строку вместо использования символьных разделителей.

Чтобы получить список событий из архива, необходимо выполнить команду следующего

формата:
[Link]
e=<starttime>&endtime=<endtime>&eventid=<eventid>[&channelid=<channelid>][&responsety
pe=json]
Где:
адрес — IP адрес или доменное имя сервера. Обязательный параметр;
порт — HTTP или HTTPS порт сервера. Обязательный параметр;
login — имя пользователя. Обязательный параметр;
password — MD5-хэш пароля пользователя. Обязательный параметр;
starttime — дата и время начала интервала поиска событий. Указывается по часовому
поясу UTC в формате ДД-ММ-ГГГГ+чч:мм:сс. Обязательный параметр;
endtime — дата и время конца интервала поиска событий. Указывается по часовому
поясу UTC в формате ДД-ММ-ГГГГ+чч:мм:сс. Обязательный параметр;
eventid — GUID типа события. Обязательный параметр;
channelid — GUID канала. Опциональный параметр;
responsetype=json — указание выводить результат в формате JSON вместо XML.
Опциональный параметр.
Если для пользователя не задан пароль, параметр password можно оставить
пустым или исключить из запроса.
 61

Пример запроса и ответа в формате JSON:

[Link]
10:50:00&endtime=19.10.2022+11:00:00&eventid=b0536c2f-2f09-4969-bf1a-
9fb847b87d21&responsetype=json
{
"EventId" : "b0536c2f-2f09-4969-bf1a-9fb847b87d21",
"Timestamp" : "19.10.2022 10:59:56",
"BinaryTimestamp" : "5249703758396001539",
"ZonedTimestamp" : "19.10.2022 10:59:56.861 +05:00",
"EventDescription" : "Событие трекинга",
"IsAlarmEvent" : "True",
"ChannelId" : "e0391a80-c921-4ffc-9a69-107fcf28e34e",
"ChannelName" : "Камера 3",
"Comment" : "Движение в зоне",
"EventType" : "Alarm",
"InitiatorName" : "ExternalEvent",
"alertType" : ["MovingInZone"],
"AlertTime" : "638017739968613635",
"TrajectoryId" : "57f88149-9976-4953-9b4c-3921c689b82d",
"Left" : "0,0032153846710991974",
"Top" : "0,5185692308091415",
"Width" : "0,05787692314846298",
"Height" : "0,13713846175798144"
}

Получение из архива распознанных автомобильных номеров

Для модуля Распознавания автомобильных номеров существует дополнительный тип
запроса, позволяющий получить список распознанных за указанный период времени
номеров в более коротком формате, чем с помощью команды event.

Чтобы получить список распознанных за указанный временной интервал автомобильных

номеров, необходимо выполнить команду следующего формата:
[Link]
tTime=<starttime>&finishTime=<finishtime>
Где:
адрес — IP адрес или доменное имя сервера. Обязательный параметр;
порт — http или https порт сервера. Обязательный параметр;
login — имя пользователя. Обязательный параметр;
password — MD5-хэш пароля пользователя. Обязательный параметр;
starttime — время начала интервала поиска событий. Указывается по часовому поясу
сервера в формате ГГГГ-ММ-ДД-чч-мм-сс-мс. Обязательный параметр;
finishtime — время конца интервала поиска событий. Указывается по часовому поясу
сервера в формате ГГГГ-ММ-ДД-чч-мм-сс-мс. Обязательный параметр;
channelid — GUID канала. Обязательный параметр.

Если для пользователя не задан пароль, параметр password можно оставить

пустым или исключить из запроса.
Ответ от сервера при выполнении этой команды всегда будет в формате JSON.
 62

Пример запроса и ответа:

[Link]
4128-a48e-37dd184b109b&startTime=2022-10-20-16-40-00-000&finishTime=2022-10-20-17-00-
00-000
[
{
"TimeUtc" : "20.10.2022 11:48:11.707",
"Numberplate" : "Х532МН159",
"LastName" : "",
"FirstName" : "",
"PatronymicName" : "",
"Group" : "",
"Direction" : "Unknown"
}
,

{
"TimeUtc" : "20.10.2022 11:48:35.097",
"Numberplate" : "С112НР72",
"LastName" : "",
"FirstName" : "",
"PatronymicName" : "",
"Group" : "",
"Direction" : "Unknown"
}
]

При отправке запроса и чтении ответа необходимо учитывать особенность

отображения времени.
В теле запроса временной интервал указывается по часовому поясу сервера в
формате ГГГГ-ММ-ДД-чч-мм-сс-мс.
В теле ответа время распознавания автомобильного номера указывается по
часовому поясу UTC(+0) в формате ДД-ММ-ГГГГ чч-мм-сс.
Таким образом, если запрос отправляется на сервер с часовым поясом UTC+3 с
целью получить список распознанных номеров за интервал 15:00:00 -
15:10:00, время в теле запроса указывается согласно требуемому интервалу,
тогда как в теле ответа соответствующие запросу номера будут иметь время из
интервала 12:00:00 - 12:10:00.
 63

HTTP-интерфейс для отправки команд на сервер

Macroscop
Для отправки команд на сервер Macroscop используются CGI-запросы, описанные ниже.

Включение/выключение записи на канале

Для включения записи с обязательным указанием времени записи в минутах нужно
выполнить запрос:
[Link]
&channelid=34512d50-c87e-4c75-a5a5-9b3a5aaa7d13&Interval=20&login=root&password=
Где:
channelid — GUID канала;
interval — время записи в минутах;
mode — режим, принимает значения start и stop.
Для выключения записи необходимо послать запрос:
[Link]
a5a5-9b3a5aaa7d13&login=root&password=

Синхронизация времени с другим компьютером в сети

Данный запрос установит время на сервере Macroscop согласно времени в параметре
time.
[Link]
&password=

Получение профилей (предустановленные сетки)

[Link]
Пример ответа в JSON-формате:
[
{
"Id": "13851f3d-c7d3-4ec6-b0ff-2d66873bf118",
"Name": "Новый профиль 1"
}
]

Установка профиля на клиенте

[Link]
&profileid=13851f3d-c7d3-4ec6-b0ff-2d66873bf118&login=root&password=
Где:
clientip — IP-адрес компьютера с установленным Macroscop клиентом;
monitor — номер монитора (отсчет от нуля);
pofileid — идентификатор профиля, который может быть получен из ответа на запрос
получения профилей.

Смена сетки на клиенте

[Link]
&login=root&password=
Устанавливает требуемую сетку, передаваемую в параметре cells. Сетка должна быть
разрешена для использования на указанном клиенте.

Очистка сетки
[Link]
&password=
 64

Закрывает все каналы, открытые в ячейках текущей сетки

Установка канала в ячейку сетки

[Link]
&mode=archive&cell=0&channelid=34512d50-c87e-4c75-a5a5-9b3a5aaa7d13
&login=root&password=
Где:
mode – принимает значения realtime (для просмотра реального времени) или archive
(для доступа в архив);
cell – номер ячейки, в которую необходимо поместить канал (отсчет от 0).
В зависимости от параметра mode открывает либо канал реального времени,
либо архивный канал в указанной ячейке. Опционально возможно указать время
startTime, начиная с которого должно начинаться воспроизведение архива и скорость
проигрывания с помощью параметра speed (доступные скорости для воспроизведения:
0,1; 0,2; 0,5; 1; 2; 5; 10; 20; 60; 120).

Удаление канала из ячейки сетки

[Link]
&login=root&password=
Где cell – номер ячейки в сетке

Команда PTZ для «непрерывного» движения

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где:
panspeed — скорость по горизонтали от -100 до 100;
tiltspeed — скорость по вертикали от -100 до 100;
stoptimeout - время в миллисекундах, через которое команда будет остановлена, если
значение не задано, будет выбрано 500 мс.

Команда PTZ для «непрерывного» изменения фокуса

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где:
speed — скорость фокусировки от -100 до 100;
stoptimeout - время в миллисекундах, через которое команда будет остановлена, если
значение не задано, будет выбрано 500 мс.

Команда PTZ для «непрерывного» зума

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где:
speed — скорость -100 до 100;
stoptimeout - время в миллисекундах, через которое команда будет остановлена, если
значение не задано, будет выбрано 500 мс.

Команда PTZ остановки для «непрерывных» команд

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
 65

Команда PTZ установки пресета

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где index — порядковый номер пресета, отсчет с единицы.

Команда PTZ автофокусировки

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=

Команда PTZ для выполнения центрирования

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где x и y — координаты на кадре размером width и height.

Команда PTZ для «шагового» движения

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где:
tiltstep — шаг по вертикали от -100 до 100;
panstep — шаг по горизонтали от -100 до 100.

Команда PTZ для «шагового» зума

[Link]
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где zoomstep — шаг от -100 до 100.

Команда PTZ приближения выделенной области (AreaZoom)

[Link]
&frameWidth=1920&frameHeight=1080
&channelid=20d9884f-ae8c-45d3-ac5a-505ec258f01b&login=root&password=
Где x, y, width, height – задают в кадре прямоугольник, который будет увеличен;
frameWidth — ширина кадра;
frameHeight — высота кадра.

Постановка канала на охрану

Реализовано в Macroscop версии 2.1 и более поздних.

[Link]
time&login=root&password=&channelid=f67b3044-2fe2-451f-885a-
7d570f8d2e01&isguardianmodeenabled=false
Параметры:
clientip — IP-адрес клиентского компьютера, для которого выполняется команда;
monitor — номер монитора клиентского компьютера;
isguardianmodenabled — true – включение / false – выключение охраны.
 66

Отправка звука на камеру

Реализовано в Macroscop версии 2.1 и более поздних.

Для отправки звука на камеру используется POST-запрос. В заголовке указываются
параметры запроса, в теле запроса передаются аудиоданные.
Заголовок:
[Link]
4d71-8ed1-e7beadf0dc46&clientid=66abc0c4-d4b7-4d71-8ed1-e7beadf0dc46
Параметры:
clientid — GUID сеанса передачи.
Для тела запроса ContentType = "multipart/form-data;"
Описание:
Запрос предназначен для использования в сторонних приложениях — эти приложения
называются клиентами.
В рамках одного запроса передается одна порция аудиоданных; т.е. запрос не является
постоянным подключением и сервер передает порцию звука на камеру только после того,
как завершит прием соответствующего запроса от клиента.
Для формирования порции аудиоданных (кодирования звука) следует использовать
сторонние библиотеки (например, NAudio: [Link] параметры
кодирования — Samplesrate = 8000; Bitspersample = 16; Количетсво каналов = 1).
Сеансом передачи считается серия запросов с определенного клиентского компьютера
на определённую камеру. Для каждого сеанса передачи должен использоваться
уникальный clientID. Для снижения серверных издержек рекомендуется для серии
запросов в рамках одного сеанса использовать один и тот же clientID. Клиент
самостоятельно формирует clientid.

Генерация события из внешней системы

Реализовано в Macroscop версии 2.1 и более поздних.

Данный запрос генерирует системное событие Событие из внешней системы. Пример:
[Link]
&channelid=af820905-3641-4448-a73a-eb5e91da73db
&systemname=TestSystem&information=record
Параметры:
systemname — название внешней системы;
information — строка с информацией о событии;
eventcode — код события (опционально).
В запросе обязательно должно быть указано либо название системы (systemname), либо
информация о событии (information).
В Журнале событий приложения Macroscop Клиент данное событие будет выглядеть
следующим образом:
 67

Также на эти события можно назначать действия в сценариях (посредством приложения

Macroscop Конфигуратор):

RTSP-интерфейс для получения видео и звука

RTSP-интерфейс используется для получения видео и звука клиентами, работающими по
протоколу RTSP. Данный интерфейс поддерживает кодек H.264 и, опционально, MJPEG
(MJPEG по умолчанию выключен).
Перед началом использования следует удостовериться, что RTSP-интерфейс включен.
Для этого нужно запустить Macroscop Конфигуратор и на странице серверных
настроек в разделе Сеть убедиться, что установлен флажок Принимать подключения
по протоколу RTSP (для вещания H.264
и MJPEG). В том же блоке настроек указан порт для RTSP подключений.
 68

Для подключения по протоколу RTSP можно использовать TCP-подключения (RTSP over

TCP) или HTTP-подключения (RTSP over HTTP). UDP-подключения (RTSP over UDP)
не поддерживаются.
По умолчанию вещание формата MJPEG по протоколу RTSP отключено, поскольку
протокол RTSP поддерживает только MJPEG-кадры, закодированные в базовом
(Baseline) режиме кодирования. Таким образом, для передачи видеопотоков,
закодированных в других режимах MJPEG, потребуется перекодирование; что, в
свою очередь повысит нагрузку на сервер. Кроме того, при перекодировании
MJPEG может быть понижена частота кадров
(по сравнению с частотой кадров, передаваемой непосредственно камерой).
Подключение к серверу осуществляется RTSP-клиентом, например VLC, с помощью
строки подключения следующего вида:
rtsp://<ip адрес сервера macroscop и порт rtsp>/rtsp?channelid=<id канала>
&login=<имя пользователя>&password=<хэш-строка MD5 пароля>[&sound=on]
[&streamtype=alternative]
Обязательный параметр channelid задает идентификатор канала, по которому
необходимо получать видео.

Также для задания канала можно использовать порядковый номер канала

(начинается с нуля) в конфигурации — для этого вместо параметра channelid
следует использовать параметр channelnum (см. Получение видео реального
времени и архива). Данный параметр не рекомендуется использовать, подходит
для тестирования.

Обязательный параметр login задает имя пользователя. У пользователя должны быть

права на запрашиваемый канал.
Параметр password является обязательным, если у пользователя установлен пароль.
Если у пользователя нет пароля (пустой пароль), то параметр password является
опциональным и может быть опущен, либо оставлен с пустым значением.
Опциональный параметр sound со значением on позволяет вместе с видео получать
звук. Звуковые кадры всегда приходят в формате G.711U.
Опциональный параметр streamtype со значением alternative позволяет запрашивать
альтернативный (2-й) поток видео, который, как правило, имеет меньшее разрешение.
 69

Пример запроса:
rtsp://[Link]:554/rtsp?channelid=D3039B22-3350-47C6-85FE-40F29B1C7FBD&login=root
Для доступа в архив требуется задать параметры, аналогичные параметрам
при подключении по HTTP (см. Получение видео реального времени и архива).
rtsp://<ip адрес сервера macroscop и порт rtsp>/rtsp?channelid=<id канала>
&login=<имя пользователя>&password=<хэш-строка MD5 пароля>&mode=archive
&starttime= <[Link]+ hh:mm:ss[.fff]>[&sound=on][&speed=<n>][&isforward=false]
Параметры channelid, login, password и sound аналогичны параметрам запроса
для получения видео реального времени по протоколу RTSP.
Обязательный параметр mode со значением archive указывает на доступ в архив.
Обязательный параметр starttime указывает время записи, с которого начинается
воспроизведение архива. Это значение задается в виде комбинации даты и UTC-времени.
Опциональный параметр speed задает скорость воспроизведения архива.
Диапазон принимаемых значений является непрерывным и изменяется от 0.1 до 20.
Значение по умолчанию — 1.0.
Опциональный параметр isforward со значением false указывает, что воспроизводить
архив следует назад.
Пример запроса:
rtsp://[Link]:554/rtsp?channelid=D3039B22-3350-47C6-85FE-40F29B1C7FBD
&login=root&mode=archive&starttime=21.04.2015+ 12:05:01.125&sound=on&speed=1
70
 71

Macroscop API с интерфейсом XML

XML интерфейс позволяет посылать на сервер Macroscop запросы в формате XML
и получать в ответ данные в том же формате. Структура запроса должна быть
следующей:
<?xml version="1.0" encoding="utf-8" ?>
<query>
<server_login>root</server_login>
<server_pass_hash></server_pass_hash>
<query_name>get_people_counters</query_name>
<query_params>
…
</query_params>
</query>
Ниже описано назначение параметров:
Параметр Описание
server_login Имя пользователя, под которым будет выполняться команда
server_pass_hash MD5 хэш пароля пользователя
query_name Строковое наименование типа запроса
query_params Внутри данного тэга будут помещаться параметры, специфичные
для типа запроса, указанного в параметре query_name
В ответ сервер возвращает ответ вида:
<?xml version="1.0" encoding="utf-8" ?>
<result>
<query_name></query_name>
<query_result>Ok</query_result>
<query_msg>Запрос выполнен успешно.</query_msg>
<query_time>20.09.2012 10:58:15</query_time>
<query_time_local>20.09.2012 16:58:15</query_time_local>
</result>
Ниже описано назначение параметров:
Параметр Описание
query_name Строковое наименование типа запроса
query_result Ok — если запрос выполнен успешно
Error — если произошли какие-либо ошибки
query_msg Строковый комментарий по результатам выполнения запроса
query_time Время запроса UTC
query_time_local Время запроса локальное
В ответе также могут быть тэги, специфичные для конкретного типа запроса.

Получение данных счётчика посетителей

Для получения данных счётчика посетителей используется запрос
get_people_counters.
Параметрами данного запроса являются:
<channel_id>cacdd8e6-1c56-435c-86e3-6967d7494a50</channel_id>
<search_time>2012-09-17 09:50:00</search_time>
Параметр Описание
channel_id Идентификатор канала, на котором настроен счётчик посетителей
search_time Момент времени, для которого необходимо выдать показания
счётчика. Время указывается в формате yyyy-MM-dd HH:mm:ss.
При этом указывается локальное время сервера, на который
отправляется запрос
 72

В ответ сервер возвращает следующие параметры:

<in>434</in>
<out>378</out>
Параметр Описание
in Количество вошедших людей для данного счётчика
out Количество вышедших людей для данного счётчика
73
 74

Организация вещания видео на сайт

Вещание видео на сайт может быть организовано с помощью службы мобильных
подключений сервера Macroscop и компонентов на клиентской стороне (в браузере).

Вещание с помощью HTML5

Реализовано в Macroscop версии 4.0 и более поздних.
Вещание видео в режиме реального времени на сайт может быть организовано с
помощью службы мобильных подключений сервера Macroscop и HTML5-проигрывателя,
предоставляемого Web-клиентом Macroscop.

Для организации вещания необходимо сформировать ссылку на поток выбранной камеры

следующего вида:
{Протокол}://{Сервер}:{Порт}/embedding/[Link]#/embed?login={Логин}&password={
Пароль}&channelid={ID}&channelstreamtype={Поток}&mode={Формат}
Где:
• Протокол — сетевой протокол, выбранный для взаимодействия с сервером
Macroscop. Вещание доступно по протоколам http и https.
• Сервер — доменное имя или IP адрес сервера Macroscop, используемого для
получения видео.
• Порт — сетевой порт, соответствующий выбранному Протоколу. Порты по
умолчанию: 8080 для http; 18080 для https.
• Логин — имя пользователя Macroscop, от имени которого будет осуществляться
вещание.
• Пароль — md5-хэш пароля пользователя Macroscop.
• ID — идентификатор канала, выбранного для вещания. Идентификаторы всех
каналов в системе могут быть получены с помощью соответствующего запроса (см.
Получение конфигурации системы).
• Поток — тип потока, предпочтительного для вещания. Может принимать
значения: Main (Основной), Alternative (Альтернативный 1), SecondAlternative
(Альтернативный 2), ThirdAlternative (Альтернативный 3).
• Формат — предпочитаемый формат видео: MJPEG или H264.
Перечисленные параметры не имеют значения по умолчанию и обязательны к
заполнению. Если для пользователя не задан Пароль, сервер Macroscop будет
ожидать md5-хэш пустой строки (D41D8CD98F00B204E9800998ECF8427E).
Регистрозависимым является только параметр Логин, в то время как остальные
параметры могут быть указаны в любом регистре.

Пример ссылки:
[Link]
89aeb826edde08a1109deb5e61a4ba&channelid=d8112e29-fce9-40ea-bef4-
a1c7b276ac98&channelstreamtype=Alternative&mode=H264

Доступ к потоку видео осуществляется с помощью компонентов Web-клиента

Macroscop, в связи с чем необходимо выполнить следующие настройки в приложении
Macroscop Конфигуратор:
• Поток должен быть разрешён для использования мобильными приложениями и
Web-клиентом. Для этого необходимо в разделе Камеры, выбрать нужную камеру
и убедиться, что у выбранного для вещания потока включена опция Мобильные
и веб клиенты.
• Пользователь, от чьего имени запрашивается поток, должен иметь право на
использование встраиваемого компонента. Для этого необходимо в разделе
 75

Пользователи выбрать группу пользователя и нажать Редактировать. В

открывшемся окне, на вкладке Основные необходимо убедиться, что право
Подключение с мобильных устройств и Web-Клиента включено.
• Пользователь, от чьего имени запрашивается поток, должен иметь право на
просмотр выбранной для вещания камеры. Для этого необходимо в разделе
Пользователи выбрать группу пользователя и нажать Редактировать. В
открывшемся окне, на вкладке Камеры необходимо убедиться, что для
выбранной камеры включено право Наблюдение или Наблюдение и архив.
В целях безопасности рекомендуется использовать для вещания видео на сайт
отдельного пользователя, предоставив ему необходимый для этих целей минимум
прав.

Предоставить доступ к видео по сформированной ссылке можно несколькими способами.

Например, разместить на странице сформированную ссылку на поток как гиперссылку
для открытия отдельной вкладки с проигрывателем или добавить в качестве
содержимого iframe-элемента для воспроизведения непосредственно на странице.

Чтобы открывать проигрыватель в виде отдельной вкладки, необходимо разместить на

странице элемент гиперссылки <a>, добавив в него ранее сформированную ссылку на
поток:
<a href="[Link]
login=Website&password=5989aeb826edde08a1109deb5e61a4ba&
channelid=d8112e29-fce9-40ea-bef4-a1c7b276ac98&
channelstreamtype=Alternative&mode=H264">Просмотр камеры Парковка</a>
При открытии проигрывателя в виде отдельной вкладки ширина и высота
изображения определяются шириной и высотой открывшейся вкладки, несмотря
на исходные параметры получаемого потока.

Чтобы разместить проигрыватель непосредственно на странице, необходимо добавить в

код страницы элемент встраиваемого содержимого <iframe>, добавив в него ранее
сформированную ссылку на поток:
<iframe src="[Link]
login=Website&password=5989aeb826edde08a1109deb5e61a4ba&
channelid=d8112e29-fce9-40ea-bef4-a1c7b276ac98&
channelstreamtype=Alternative&mode=H264" frameborder="0" width="{Ширина}"
height="{Высота}" allowfullscreen></iframe>
При встраивании проигрывателя в качестве содержимого iframe-элемента
размеры изображения определяются заданными параметрами Ширина и
Высота, несмотря на исходные параметры получаемого потока.

Описанный способ имеет ряд ограничений, которые необходимо учитывать при

использовании:
• Для данного способа необходима поддержка Media Source API со стороны
браузера. Актуальные версии браузеров, кроме Safari для iOS, поддерживают
этот API.
• Вещание доступно только для видео в режиме реального времени. Доступ к
архиву не поддерживается.
• Вещание доступно только для видео. Получение звука от камеры данным
способом не поддерживается.
• Вещание доступно только для потоков в формате H264 и MJPEG. Другие
форматы видео не поддерживаются.
• Вещание в формате H264 доступно только при условии, что исходный поток
транслируется в том же формате. Перекодирование исходного потока MJPEG в
H264 не предусмотрено.
 76

• Вещание в MJPEG доступно как для камер, изначально передающих поток в этом
формате, так и для потоков H264 путём перекодирования исходного
изображения на сервере.
• При возникновении проблем с отображением потока в формате H264 произойдёт
автоматическая смена формата на MJPEG без возможности обратного
переключения со стороны пользователя.
Перекодирование H264 в MJPEG потребляет ресурсы сервера и может привести к
повышенной нагрузке на сервер.

В случае возникновения сложностей с вещанием необходимо убедиться, что:

• Указанные сервер, камера и выбранный для вещания поток активны и
доступны для использования.
• Пользователю предоставлены необходимые для получения потока права.
• Все обязательные параметры ссылки-запроса (данные пользователя,
идентификатор камеры, параметры потока) заполнены корректными данными.
Подробную информацию о причинах можно получить в Консоли браузера. Для
этого откройте сформированную ссылку как отдельную вкладку, запустите
Инструменты разработчика (F12) и перейдите на вкладку Консоль.

Вещание с помощью Flash (устарело)

Данный способ является устаревшим в связи с прекращением поддержки
технологии Flash со стороны разработчика Adobe.

Вещание видео на сайт может быть организовано с помощью службы мобильных

подключений сервера Macroscop и Flash-компонента на клиентской стороне. Пример
использования компонента на HTML-странице размещен в папке Examples\SiteFlash.
На HTML-странице ([Link]) необходимо указать параметры подключения к серверу
Macroscop, а также идентификатор (имя/номер) канала, с которого должно
транслироваться видео и требуемый кодек (H.264 или MJPEG).
Пример настройки:
var flashvars = {
server: "[Link]", // адрес сервера
port: "8080", // порт сервера
login: "root", // имя пользователя
password_hash: "", // md5-хэш пароля
mode: "MJPEG," // предпочитаемый формат видео
channel: "1" // имя, номер или идентификатор канала
};
Идентификаторы всех каналов в системе могут быть получены с помощью
соответствующего запроса (см. Получение конфигурации системы).
Параметр Предпочитаемый формат видео (mode) может принимать значения MJPEG,
H264 или вообще пропущен. Если предпочитаемый формат видео не задан,
то автоматически будет выбран подходящий формат. Значение H264 можно указать
только для камер, транслирующих видеопотоки, закодированные в H.264. Значение
MJPEG можно указать для всех камер, однако в случае перекодирования из H.264 это
может привести к повышенной нагрузке на сервер.
 77

Вещание с помощью JavaScript (устарело)

Данный способ является устаревшим, поскольку создает повышенную нагрузку
на сервер Macroscop и предоставляет худшее качество по сравнению
с другими способами.

Вещание видео на сайт может быть организовано с помощью сервера Macroscop

и JavaScript-компонента на клиентской стороне. Скрипт для клиентской стороны
и пример его использования на HTML-странице размещен в папке
Examples\Site\[Link]. В скрипте необходимо указать параметры
подключения к серверу Macroscop, а также идентификатор (имя/номер) канала,
с которого должно транслироваться видео и требуемый размер области, в которую будут
выводиться видеокадры.
Пример настройки скрипта:
var serverUrl = "[Link] /*URL сервера*/
var login = "root" /*пользователь, имеющий права на просмотр транслируемого канала*/
var password = ""; /*MD5-хэш пароля пользователя в верхнем регистре или пуста строка,
если пароль пустой*/
var channelnum = 0; /*порядковый номер канала в общей конфигурации, счет с 0*/
var drawWidth = 577; /*ширина области отображения, в пикселях*/
var drawHeight = 432; /*высота области отображения, в пикселях*/
Пример скрипта, использующего идентификатор канала вместо его порядкового номера,
размещен в папке Examples\Site\frameReceiver_id.js.
На самой HTML-странице должен быть размещен тег <img name='frontImage' />,
в котором будет отображаться видеопоток, закодированный в MJPEG.
Не рекомендуется изменять размеры области отображения видео динамически,
поскольку это приведет к существенному повышению потребляемых ресурсов
службой мобильных подключений, так как эта служба перекодирует в MJPEG
исходный видеопоток, после чего полученный поток кадров разделяет между
многими клиентами (сессиями). Использование разных разрешений также
приведет к дополнительной нагрузке на службу мобильных подключений.