Interface PointTracker<T extends ImageBase<T>>

All Known Implementing Classes:
PointTrackerDda, PointTrackerDefault, PointTrackerHybrid, PointTrackerKltPyramid, PointTrackerPerfectCloud

public interface PointTracker<T extends ImageBase<T>>

Interface for tracking point features in image sequences with automatic feature selection for use in Structure From Motion (SFM) application. Access is provided to the pixel location of each track. Implementation specific track information is hidden from the user.

Each track can have the following states, active, inactive, new, and dropped. An active track is one which was recently updated in the latest image, while an inactive one was not. New tracks were spawned in the most recent image. Dropped tracks are tracks which were automatically dropped in the most recent update.

TRACK MAINTENANCE: Implementations of this interface should not automatically drop tracks or perform other forms of track maintenance unless the feature is hopelessly lost and can no longer be tracked. It is the responsibility of the user to drop tracks which are inactive for an excessive amount of time. New tracks should never be spawned unless specifically requested by the user.

TRACK MEMORY: Implementations of this interface must recycle tracks. After a track has been dropped, either by the user or automatically, the reference should be saved and the user provided cookie left unmodified. When a new track is added the track information should be updated and the cookie left unmodified again. The intended purpose of this requirement is to reduce the burden of memory maintenance on the user and to encourage good memory management.

NOTE: Tracks dropped by the user will not be included in the dropped list.

  • Method Details

    • process

      void process​(T image)
      Process input image and perform tracking.
      Parameters:
      image - Next image in the sequence
    • reset

      void reset()
      Discard memory of all current and past tracks. Growing buffered might not be reset to their initial size by this method.
    • getFrameID

      long getFrameID()
      Returns the ID of the most recently processed frame. Frames start at 0 and increment by one each time process is called. After reset or before any frames have been processed -1 is returned.
    • getTotalActive

      int getTotalActive()
      Returns the total number of active tracks
    • getTotalInactive

      int getTotalInactive()
      Returns total number of inactive tracks
    • dropAllTracks

      void dropAllTracks()
      Drops all feature to be dropped and will no longer be tracked.

      NOTE: Tracks dropped using this function will not appear in the dropped list.

    • getMaxSpawn

      int getMaxSpawn()
      Returns the maximum total number of tracks that it can spawn in a single frame. This number is reduced by the number of active tracks. So if the maximum number of tracks it can spawn is 200 and 50 tracks are active then it will spawn at most 150 tracks. If there is no limit then a number ≤ 0 is returned.
    • dropTrack

      boolean dropTrack​(PointTrack track)
      Manually forces a track to be dropped. New requests to all and active lists will not include the track after it has been dropped using this function. If request is made to drop a track that is not being tracked (in the internal all list), then the request is ignored.

      NOTE: Tracks dropped using this function will not appear in the dropped list.

      Parameters:
      track - The track which is to be dropped
      Returns:
      true if the request to drop the track was done or if it was ignored because the track wasn't being tracked
    • dropTracks

      void dropTracks​(PointTracker.Dropper dropper)
      Used to drop multiple tracks using a rule. This can be more efficient than dropping them one at a time.

      NOTE: Tracks dropped using this function will not appear in the dropped list.

      Parameters:
      dropper - Rule for dropping the tracks
    • getAllTracks

      List<PointTrack> getAllTracks​(@Nullable @Nullable List<PointTrack> list)
      Returns a list of all features that are currently being tracked
      Parameters:
      list - Optional storage for the list of tracks. List is cleared before tracks are added. If null a new list will be declared internally.
      Returns:
      List of tracks.
    • getActiveTracks

      List<PointTrack> getActiveTracks​(@Nullable @Nullable List<PointTrack> list)
      Returns a list of active tracks. An active track is defined as a track which was found in the most recently processed image.
      Parameters:
      list - Optional storage for the list of tracks. List is cleared before tracks are added. If null a new list will be declared internally.
      Returns:
      List of tracks.
    • getInactiveTracks

      List<PointTrack> getInactiveTracks​(@Nullable @Nullable List<PointTrack> list)
      Returns a list of inactive tracks. A track is inactive if it is not associated with any features in the current image.
      Parameters:
      list - Optional storage for the list of tracks. List is cleared before tracks are added. If null a new list will be declared internally.
      Returns:
      List of tracks.
    • getDroppedTracks

      List<PointTrack> getDroppedTracks​(@Nullable @Nullable List<PointTrack> list)
      Returns a list of tracks dropped by the tracker during the most recent update. Tracks dropped by user request are not included in this list.
      Parameters:
      list - Optional storage for the list of tracks. List is cleared before tracks are added. If null a new list will be declared internally.
      Returns:
      List of tracks.
    • getNewTracks

      List<PointTrack> getNewTracks​(@Nullable @Nullable List<PointTrack> list)
      Returns a list of tracks that have been added since process was called.
      Parameters:
      list - Optional storage for the list of tracks. List is cleared before tracks are added. If null a new list will be declared internally.
      Returns:
      List of tracks.
    • spawnTracks

      void spawnTracks()
      Automatically selects new features in the image to track. Returned tracks must be unique and not duplicates of any existing tracks. This includes both active and inactive tracks. NOTE: This function may or may not also modify the active and inactive lists.
    • getImageType

      ImageType<T> getImageType()
      Input image type