PKamCheckAnalytics Class Reference

Detailed Description

The PKamCheckAnalytics class provides three static methods for performing a KamCheck camera tampering analysis and one static method for obtaining a good reference image from a video clip.

KamCheck compares a video clip with a reference image from the same camera recorded at an earlier (supposedly) untampered point in time. A probability of the camera being tampered is returned.

dot_inline_dotgraph_14.png

Reasons for high tamper probability include

  • Video out of focus or blurred
  • Field of view displacement
  • Complete masking
  • Video frozen
  • Video resolution changed

Some notes on using KamCheck

  • When performing a KamCheck it is preferable that the video clip be recorded at approximately the same time of day as the reference image. It is strongly discouraged to mix day and night recordings.
  • The video clip and reference image must be of the same resolution
  • The video clip should be short, ideally around 25 frames. No more than 80 frames will be read from the clip.
  • KamCheck works best in daylight. It might still be possible to use KamCheck during the night, but the scene should be well enough lit for the algorithms to work. Furthermore, if lighting is not consistent from night to night, view displacement estimation may fail. In this case, it is recommended to use PKamCheckAnalytics::CheckNight(), that performs all the usual checks except the view displacement estimation.
  • It is recommended to use a reference image obtained from a video clip using the static method PKamCheckAnalytics::GetReferenceFrame(). This will allow you to detect if the camera is already out of focus or frozen or too lacking in structure for the displacement analysis.
  • KamCheck determines if the camera is out of focus by comparing the video's sharpness to the sharpness of the reference image. For this to work, the reference image must have some structure for the sharpness computation to work. So e.g. a camera looking at a uniformly coloured wall can not be managed by KamCheck.
  • KamCheck estimates field of view displacement (or rather the lack thereof) by checking whether enough identifiable parts of the reference image have stayed fixed in the test video. For this to work, something fixed and identifiable must always be visible (e.g. markings on a parking lot, a sign on a wall, the roof of a building, doors, windows, ...). So e.g. a camera seeing only a uniform concrete floor covered in containers that may all be moved around cannot be managed by KamCheck. If this is the case, it is suggested to use PKamCheckAnalytics::CheckNight(), that performs all the usual checks except the view displacement estimation.
  • KamCheck is fairly robust to wind and weather, but if your camera is covered with raindrops or snowflakes it will probably fail. Also, if the scene is covered in fog, there is a fair chance that KamCheck will signal the camera as being out of focus.

An example of its use is shown below

/*
* Copyright (C) 2015-2018 Digital Barriers plc. All rights reserved.
* Contact: http://www.digitalbarriers.com/
*
* This file is part of the Papillon SDK.
*
* You can't use, modify or distribute any part of this file without
* the explicit written agreements of Digital Barriers.
*/
#include <PapillonCore.h>
USING_NAMESPACE_PAPILLON
const PString SAMPLE_DIR = PPath::Join(PUtils::GetEnv("PAPILLON_INSTALL_DIR"), "Data", "Samples");
PResult KamCheck(const PString& inputVideoFile, const PString& inputImageFile)
{
ReturnIfFailed(PInputVideoStream::Open(inputVideoFile, ivs));
PImage image;
ReturnIfFailed(image.Load(inputImageFile));
int probability;
PResult res = PKamCheckAnalytics::Check(ivs, image, probability);
std::cout << std::endl << "KamCheck tamper probability for " << inputVideoFile.Quote() << ": " << probability << "%" << std::endl;
if (probability > 0)
std::cout << "KamCheck tamper estimation: " << res << std::endl;
std::cout << std::endl;
return PResult::C_OK;
}
int main()
{
// Windy camera. KamCheck says it's OK (tampering probability should be 0%)
KamCheck(PPath::Join(SAMPLE_DIR, "kamcheck01.avi"), PPath::Join(SAMPLE_DIR, "kamcheck01.jpg")).OrDie();
// Example where camera has been moved. KamCheck flags a problem (tampering probability should be 100%)
KamCheck(PPath::Join(SAMPLE_DIR, "kamcheck02.avi"), PPath::Join(SAMPLE_DIR, "kamcheck02.jpg")).OrDie();
// Example where camera has been zoomed in. KamCheck flags a problem (tampering probability should be 100%)
KamCheck(PPath::Join(SAMPLE_DIR, "kamcheck03.avi"), PPath::Join(SAMPLE_DIR, "kamcheck03.jpg")).OrDie();
return 0;
}

Definition at line 80 of file PKamCheckAnalytics.h.

#include <PKamCheckAnalytics.h>

Member Function Documentation

◆ Check()

static papillon::PResult PKamCheckAnalytics::Check ( papillon::PInputVideoStream &  i_stream,
const papillon::PImage &  i_refImg,
int &  o_result 
)
static

Checks whether video seems to have been tampered relative to the reference image.

Parameters
i_streamThe video stream.
i_refImgThe reference image.
o_resultOutput value between 0 and 100. A low value indicates that video has not been tampered with.
Returns
PResult::C_OK when there is no tampering and PResult::Error (with an explaining message) when there is tampering. The error message may be one of the following:
  • "Reference image looks blurry" (This shouldn't happen if the reference image was obtained with PKamCheckAnalytics::GetReferenceFrame())
  • "Reference image does not seem to have enough structure" (This shouldn't happen if the reference image was obtained with PKamCheckAnalytics::GetReferenceFrame())
  • "Test video stream is empty"
  • "Test video stream looks static"
  • "Test video stream looks blurry"
  • "Test video stream looks masked or displaced"

◆ CheckDay()

static papillon::PResult PKamCheckAnalytics::CheckDay ( papillon::PInputVideoStream &  i_stream,
const papillon::PImage &  i_refImg,
int &  o_result 
)
static

Checks whether video seems to have been tampered relative to the reference image.

This function is added for completeness. It is identical to PKamCheckAnalytics::Check().

◆ CheckNight()

static papillon::PResult PKamCheckAnalytics::CheckNight ( papillon::PInputVideoStream &  i_stream,
const papillon::PImage &  i_refImg,
int &  o_result 
)
static

Checks whether video seems to have been tampered relative to the reference image.

Displacement checking is turned off since it might not be reliable on night images/videos. Otherwise, this function is identical to PKamCheckAnalytics::Check().

◆ GetReferenceFrame()

static papillon::PResult PKamCheckAnalytics::GetReferenceFrame ( papillon::PInputVideoStream &  i_stream,
papillon::PFrame &  o_refFrame 
)
static

Selects a good reference image from video clip.

If clip is static or if there are no good images, fail with useful message

Parameters
i_streamThe video stream
o_refFrameThe best reference frame to use from the stream
Returns
PResult::C_OK on success and PResult::Error (with an explaining message) if a good reference image could not be chosen. The error message may be one of the following:
  • "No valid images in reference video" (all frames are blurry or contain insufficient structure)
  • "Reference video looks static"