 |
ImFusion SDK 4.3
|
|
ImFusion SDK 4.3
|
#include <ImFusion/US/RemoveDuplicateFrames.h>
Algorithm for detecting and removing duplicate or nearly identical successive frames from an image set. More...
Inheritance diagram for RemoveDuplicateFrames:Algorithm for detecting and removing duplicate or nearly identical successive frames from an image set.
This algorithm is designed to clean up ultrasound or video sequences by identifying and removing frames that are either exact duplicates or nearly identical to their immediate predecessor. This reduces data size, improves processing efficiency, and can help mitigate artifacts in downstream processing. The algorithm compares each frame to the previous one using configurable pixel-wise difference thresholds. The algorithm does not create new data, but modifies the input. If p_repairHorizontalTearing is true, the algorithm attempts to repair horizontal tearing artifacts by merging frames at detected cutlines (see illustration below). Otherwise, the algorithm detects screen tearing and removes frames that contain the tear (see illustration below).
Example usage:
Public Member Functions | |
| RemoveDuplicateFrames (SharedImageSet *img) | |
| void | compute () override |
| Execute the algorithm. | |
| std::pair< std::shared_ptr< SharedImage >, DataComponentList > | processImage (const SharedImage &image, const DataComponentList &components) const override |
| Processes a single image and determines if it is a duplicate of the previous frame, using the current algorithm parameters. | |
| Public Member Functions inherited from Algorithm | |
| Algorithm () | |
| Default constructor will registers a single "compute" action that calls compute() and returns status(). | |
| virtual OwningDataList | takeOutput () |
| Return any new Data that was created by the Algorithm during the last call to compute(). | |
| virtual void | setProgress (Progress *progress) |
| Sets a Progress interface the algorithm can use to notify observers about its computing progress. | |
| Progress * | progress () const |
| Returns the progress interface if set. | |
| virtual int | status () const |
| Indicates the status of the last call to compute(). | |
| virtual bool | survivesDataDeletion (const Data *) const |
| Indicates whether the algorithm can handle (partial) deletion of the specified data, by default this checks whether the data is in the input list. | |
| const FactoryInfo & | factoryInfo () const |
| Returns the record describing how this Algorithm was instantiated by the AlgorithmFactory. | |
| void | setFactoryInfo (const FactoryInfo &value) |
| Sets the record describing how this Algorithm was instantiated by the AlgorithmFactory. | |
| Status | runAction (const std::string &id) |
Run the action with name id if it exists. | |
| const std::vector< Action > & | actions () |
| Get a mapping from Action id to Action as registered in this algorithm. | |
| Public Member Functions inherited from Configurable | |
| virtual void | configure (const Properties *p) |
| Configure this object instance by de-serializing the given Properties. | |
| virtual void | configuration (Properties *p) const |
| Serialize the current object configuration into the given Properties object. | |
| virtual void | configureDefaults () |
| Retrieve the properties of this object, replaces values with their defaults and sets it again. | |
| void | registerParameter (ParameterBase *param) |
| Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration(). | |
| void | unregisterParameter (const ParameterBase *param) |
| Remove the given Parameter or SubProperty from the list of registered parameters. | |
| Configurable (const Configurable &rhs) | |
| Configurable (Configurable &&rhs) noexcept | |
| Configurable & | operator= (const Configurable &) |
| Configurable & | operator= (Configurable &&) noexcept |
| Public Member Functions inherited from SequentialImageProcessor | |
| virtual void | setSequentialMode (bool b) |
| This method should be called to let the algorithm know that it should only run in sequential mode. | |
| virtual bool | isSequentialMode () const |
| Returns of the algorithm should only run in sequential mode. | |
Static Public Member Functions | |
| static bool | createCompatible (const DataList &data, Algorithm **a=nullptr) |
| Static Public Member Functions inherited from Algorithm | |
| static bool | createCompatible (const DataList &data, Algorithm **a=nullptr) |
| Factory function to check algorithm compatibility with input data and optionally instantiate it. | |
Public Attributes | |
| Parameter< bool > | p_printOnly = {"printOnly", false, this} |
| If true, only print information about duplicate frames without modifying the image set. | |
| Parameter< bool > | p_repairHorizontalTearing = {"repairHorizontalTearing", false, this} |
| If true, attempts to repair horizontal tearing artifacts between successive frames. | |
| Parameter< bool > | p_equalizeTs = {"equalizeTs", false, this} |
| If true, adjusts frame timestamps to be evenly spaced, assuming a constant frame rate. | |
| Parameter< int > | p_diffMax = {"diffMax", 0, this} |
| Maximum allowed absolute per-pixel difference between pixel values (of corresponding channels) for frames to be considered identical. | |
| Parameter< double > | p_diffMean = {"diffMean", 0.0, this} |
Maximum allowed mean of the absolute per-pixel difference between pixel values (of corresponding channels) for frames to be considered identical Pseudocode: mean(abs(frame_i - frame_i+1), axis=(0, 1, 2)) | |
| Parameter< double > | p_maxIdenticalProp = {"maxIdenticalProp", 1.0, this} |
| Threshold for the proportion of identical, non-saturated pixels required to consider two frames as duplicates. | |
| Parameter< int > | p_borderSize = {"borderSize", 0, this} |
| Number of lines at the top and bottom of the image considered as border regions. | |
| Parameter< bool > | p_strictMode = {"strictMode", false, this} |
| If true, requires all differing image regions to be contiguous when p_repairHorizontalTearing is true. | |
| Public Attributes inherited from Algorithm | |
| Signal | signalOutputChanged |
| Signal should be emitted by Algorithms when their output/result has changed. | |
| Signal | signalParametersChanged |
| Signal should be emitted by Algorithms when their parameter configuration has changed. | |
| Public Attributes inherited from Configurable | |
| Signal | signalParametersChanged |
Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted. | |
Protected Types | |
| enum class | FrameStatus { New = 0 , Duplicate = 1 , MergeFirst = 2 , MergeSecond = 3 } |
| FrameStatus specifying the status of a frame in relation to the last processed frame. | |
Protected Member Functions | |
| void | mergeFrames (int secondFrameIndex, int cutline) |
| Merges two consecutive frames at a specified horizontal cutline. | |
| FrameStatus | processImage (std::shared_ptr< const Frame > frame) const |
| Processes a single frame to determine its FrameStatus relative to the previous frame. | |
| Protected Member Functions inherited from Algorithm | |
| void | loadDefaults () |
| void | registerAction (const std::string &id, const std::string &guiName, const std::function< Algorithm::Status(void)> &action) |
| Register an action to be run via runAction. | |
| template<typename D> | |
| void | registerAction (const std::string &id, const std::string &guiName, Algorithm::Status(D::*action)(void)) |
| Template version of runAction that can be used with a pointer to a member function. | |
| void | registerAction (const Action &action) |
| Register an action. | |
Static Protected Member Functions | |
| static bool | compareImages (const Frame &img1, const Frame &img2, vec4i ®ionOut, int &maxDiffOut, double &meanDiffOut, double &propIdenticalOut) |
| Compares two frames for equality, optionally returning the region and statistics of their differences. | |
| static std::vector< vec2i > | compareFrameRegions (const Frame *img1, const Frame *img2, int diffMax, int borderSize) |
| Compares two frames in a row-by-row fashion to identify vertical regions (ranges of rows) where the frames differ, ignoring saturated pixel values. | |
| static bool | overlap (const vec4i &box1, const vec4i &box2) |
| Helper method that checks whether two bounding boxes overlap. | |
Additional Inherited Members | |
| Public Types inherited from Algorithm | |
| enum | Status { Unknown = -1 , Success = 0 , Error = 1 , InvalidInput , IncompleteInput , OutOfMemoryHost , OutOfMemoryGPU , UnsupportedGPU , UnknownAction , AbortedByUser , User = 1000 } |
| Status codes. More... | |
| Protected Attributes inherited from Algorithm | |
| std::string | m_name |
| Algorithm name. | |
| Progress * | m_progress = nullptr |
| Non-owing pointer to a progress interface. May be a nullptr. | |
| FactoryInfo | m_factoryInfo = {} |
| Record describing how this algorithm was instantiated by the AlgorithmFactory. | |
| int | m_status = Status::Unknown |
| Algorithm status after last call to compute() | |
| std::vector< Action > | m_actions |
| Map of key given by the id of the action, of the available actions of this algorithm. | |
| Protected Attributes inherited from Configurable | |
| std::vector< Param > | m_params |
| List of all registered Parameter and SubProperty instances. | |
| Protected Attributes inherited from SequentialImageProcessor | |
| bool | m_isSequentialMode = false |
| Flag to determine if algorithm is running in sequential mode. | |
|
overridevirtual |
Execute the algorithm.
Implements Algorithm.
|
overridevirtual |
Processes a single image and determines if it is a duplicate of the previous frame, using the current algorithm parameters.
Returns a shallow copy of the image and its components if it is new; otherwise, returns nullptr and an empty list.
| image | The image to process. |
| components | Associated data components for the image. |
Implements SequentialImageProcessor.
|
staticprotected |
Compares two frames for equality, optionally returning the region and statistics of their differences.
This method compares two 2D unsigned 8-bit images (frames) pixel-wise, ignoring saturated pixels (values below 5 or above 250). If the frames differ, it computes the minimal axis-aligned bounding box enclosing all differing pixels, the maximum and mean per-pixel difference, and the fraction of identical pixels.
| img1 | First image to compare (must be compatible with img2) |
| img2 | Second image to compare |
| regionOut | Bounding box (xMin, xMax, yMin, yMax) of differing region, or all zeros if identical. Input & output variable. |
| maxDiffOut | Maximum absolute difference between corresponding pixels. Input & output variable. |
| meanDiffOut | Mean absolute difference between corresponding pixels. Input & output variable. |
| propIdenticalOut | Fraction of non-saturated pixels that are identical (range: 0.0–1.0). Input & output variable. |
|
staticprotected |
Compares two frames in a row-by-row fashion to identify vertical regions (ranges of rows) where the frames differ, ignoring saturated pixel values.
Small identical regions surrounded by differences (up to borderSize lines) are merged into the surrounding different regions.
| img1 | Pointer to the first frame to compare. |
| img2 | Pointer to the second frame to compare. |
| diffMax | Maximum allowed pixel difference for a line to be considered identical. |
| borderSize | Minimum distance between two consecutive sections. |
|
staticprotected |
Helper method that checks whether two bounding boxes overlap.
| box1 | First bounding box |
| box2 | Second bounding box |
|
protected |
Merges two consecutive frames at a specified horizontal cutline.
This method copies a region of pixel data from the source frame (at index secondFrameIndex) into the destination frame (at index secondFrameIndex - 1). The cutline parameter determines the row at which the merge occurs:
cutline > 0, rows from (cutline - 1) to the bottom of the image are copied.cutline < 0, rows from the top of the image to (height + cutline) are copied. | secondFrameIndex | Index of the frame to be merged |
| cutline | Row index at which to merge the frames. Positive values count from the top, negative values count from the bottom. |
|
protected |
Processes a single frame to determine its FrameStatus relative to the previous frame.
Compares the given frame to the last processed frame to detect duplicates, horizontal tearing, or regions requiring merging. Updates internal state accordingly.
| frame | Shared pointer to the frame to process. |
| Parameter<bool> p_printOnly = {"printOnly", false, this} |
If true, only print information about duplicate frames without modifying the image set.
This parameter is ignored when using the SequentialImageProcessor interface.
| Parameter<int> p_diffMax = {"diffMax", 0, this} |
Maximum allowed absolute per-pixel difference between pixel values (of corresponding channels) for frames to be considered identical.
Pseudocode: max(abs(frame_i - frame_i+1), axis=(0, 1, 2))
| Parameter<double> p_maxIdenticalProp = {"maxIdenticalProp", 1.0, this} |
Threshold for the proportion of identical, non-saturated pixels required to consider two frames as duplicates.
If the measured proportion of identical pixels between frames exceeds this value, the frames are treated as duplicates. Only applies when p_repairHorizontalTearing is false. Threshold for the maximum proportion of identical pixels
| Parameter<int> p_borderSize = {"borderSize", 0, this} |
Number of lines at the top and bottom of the image considered as border regions.
Used to allow merging or ignoring small differences near the image edges when comparing frames. Only applies when p_repairHorizontalTearing is true.