nx_cloud_storage_sdk  1.0
Cloud Storage SDK
data.h
1 // Copyright 2018-present Network Optix, Inc. Licensed under MPL 2.0: www.mozilla.org/MPL/2.0/
2 
3 #pragma once
4 
5 #include <chrono>
6 #include <limits>
7 #include <optional>
8 #include <string>
9 #include <vector>
10 
11 #include <camera/camera_plugin.h>
12 #include <nx/kit/json.h>
13 #include <nx/sdk/cloud_storage/i_media_data_packet.h>
14 #include <nx/sdk/cloud_storage/i_plugin.h>
15 #include <nx/sdk/i_device_info.h>
16 
17 namespace nx::sdk::cloud_storage {
18 
20 {
21  PluginManifest(const char* jsonStr);
22  PluginManifest(const nx::kit::Json& json);
24  const std::string& id,
25  const std::string& name,
26  const std::string& description,
27  const std::string& version,
28  const std::string& vendor);
29 
30  PluginManifest() = default;
31 
32  template<typename T>
33  PluginManifest(const T&) = delete;
34 
35  bool operator==(const PluginManifest&) const;
36 
37  // Plugin identificator. This is what will be displayed int the storage type field in
38  // the storage dialog.
39  std::string id;
40  // Full plugin name ('Stub Cloud Storage plugin', for example)
41  std::string name;
42  // Brief plugin description.
43  std::string description;
44  std::string version;
45  std::string vendor;
46 
47  nx::kit::Json to_json() const;
48 };
49 
50 struct TimePeriod
51 {
52  TimePeriod(const char* jsonStr);
53  TimePeriod(const nx::kit::Json& json);
54  TimePeriod(std::chrono::milliseconds startTimestamp, std::chrono::milliseconds duration);
55  TimePeriod() = default;
56 
57  template<typename T>
58  TimePeriod(const T&) = delete;
59 
60  std::chrono::milliseconds startTimestamp{-1};
61  std::chrono::milliseconds duration{-1};
62 
63  bool isInfinite() const;
64  bool contains(std::chrono::milliseconds timestamp) const;
65  bool isNull() const;
66  bool intersects(const TimePeriod& other) const;
67  std::optional<std::chrono::milliseconds> endTimestamp() const;
68 
69  nx::kit::Json to_json() const;
70  bool operator<(const TimePeriod& other) const;
71  bool operator==(const TimePeriod& other) const;
72 };
73 
74 using TimePeriodList = std::vector<TimePeriod>;
75 nx::kit::Json timePeriodListToJson(const TimePeriodList& timePeriods);
76 TimePeriodList timePeriodListFromJson(const char* data);
77 
79 {
80  KeyValuePair(const char* jsonStr);
81  KeyValuePair(const nx::kit::Json& json);
82  KeyValuePair() = default;
83  KeyValuePair(const std::string& name, const std::string& value);
84 
85  template<typename T>
86  KeyValuePair(const T&) = delete;
87 
88  bool operator==(const KeyValuePair&) const;
89 
90  nx::kit::Json to_json() const;
91 
92  std::string name;
93  std::string value;
94 };
95 
96 nx::kit::Json keyValuePairsToJson(const std::vector<KeyValuePair>& keyValuePairList);
97 
99 
100 // Device description object. Consists of key-value pairs of the device attributes.
102 {
103  DeviceDescription() = default;
104  DeviceDescription(const char* jsonData);
105  DeviceDescription(const nx::kit::Json& json);
107 
108  template<typename T>
109  DeviceDescription(const T&) = delete;
110 
111  bool operator==(const DeviceDescription&) const;
112 
113  std::vector<DeviceParameter> parameters;
114 
115  const char* getParamValue(const std::string& key) const;
116  nx::kit::Json to_json() const;
117  std::optional<std::string> deviceId() const;
118 };
119 
120 std::string deviceId(nx::sdk::cloud_storage::IDeviceAgent* deviceAgent);
121 int toStreamIndex(nxcip::MediaStreamQuality quality);
122 std::string toString(sdk::cloud_storage::MetadataType metadataType);
123 
124 // Bookmark object passed to the plugin when bookmark is saved. And the same object
125 // should be returned to the Server when queried back if it matches against the filter.
126 // Plugin should keep bookmarks as is, without any changes.
127 struct Bookmark
128 {
129  Bookmark(const char* jsonData);
130  Bookmark(const nx::kit::Json& json);
131  Bookmark() = default;
132 
133  template<typename T>
134  Bookmark(const T&) = delete;
135 
136  bool operator==(const Bookmark&) const;
137 
138  nx::kit::Json to_json() const;
139 
140  // Bookmark unique id.
141  std::string id;
142  // User that created this bookmark id.
143  std::string creatorId;
144  std::chrono::milliseconds creationTimestamp{};
145  std::string name;
146  std::string description;
147  std::chrono::milliseconds timeout = std::chrono::milliseconds(-1);
148  std::chrono::milliseconds startTimestamp;
149  std::chrono::milliseconds duration{};
150  std::vector<std::string> tags;
151  std::string deviceId;
152 };
153 
154 using BookmarkList = std::vector<Bookmark>;
155 
156 BookmarkList bookmarkListFromJson(const char* data);
157 
158 enum class SortOrder
159 {
160  ascending,
161  descending,
162 };
163 
164 std::string sortOrderToString(SortOrder order);
165 SortOrder sortOrderFromString(const std::string& s);
166 
167 // This filter will be passed to the plugin when bookmarks are queried by Server.
168 // For processing example refer to the 'nx/sdk/cloud_storage/algorithm.cpp'
170 {
171  enum class SortColumn
172  {
173  name,
174  startTime,
175  duration,
176  creationTime,
177  tags,
178  description,
179  };
180 
181  BookmarkFilter(const char* jsonData);
182  BookmarkFilter(const nx::kit::Json& json);
183  BookmarkFilter() = default;
184 
185  template<typename T>
186  BookmarkFilter(const T&) = delete;
187 
188  bool operator==(const BookmarkFilter&) const;
189 
190  nx::kit::Json to_json() const;
191 
192  static std::string sortColumnToString(SortColumn column);
193  static SortColumn sortColumnFromString(const std::string& s);
194 
195  std::optional<std::string> id;
196  std::optional<std::chrono::milliseconds> startTimestamp;
197  std::optional<std::chrono::milliseconds> endTimestamp;
198  // Arbitrary text to search for within bookmark name or tag.
199  std::optional<std::string> text;
200  std::optional<int> limit;
201  SortOrder order = SortOrder::ascending;
202  SortColumn column = SortColumn::startTime;
203  // Minimum bookmark duration time.
204  std::optional<std::chrono::milliseconds> minVisibleLength;
205  std::vector<std::string> deviceIds;
206  std::optional<std::chrono::milliseconds> creationStartTimestamp;
207  std::optional<std::chrono::milliseconds> creationEndTimestamp;
208 };
209 
210 // Motion object passed to the plugin when bookmark is saved. And the same object
211 // should be returned to the Server when queried back if it matches against the filter.
212 // Plugin should keep motion as is, without any changes.
213 struct Motion
214 {
215  Motion() = default;
216  Motion(const char* jsonData);
217  Motion(const nx::kit::Json& json);
218 
219  template<typename T>
220  Motion(const T&) = delete;
221 
222  bool operator==(const Motion&) const;
223 
224  int channel = 0;
225  std::chrono::milliseconds startTimestamp;
226  std::chrono::milliseconds duration{};
227  std::string deviceId;
228  // Binary motion mask data. Encoded in base64.
229  // This mask covers the frame as a 44x32 cells grid. Every non zero bit in the mask means
230  // that motion was detected in that cell. So, the bit mask size is 44*32=1408 bits = 176 bytes
231  // before encoding to base64. The mask is rotated by 90 degree. The very first bit of the mask
232  // is the top-left corner bit. The next bit is for 1-st column, 2-nd row e.t.c.
233  std::string dataBase64;
234 
235  nx::kit::Json to_json() const;
236 };
237 
238 struct Rect
239 {
240  Rect(const char* jsonData);
241  Rect(const nx::kit::Json& json);
242  Rect(double x, double y, double w, double h);
243  Rect() = default;
244 
245  template<typename T>
246  Rect(const T&) = delete;
247 
248  bool operator==(const Rect&) const;
249 
250  nx::kit::Json to_json() const;
251 
252  double x = 0;
253  double y = 0;
254  double w = 0;
255  double h = 0;
256 
257  bool isEmpty() const;
258  bool intersectsWith(const Rect& other) const;
259  double left() const;
260  double top() const;
261  double right() const;
262  double bottom() const;
263 
264 private:
265  bool isInside(double x, double y) const;
266 };
267 
268 // This filter will be passed to the plugin when motion is queried by Server.
269 // For processing example refer to the 'nx/sdk/cloud_storage/algorithm.cpp'
271 {
272  MotionFilter() = default;
273  MotionFilter(const char* jsonData);
274  MotionFilter(const nx::kit::Json& json);
275 
276  template<typename T>
277  MotionFilter(const T&) = delete;
278 
279  bool operator==(const MotionFilter&) const;
280 
281  nx::kit::Json to_json() const;
282 
283  std::vector<std::string> deviceIds;
284  TimePeriod timePeriod;
285 
286  // Regions of screen which should be matched against the motion data.
287  // Motion matches if motion.data intersected with any of rectangles in regions contains at
288  // least one cell of motion i.e. the corresponding bit in the motion.data is set to 1.
289  std::vector<Rect> regions;
290  // Maximum number of objects to return.
291  std::optional<int> limit;
292 
294  SortOrder order = SortOrder::descending;
295 
296  // If distance between two time periods less than this value, then those periods must be merged
297  // ignoring the gap.
298  std::chrono::milliseconds detailLevel;
299 };
300 
301 using Attribute = KeyValuePair;
302 using Attributes = std::vector<KeyValuePair>;
303 
305 {
306  ObjectRegion() = default;
307  ObjectRegion(const nx::kit::Json & json);
308  ObjectRegion(const char* jsonData);
309 
310  template<typename T>
311  ObjectRegion(const T&) = delete;
312 
313  bool operator==(const ObjectRegion&) const;
314 
315  nx::kit::Json to_json() const;
316 
317  // Binary mask of the bounding box grid. It has the same binary structure as motion data.
318  std::string boundingBoxGridBase64;
319 };
320 
321 // The image/thumbnail that represent the object track metadata. This information describes the
322 // image from the media archive (a part of the video frame for track thumbnail). This information
323 // is used by Server in case if the best shot image for the track is not uploaded explicitly.
324 // BestShot is NULL if its rect is empty.
325 struct BestShot
326 {
327  BestShot() = default;
328  BestShot(const nx::kit::Json& json);
329  BestShot(const char* jsonData);
330 
331  template<typename T>
332  BestShot(const T&) = delete;
333 
334  bool operator==(const BestShot&) const;
335 
336  nx::kit::Json to_json() const;
337  bool isNull() const;
338 
339  std::chrono::microseconds timestamp{};
340  Rect rect;
341  int streamIndex = -1;
342 };
343 
345 {
346  ObjectTrack() = default;
347  ObjectTrack(const nx::kit::Json & json);
348  ObjectTrack(const char* jsonData);
349 
350  template<typename T>
351  ObjectTrack(const T&) = delete;
352 
353  bool operator==(const ObjectTrack&) const;
354 
355  nx::kit::Json to_json() const;
356 
357  std::string id;
358  // Device that this object track was collected from id.
359  std::string deviceId;
360  // Object category (vehicle, person, e.t.c.). The string of the type must be compared
361  // starting from the beginning. For example, object track may have a 'human.head' type.
362  // This object track should be found if the filter.text contains 'human' object type.
363  std::string objectTypeId;
364  // A list of the object track attributes. Each attribute in the list consists of a name
365  // and a value. For example 'color,red','hasBag,true' e.t.c. Attribute value may also contain a
366  // numeric range. For example: 'speed, [10..50]'.
367  Attributes attributes;
368  // Object track start time.
369  std::chrono::microseconds firstAppearanceTimestamp{};
370  // Object track end time.
371  std::chrono::microseconds lastAppearanceTimestamp{};
372  // Object track coordinates. See ObjectRegion description for more details.
373  ObjectRegion objectPosition;
374  // An analytics plugin id that provided data.
375  std::string analyticsEngineId;
376  BestShot bestShot;
377 };
378 
379 // BestShot image associated with the given ObjectTrack.
381 {
382  BestShotImage() = default;
383  BestShotImage(const nx::kit::Json& json);
384  BestShotImage(const char* jsonData);
385 
386  template<typename T>
387  BestShotImage(const T&) = delete;
388 
389  bool operator==(const BestShotImage&) const;
390 
391  nx::kit::Json to_json() const;
392 
393  std::string objectTrackId;
394  // Human-readable image format name.
395  std::string format;
396  // Base64 encoded image data.
397  std::string data64;
398 };
399 
400 using AnalyticsLookupResult = std::vector<ObjectTrack>;
401 
402 AnalyticsLookupResult analyticsLookupResultFromJson(const char* data);
403 
404 // Helper struct representing a range border point.
406 {
407  RangePoint() = default;
408  RangePoint(const nx::kit::Json& json);
409  RangePoint(const char* jsonData);
410 
411  template<typename T>
412  RangePoint(const T&) = delete;
413 
414  RangePoint(float value, bool inclusive);
415 
416  bool operator==(const RangePoint&) const;
417 
418  nx::kit::Json to_json() const;
419 
420  float value = 0.0;
421  bool inclusive = false;
422 };
423 
424 // Numeric range representation. Used as one of the possible search conditions while querying
425 // object tracks filtered by attributes.
427 {
428  NumericRange() = default;
429  NumericRange(const nx::kit::Json& json);
430  NumericRange(const char* jsonData);
431 
432  template<typename T>
433  NumericRange(const T&) = delete;
434 
435  bool operator==(const NumericRange&) const;
436 
437  NumericRange(float value): from(RangePoint{value, true}), to(RangePoint{value, true}) {}
438 
439  NumericRange(std::optional<RangePoint> from, std::optional<RangePoint> to):
440  from(std::move(from)), to(std::move(to))
441  {
442  }
443 
444  static std::optional<NumericRange> fromString(const std::string& s);
445 
446  nx::kit::Json to_json() const;
447 
448  bool intersects(const NumericRange& range) const;
449  bool hasRange(const NumericRange& range) const;
450 
451  std::optional<RangePoint> from;
452  std::optional<RangePoint> to;
453 };
454 
455 // A search condition representation specifying how exactly to filter queried object tracks
456 // by their attributes.
457 // Multiple condition match results are joined using AND logic. So for object track to be included
458 // in the result its attributes (any of them) should match every condition present in the Filter.
459 // I.e. bool objectTrackMatch = atLeastOneAttrMatch(condition_1) && ... && atLeastOneAttrMatch(condition_N)
461 {
462  AttributeSearchCondition() = default;
464  AttributeSearchCondition(const char* jsonData);
465 
466  template<typename T>
467  AttributeSearchCondition(const T&) = delete;
468 
469  bool operator==(const AttributeSearchCondition&) const;
470 
471  nx::kit::Json to_json() const;
472 
473  // All search types except 'textMatch' assume that ObjectTrack attribute name matches
474  // the condition name only if the match starts from the beginning and lasts till the end
475  // or the point separator.
476  // For example, let one of the ObjectTrack attribute equals to 'car.color=blue'. Then the
477  // Search conditions with the following names should match: 'car', 'car.color'. But not the
478  // 'ca', 'car.co', 'carxx' or 'car.colov'.
479  // In case of the 'textMatch' for the attribute to match search condition it's enough that
480  // either attribute name or value contain AttributeSearchCondition::text. Condition name and
481  // value should be ignored in this case.
482  // 'numericRangeMatch' assumes that the attribute value contains valid NumericRange and
483  // it intersects AttributeSearchCondition::range.
484  enum class Type
485  {
486  attributePresenceCheck,
487  attributeValueMatch,
488  textMatch,
489  numericRangeMatch,
490  };
491 
492  static std::string typeToString(Type type);
493  static Type typeFromString(const std::string& s);
494 
495  Type type;
496  std::string name;
497  std::string value;
498  std::string text;
499 
500  // If it is set to true than the ObjectTrack should be included in the result only if it does not
501  // match the given condition.
502  bool isNegative = false;
503 
504  // Used when type == numericRangeMatch. Object track attribute value should contain numeric range
505  // value and it should intersect the given condition value for the Object track to be included in the result.
506  NumericRange range;
507 };
508 
509 // Filter used to search for object tracks.
511 {
512  AnalyticsFilter() = default;
513  AnalyticsFilter(const char* jsonData);
514  AnalyticsFilter(const nx::kit::Json& json);
515 
516  template<typename T>
517  AnalyticsFilter(const T&) = delete;
518 
519  bool operator==(const AnalyticsFilter&) const;
520 
521  nx::kit::Json to_json() const;
522 
523  enum Option
524  {
525  none = 0x0,
526  ignoreTextFilter = 0x1,
527  ignoreBoundingBox = 0x2,
528  ignoreTimePeriod = 0x4,
529  };
530 
531  static std::string optionsToString(int options);
532  static int optionsFromString(const std::string& s);
533 
534  // If empty, any device is a match.
535  std::vector<std::string> deviceIds;
536  // See ObjectTrack.objectTypeId for explanation. If empty, any objectTrack.objectTypeId
537  // is a match.
538  std::vector<std::string> objectTypeIds;
539  // If empty, any objectTrackId is a match.
540  std::optional<std::string> objectTrackId;
541  // If not null only object tracks with firstAppearanceTimestamp within this period should
542  // match.
543  TimePeriod timePeriod;
544  // Bounding box area to search within. Search should be done similarly to motion data.
545  std::optional<Rect> boundingBox;
546  std::optional<int> maxObjectTracksToSelect;
547  std::vector<AttributeSearchCondition> attributeSearchConditions;
548 
550  SortOrder order = SortOrder::descending;
551 
552  std::optional<std::string> analyticsEngineId;
553  int options = Option::none;
554  std::chrono::milliseconds detailLevel{};
555 };
556 
558 {
559  CodecInfoData();
560  CodecInfoData(const char* jsonData);
561  CodecInfoData(const nx::kit::Json& json);
563 
564  template<typename T>
565  CodecInfoData(const T&) = delete;
566 
567  bool operator==(const CodecInfoData&) const;
568 
569  nxcip::CompressionType compressionType = nxcip::CompressionType::AV_CODEC_ID_NONE;
570  nxcip::PixelFormat pixelFormat = nxcip::PixelFormat::AV_PIX_FMT_YUV420P;
571  nxcip::MediaType mediaType = nxcip::MediaType::AVMEDIA_TYPE_UNKNOWN;
572  int width = -1;
573  int height = -1;
574  int64_t codecTag = -1;
575  int64_t bitRate = -1;
576  int channels = -1;
577  int frameSize = -1;
578  int blockAlign = -1;
579  int sampleRate = -1;
580  nxcip::SampleFormat sampleFormat = nxcip::SampleFormat::AV_SAMPLE_FMT_NONE;
581  int bitsPerCodedSample = -1;
582  int64_t channelLayout = -1;
583  std::string extradataBase64;
584  int channelNumber = -1;
585 
586  nx::kit::Json to_json() const;
587 };
588 
589 IDeviceInfo* deviceInfo(const DeviceDescription& deviceDescription);
590 
591 class MediaPacket;
592 
594 {
595  MediaPacketData(const IMediaDataPacket* mediaPacket, std::chrono::milliseconds startTime);
596  MediaPacketData() = default;
597 
598  std::vector<uint8_t> data;
599  int dataSize = 0;
600  nxcip::CompressionType compressionType = nxcip::CompressionType::AV_CODEC_ID_NONE;
601  nxcip::UsecUTCTimestamp timestampUs = 0;
602  IMediaDataPacket::Type type = IMediaDataPacket::Type::unknown;
603  int channelNumber = -1;
604  bool isKeyFrame = false;
605  std::vector<uint8_t> encryptionData;
606 };
607 
609 {
610  CloudDeviceReportEntry() = default;
611  CloudDeviceReportEntry(const char* jsonData);
613 
614  std::string id;
615  std::string serviceId;
616 
617  bool operator==(const CloudDeviceReportEntry& other) const;
618  nx::kit::Json to_json() const;
619 };
620 
621 using CloudDeviceEntryList = std::vector<CloudDeviceReportEntry>;
622 
624 {
625  CloudDeviceReport() = default;
626  CloudDeviceReport(const char* jsonData);
627  CloudDeviceReport(const nx::kit::Json& json);
628 
629  std::string cloudSystemId;
630  CloudDeviceEntryList devices;
631 
632  bool operator==(const CloudDeviceReport& other) const;
633  nx::kit::Json to_json() const;
634 };
635 
636 } // nx::sdk::namespace cloud_storage
Definition: i_codec_info.h:15
Definition: data.h:213
Definition: i_media_data_packet.h:16
Definition: json.cpp:80
Definition: data.h:127
MediaType
Definition: camera_plugin_types.h:65
SortOrder order
Definition: data.h:294
Definition: data.h:608
Definition: i_device_info.h:13
Definition: i_device_agent.h:21
SortOrder order
Definition: data.h:550
Definition: data.h:238
Definition: algorithm.cpp:8
PixelFormat
Definition: camera_plugin_types.h:39
MediaStreamQuality
Definition: camera_plugin.h:1177
SampleFormat
Definition: camera_plugin_types.h:76
Definition: data.h:325