Hashers¶
All hashers from the Hasher
class.
-
class
perception.hashers.hasher.
Hasher
¶ All hashers implement a common set of methods from the Hasher base class.
-
allow_parallel
= True¶ Indicates whether the hashes can be computed in parallel
-
compute_distance
(hash1, hash2, hash_format='base64')¶ Compute the distance between two hashes.
Parameters: - hash1 (
Union
[ndarray
,str
]) – The first hash or vector - hash2 (
Union
[ndarray
,str
]) – The second hash or vector - hash_format – If either or both of the hashes are hash strings, what format the string is encoded in.
- hash1 (
-
compute_parallel
(filepaths, progress=None, progress_desc=None, max_workers=5, isometric=False)¶ Compute hashes in a parallelized fashion.
Parameters: - filepaths – A list of paths to images or videos (depending on the hasher).
- progress – A tqdm-like wrapper for reporting progress. If None, progress is not reported.
- progress_desc – The title of the progress bar.
- max_workers – The maximum number of workers
- isometric – Whether to compute all eight isometric transforms for each image.
-
distance_metric
= None¶ The metric to use when computing distance between two hashes. All hashers must supply this parameter.
-
dtype
= None¶ The numpy type to use when converting from string to array form. All hashers must supply this parameter.
-
hash_length
= None¶ Indicates the length of the hash vector
-
returns_multiple
= False¶ Whether or not this hash returns multiple values
-
string_to_vector
(hash_string, hash_format='base64')¶ Convert hash string to vector.
Parameters: - hash_string (
str
) – The input hash string - hash_format (
str
) – One of ‘base64’ or ‘hex’
- hash_string (
-
vector_to_string
(vector, hash_format='base64')¶ Convert vector to hash string.
Parameters: - vector (
ndarray
) – Input vector - hash_format (
str
) – One of ‘base64’ or ‘hex’
- vector (
-
Images¶
All image hashers inherit from the ImageHasher
class.
-
class
perception.hashers.hasher.
ImageHasher
¶ -
compute
(image, hash_format='base64')¶ Compute a hash from an image.
Parameters: - image (
Union
[str
,ndarray
,Image
,BytesIO
]) – An image represented as a filepath, a PIL image object, or as an np.ndarray object. If it is an np.ndarray object, it must be in RGB color order (note the OpenCV default is BGR). - hash_format – One ‘base64’, ‘hex’, or ‘vector’
Return type: Union
[str
,ndarray
]- image (
-
compute_isometric_from_hash
(hash_string_or_vector, hash_format='base64')¶ For supported hashes, obtain the hashes for the dihedral transformations of the original image. They are provided in the following order:
- Vertical flip
- Horizontal flip
- 180 degree rotation
- 90 degree rotation
- 90 degree rotation and vertical flip
- 90 degree rotation and horizontal flip
- 270 degree rotation
Parameters: - hash_string_or_vector – The hash string or vector
- hash_format – One ‘base64’ or ‘hex’
-
compute_with_quality
(image, hash_format='base64')¶ Compute hash and hash quality from image.
Parameters: - image (
Union
[str
,ndarray
,Image
,BytesIO
]) – An image represented as a filepath, a PIL image object, or as an np.ndarray object. If it is an np.ndarray object, it must be in RGB color order (note the OpenCV default is BGR). - hash_format – One ‘base64’ or ‘hex’
Return type: Tuple
[str
,int
]Returns: A tuple of (hash, quality)
- image (
-
The following image hash functions are included in the package.
-
class
perception.hashers.image.
AverageHash
(hash_size=8)¶ Computes a simple hash comparing the intensity of each pixel in a resized version of the image to the mean. Implementation based on that of ImageHash.
-
class
perception.hashers.image.
PHash
(hash_size=8, highfreq_factor=4, exclude_first_term=False, freq_shift=0)¶ Also known as the DCT hash, a hash based on discrete cosine transforms of images. See complete paper for details. Implementation based on that of ImageHash.
Parameters: - hash_size – The number of DCT elements to retain (the hash length will be hash_size * hash_size).
- highfreq_factor – The multiple of the hash size to resize the input image to before computing the DCT.
- exclude_first_term – WHether to exclude the first term of the DCT
- freq_shift – The number of DCT low frequency elements to skip.
-
class
perception.hashers.image.
WaveletHash
(hash_size=8, image_scale=None, mode='haar')¶ Similar to PHash but using wavelets instead of DCT. Implementation based on that of ImageHash.
-
class
perception.hashers.image.
MarrHildreth
¶ A wrapper around OpenCV’s Marr-Hildreth hash. See paper for details.
-
class
perception.hashers.image.
BlockMean
¶ A wrapper around OpenCV’s Block Mean hash. See paper for details.
-
class
perception.hashers.image.
ColorMoment
¶ A wrapper around OpenCV’s Color Moments hash. See paper for details.
-
class
perception.hashers.image.
PDQHash
¶ The Facebook PDQ hash. Based on the original implementation located at the official repository.
-
class
perception.hashers.image.
DHash
(hash_size=8)¶ A hash based on the differences between adjacent pixels. Implementation based on that of ImageHash.
-
class
perception.hashers.image.
PHashF
(hash_size=8, highfreq_factor=4, exclude_first_term=False, freq_shift=0)¶
-
class
perception.hashers.image.
PDQHashF
¶
Videos¶
All video hashers inherit from the VideoHasher
class.
-
class
perception.hashers.hasher.
VideoHasher
¶ -
compute
(filepath, errors='raise', hash_format='base64')¶ Compute a hash for a video at a given filepath.
Parameters: - filepath – Path to video file
- errors – One of “raise”, “ignore”, or “warn”. Passed to perception.hashers.tools.read_video.
-
hash_from_final_state
(state)¶ Called after all frames have been processed. Returns the final feature vector.
Parameters: state ( dict
) – The state dictionary at the end of processing.Return type: ndarray
-
process_frame
(frame, frame_index, frame_timestamp, state=None)¶ Called for each frame in the video. For all but the first frame, a state is provided recording the state from the previous frame.
Parameters: - frame (
ndarray
) – The current frame as an RGB ndarray - frame_index (
int
) – The current frame index - frame_timestamp (
float
) – The current frame timestamp - state (
Optional
[dict
]) – The state from the last call to process_frame
Return type: dict
- frame (
-
The following video hash functions are included in the package.
-
class
perception.hashers.video.
FramewiseHasher
(frame_hasher, interframe_threshold, frames_per_second=15, quality_threshold=None)¶ A hasher that simply returns frame-wise hashes at some regular interval with some minimum inter-frame distance threshold.
-
compute_batches
(filepath, batch_size, errors='raise', hash_format='base64')¶ Compute hashes for a video in batches.
Parameters: - filepath (
str
) – Path to video file - batch_size (
int
) – The batch size to use for returning hashes - errors – One of “raise”, “ignore”, or “warn”. Passed to perception.hashers.tools.read_video.
- hash_format – The format in which to return hashes
- filepath (
-
hash_from_final_state
(state)¶ Called after all frames have been processed. Returns the final feature vector.
Parameters: state – The state dictionary at the end of processing.
-
process_frame
(frame, frame_index, frame_timestamp, state=None)¶ Called for each frame in the video. For all but the first frame, a state is provided recording the state from the previous frame.
Parameters: - frame – The current frame as an RGB ndarray
- frame_index – The current frame index
- frame_timestamp – The current frame timestamp
- state – The state from the last call to process_frame
-
-
class
perception.hashers.video.
TMKL1
(frame_hasher=None, frames_per_second=15)¶ The TMK L1 video hashing algorithm.
-
hash_from_final_state
(state)¶ Called after all frames have been processed. Returns the final feature vector.
Parameters: state – The state dictionary at the end of processing.
-
process_frame
(frame, frame_index, frame_timestamp, state=None)¶ Called for each frame in the video. For all but the first frame, a state is provided recording the state from the previous frame.
Parameters: - frame – The current frame as an RGB ndarray
- frame_index – The current frame index
- frame_timestamp – The current frame timestamp
- state – The state from the last call to process_frame
-
-
class
perception.hashers.video.
TMKL2
(frame_hasher=None, frames_per_second=15, normalization='matrix')¶ The TMK L2 video hashing algorithm.
-
hash_from_final_state
(state)¶ Called after all frames have been processed. Returns the final feature vector.
Parameters: state – The state dictionary at the end of processing.
-
process_frame
(frame, frame_index, frame_timestamp, state=None)¶ Called for each frame in the video. For all but the first frame, a state is provided recording the state from the previous frame.
Parameters: - frame – The current frame as an RGB ndarray
- frame_index – The current frame index
- frame_timestamp – The current frame timestamp
- state – The state from the last call to process_frame
-
Tools¶
These utility functions are only used by the hashers but are documented here for completeness.
-
perception.hashers.tools.
compute_md5
(filepath)¶ Compute the md5 hash for a file at filepath.
Parameters: filepath – The path to the file Return type: str
-
perception.hashers.tools.
compute_quality
(image)¶ Compute a quality metric, using the calculation proposed by Facebook for their PDQ hash algorithm.
-
perception.hashers.tools.
compute_synchronized_video_hashes
(filepath, hashers, framerates=None, hash_format='base64', use_queue=True)¶ Compute the video hashes for a group of hashers with synchronized frame processing wherever possible.
Parameters: - filepath (
str
) – Path to video file. - hashers (
dict
) – A dictionary mapping hasher names to video hasher objects - hash_format – The format in which to return the hashes
- use_queue – Whether to use queued video frames
- filepath (
-
perception.hashers.tools.
get_common_framerates
(id_rates)¶ Compute an optimal set of framerates for a list of framerates. Optimal here means that reading the video at each of the framerates will allow one to collect all of the frames required with the smallest possible number of frames decoded.
For example, consider if we need to read a video at 3 fps, 5 fps, 1 fps and 0.5 fps. We could read the video 4 times (once per framerate). But a more optimal approach is to read the video only twice, once at 3 frames per second and another time at 5 frames per second. For the 1 fps hasher, we simply pass every 3rd frame of the 3 fps pass. For the 0.5 fps hasher, we pass every 6th frame of the 3 fps pass. So if you pass this function {A: 3, B: 5, C: 1, D: 0.5}, you will get back {3: [A, C, D], 5: C}.
Parameters: id_rates ( dict
) – A dictionary with IDs as keys and frame rates as values.Returns: - A dictionary with framerates as keys and a list of
- ids as values.
Return type: rate_ids
-
perception.hashers.tools.
get_string_length
(hash_length, dtype, hash_format='hex')¶ Compute the expected length of a hash string.
Parameters: - hash_length (
int
) – The length of the hash vector - dtype (
str
) – The dtype of the vector - hash_format – One of ‘base64’ or ‘hex’
Return type: int
Returns: The expected string length
- hash_length (
-
perception.hashers.tools.
read
(filepath_or_buffer)¶ Read a file into an image object
Parameters: filepath_or_buffer ( Union
[str
,ndarray
,Image
,BytesIO
]) – The path to the file or any object with a read method (such as io.BytesIO)
-
perception.hashers.tools.
read_video
(filepath, frames_per_second=None, max_queue_size=128, use_queue=True, errors='raise')¶ Provides a generator of RGB frames, frame indexes, and timestamps from a video. This function requires you to have installed ffmpeg.
Parameters: - filepath – Path to the video file
- frames_per_second (
Union
[str
,float
,None
]) – How many frames to provide for each second of video. If None, all frames are provided. If frames_per_second is “keyframes”, we use ffmpeg to select I frames from the video. - max_queue_size – The maximum number of frames to load in the queue
- use_queue – Whether to use a queue of frames during processing
- errors – Whether to ‘raise’, ‘warn’, or ‘ignore’ errors
Yields: (frame, frame_index, timestamp) tuples
-
perception.hashers.tools.
string_to_vector
(hash_string, dtype, hash_length, hash_format, verify_length=True)¶ Convert hash back to vector.
Parameters: - hash_string (
str
) – The input base64 hash string - dtype (
str
) – The data type of the hash - hash_length (
int
) – The length of the hash vector - verify_length (
bool
) – Whether to verify the string length
- hash_string (
-
perception.hashers.tools.
vector_to_string
(vector, dtype, hash_format)¶ Convert vector to hash.
Parameters: vector ( ndarray
) – Input vector