diff options
Diffstat (limited to 'source/blender/blenkernel/BKE_tracking.h')
-rw-r--r-- | source/blender/blenkernel/BKE_tracking.h | 267 |
1 files changed, 260 insertions, 7 deletions
diff --git a/source/blender/blenkernel/BKE_tracking.h b/source/blender/blenkernel/BKE_tracking.h index 47145a7d6bd..9caf5d31765 100644 --- a/source/blender/blenkernel/BKE_tracking.h +++ b/source/blender/blenkernel/BKE_tracking.h @@ -46,20 +46,53 @@ struct rcti; /* **** Common functions **** */ +/** + * Free tracking structure, only frees structure contents + * (if structure is allocated in heap, it shall be handled outside). + * + * All the pointers inside structure becomes invalid after this call. + */ void BKE_tracking_free(struct MovieTracking *tracking); +/** + * Copy tracking structure content. + */ void BKE_tracking_copy(struct MovieTracking *tracking_dst, const struct MovieTracking *tracking_src, const int flag); +/** + * Initialize motion tracking settings to default values, + * used when new movie clip data-block is created. + */ void BKE_tracking_settings_init(struct MovieTracking *tracking); +/** + * Get list base of active object's tracks. + */ struct ListBase *BKE_tracking_get_active_tracks(struct MovieTracking *tracking); +/** + * Get list base of active object's plane tracks. + */ struct ListBase *BKE_tracking_get_active_plane_tracks(struct MovieTracking *tracking); +/** + * Get reconstruction data of active object. + */ struct MovieTrackingReconstruction *BKE_tracking_get_active_reconstruction( struct MovieTracking *tracking); -/* matrices for constraints and drawing */ +/* Matrices for constraints and drawing. */ + +/** + * Get transformation matrix for a given object which is used + * for parenting motion tracker reconstruction to 3D world. + */ void BKE_tracking_get_camera_object_matrix(struct Object *camera_object, float mat[4][4]); +/** + * Get projection matrix for camera specified by given tracking object + * and frame number. + * + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking, struct MovieTrackingObject *object, int framenr, @@ -68,16 +101,45 @@ void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking, float mat[4][4]); /* **** Clipboard **** */ +/** + * Free clipboard by freeing memory used by all tracks in it. + */ void BKE_tracking_clipboard_free(void); +/** + * Copy selected tracks from specified object to the clipboard. + */ void BKE_tracking_clipboard_copy_tracks(struct MovieTracking *tracking, struct MovieTrackingObject *object); +/** + * Check whether there are any tracks in the clipboard. + */ bool BKE_tracking_clipboard_has_tracks(void); +/** + * Paste tracks from clipboard to specified object. + * + * Names of new tracks in object are guaranteed to be unique here. + */ void BKE_tracking_clipboard_paste_tracks(struct MovieTracking *tracking, struct MovieTrackingObject *object); /* **** Track **** */ + +/** + * Add new empty track to the given list of tracks. + * + * It is required that caller will append at least one marker to avoid degenerate tracks. + */ struct MovieTrackingTrack *BKE_tracking_track_add_empty(struct MovieTracking *tracking, struct ListBase *tracks_list); +/** + * Add new track to a specified tracks base. + * + * Coordinates are expected to be in normalized 0..1 space, + * frame number is expected to be in clip space. + * + * Width and height are clip's dimension used to scale track's + * pattern and search regions. + */ struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking, struct ListBase *tracksbase, float x, @@ -85,14 +147,35 @@ struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking int framenr, int width, int height); +/** + * Duplicate the specified track, result will no belong to any list. + */ struct MovieTrackingTrack *BKE_tracking_track_duplicate(struct MovieTrackingTrack *track); +/** + * Ensure specified track has got unique name, + * if it's not name of specified track will be changed + * keeping names of all other tracks unchanged. + */ void BKE_tracking_track_unique_name(struct ListBase *tracksbase, struct MovieTrackingTrack *track); +/** + * Free specified track, only frees contents of a structure + * (if track is allocated in heap, it shall be handled outside). + * + * All the pointers inside track becomes invalid after this call. + */ void BKE_tracking_track_free(struct MovieTrackingTrack *track); +/** + * Get frame numbers of the very first and last markers. + * There is no check on whether the marker is enabled or not. + */ void BKE_tracking_track_first_last_frame_get(const struct MovieTrackingTrack *track, int *r_first_frame, int *r_last_frame); +/** + * Find the minimum starting frame and maximum ending frame within given set of tracks. + */ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingTrack **tracks, const int num_tracks, int *r_first_frame, @@ -101,17 +184,50 @@ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingT int BKE_tracking_count_selected_tracks_in_list(const struct ListBase *tracks_list); int BKE_tracking_count_selected_tracks_in_active_object(/*const*/ struct MovieTracking *tracking); -/* Get array of selected tracks from the current active object in the tracking structure. - * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0. */ +/** + * Get array of selected tracks from the current active object in the tracking structure. + * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0. + */ struct MovieTrackingTrack **BKE_tracking_selected_tracks_in_active_object( struct MovieTracking *tracking, int *r_num_tracks); +/** + * Set flag for all specified track's areas. + * + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + * \param flag: flag to be set for areas. + */ void BKE_tracking_track_flag_set(struct MovieTrackingTrack *track, int area, int flag); +/** + * Clear flag from all specified track's areas. + * + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + * \param flag: flag to be cleared for areas. + */ void BKE_tracking_track_flag_clear(struct MovieTrackingTrack *track, int area, int flag); +/** + * Check whether track has got marker at specified frame. + * + * \note frame number should be in clip space, not scene space. + */ bool BKE_tracking_track_has_marker_at_frame(struct MovieTrackingTrack *track, int framenr); +/** + * Check whether track has got enabled marker at specified frame. + * + * \note frame number should be in clip space, not scene space. + */ bool BKE_tracking_track_has_enabled_marker_at_frame(struct MovieTrackingTrack *track, int framenr); +/** + * Clear track's path: + * + * - If action is #TRACK_CLEAR_REMAINED path from `ref_frame+1` up to end will be clear. + * - If action is #TRACK_CLEAR_UPTO path from the beginning up to `ref_frame-1` will be clear. + * - If action is #TRACK_CLEAR_ALL only marker at frame ref_frame will remain. + * + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_track_path_clear(struct MovieTrackingTrack *track, int ref_frame, int action); void BKE_tracking_tracks_join(struct MovieTracking *tracking, @@ -140,7 +256,11 @@ float BKE_tracking_track_get_weight_for_marker(struct MovieClip *clip, struct MovieTrackingTrack *track, struct MovieTrackingMarker *marker); -/* selection */ +/* Selection */ + +/** + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + */ void BKE_tracking_track_select(struct ListBase *tracksbase, struct MovieTrackingTrack *track, int area, @@ -155,19 +275,31 @@ void BKE_tracking_marker_delete(struct MovieTrackingTrack *track, int framenr); void BKE_tracking_marker_clamp(struct MovieTrackingMarker *marker, int event); +/** + * Get marker closest to the given frame number. + * + * If there is maker with exact frame number it returned. + * Otherwise, marker with highest frame number but lower than the requested + * frame is returned if such marker exists. Otherwise, the marker with lowest + * frame number greater than the requested frame number is returned. + * + * This function has complexity of `O(log number_of_markers)`. + */ struct MovieTrackingMarker *BKE_tracking_marker_get(struct MovieTrackingTrack *track, int framenr); struct MovieTrackingMarker *BKE_tracking_marker_get_exact(struct MovieTrackingTrack *track, int framenr); struct MovieTrackingMarker *BKE_tracking_marker_ensure(struct MovieTrackingTrack *track, int framenr); -/* Get marker position, possibly interpolating gap between key-framed/tracked markers. +/** + * Get marker position, possibly interpolating gap between key-framed/tracked markers. * * The result marker frame number is set to the requested frame number. Its flags are 0 if the * marker is interpolated, and is set to original marker flag if there were no interpolation * involved. * - * Returns truth if the result is usable. */ + * \returns truth if the result is usable. + */ bool BKE_tracking_marker_get_interpolated(struct MovieTrackingTrack *track, const int framenr, struct MovieTrackingMarker *r_marker); @@ -181,12 +313,21 @@ void BKE_tracking_marker_get_subframe_position(struct MovieTrackingTrack *track, float pos[2]); /* **** Plane Track **** */ +/** + * Creates new plane track out of selected point tracks. + */ struct MovieTrackingPlaneTrack *BKE_tracking_plane_track_add(struct MovieTracking *tracking, struct ListBase *plane_tracks_base, struct ListBase *tracks, int framenr); void BKE_tracking_plane_track_unique_name(struct ListBase *plane_tracks_base, struct MovieTrackingPlaneTrack *plane_track); +/** + * Free specified plane track, only frees contents of a structure + * (if track is allocated in heap, it shall be handled outside). + * + * All the pointers inside track becomes invalid after this call. + */ void BKE_tracking_plane_track_free(struct MovieTrackingPlaneTrack *plane_track); bool BKE_tracking_plane_track_has_marker_at_frame(struct MovieTrackingPlaneTrack *plane_track, @@ -222,10 +363,21 @@ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_insert( struct MovieTrackingPlaneTrack *plane_track, struct MovieTrackingPlaneMarker *plane_marker); void BKE_tracking_plane_marker_delete(struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Get a plane marker at given frame, + * If there's no such marker, closest one from the left side will be returned. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get( struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Get a plane marker at exact given frame, if there's no marker at the frame, + * NULL will be returned. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get_exact( struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Ensure there's a marker for the given frame. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_ensure( struct MovieTrackingPlaneTrack *plane_track, int framenr); void BKE_tracking_plane_marker_get_subframe_corners(struct MovieTrackingPlaneTrack *plane_track, @@ -255,6 +407,9 @@ struct MovieTrackingReconstruction *BKE_tracking_object_get_reconstruction( struct MovieTracking *tracking, struct MovieTrackingObject *object); /* **** Camera **** */ +/** + * Converts principal offset from center to offset of blender's camera. + */ void BKE_tracking_camera_shift_get( struct MovieTracking *tracking, int winx, int winy, float *shiftx, float *shifty); void BKE_tracking_camera_to_blender(struct MovieTracking *tracking, @@ -346,10 +501,21 @@ struct ImBuf *BKE_tracking_get_search_imbuf(struct ImBuf *ibuf, bool anchored, bool disable_channels); +/** + * Zap channels from the imbuf that are disabled by the user. this can lead to + * better tracks sometimes. however, instead of simply zeroing the channels + * out, do a partial gray-scale conversion so the display is better. + */ void BKE_tracking_disable_channels( struct ImBuf *ibuf, bool disable_red, bool disable_green, bool disable_blue, bool grayscale); /* **** 2D tracking **** */ + +/** + * Refine marker's position using previously known keyframe. + * Direction of searching for a keyframe depends on backwards flag, + * which means if backwards is false, previous keyframe will be as reference. + */ void BKE_tracking_refine_marker(struct MovieClip *clip, struct MovieTrackingTrack *track, struct MovieTrackingMarker *marker, @@ -368,6 +534,9 @@ void BKE_autotrack_context_free(struct AutoTrackContext *context); /* **** Plane tracking **** */ +/** + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_track_plane_from_existing_motion(struct MovieTrackingPlaneTrack *plane_track, int start_frame); void BKE_tracking_retrack_plane_from_existing_motion_at_segment( @@ -377,11 +546,20 @@ void BKE_tracking_homography_between_two_quads(/*const*/ float reference_corners float H[3][3]); /* **** Camera solving **** */ + +/** + * Perform early check on whether everything is fine to start reconstruction. + */ bool BKE_tracking_reconstruction_check(struct MovieTracking *tracking, struct MovieTrackingObject *object, char *error_msg, int error_size); +/** + * Create context for camera/object motion reconstruction. + * Copies all data needed for reconstruction from movie clip datablock, + * so editing this clip is safe during reconstruction job is in progress. + */ struct MovieReconstructContext *BKE_tracking_reconstruction_context_new( struct MovieClip *clip, struct MovieTrackingObject *object, @@ -389,13 +567,29 @@ struct MovieReconstructContext *BKE_tracking_reconstruction_context_new( int keyframe2, int width, int height); +/** + * Free memory used by a reconstruction process. + */ void BKE_tracking_reconstruction_context_free(struct MovieReconstructContext *context); +/** + * Solve camera/object motion and reconstruct 3D markers position + * from a prepared reconstruction context. + * + * stop is not actually used at this moment, so reconstruction + * job could not be stopped. + * + * do_update, progress and stat_message are set by reconstruction + * callback in libmv side and passing to an interface. + */ void BKE_tracking_reconstruction_solve(struct MovieReconstructContext *context, short *stop, short *do_update, float *progress, char *stats_message, int message_size); +/** + * Finish reconstruction process by copying reconstructed data to an actual movie clip data-block. + */ bool BKE_tracking_reconstruction_finish(struct MovieReconstructContext *context, struct MovieTracking *tracking); @@ -405,9 +599,16 @@ void BKE_tracking_reconstruction_report_error_message(struct MovieReconstructCon const char *BKE_tracking_reconstruction_error_message_get( const struct MovieReconstructContext *context); +/** + * Apply scale on all reconstructed cameras and bundles, used by camera scale apply operator. + */ void BKE_tracking_reconstruction_scale(struct MovieTracking *tracking, float scale[3]); /* **** Feature detection **** */ + +/** + * Detect features using FAST detector. + */ void BKE_tracking_detect_fast(struct MovieTracking *tracking, struct ListBase *tracksbase, struct ImBuf *ibuf, @@ -418,6 +619,9 @@ void BKE_tracking_detect_fast(struct MovieTracking *tracking, struct bGPDlayer *layer, bool place_outside_layer); +/** + * Detect features using Harris detector. + */ void BKE_tracking_detect_harris(struct MovieTracking *tracking, struct ListBase *tracksbase, struct ImBuf *ibuf, @@ -429,6 +633,24 @@ void BKE_tracking_detect_harris(struct MovieTracking *tracking, bool place_outside_layer); /* **** 2D stabilization **** */ + +/** + * Get stabilization data (translation, scaling and angle) for a given frame. + * Returned data describes how to compensate the detected movement, but with any + * chosen scale factor already applied and any target frame position already compensated. + * In case stabilization fails or is disabled, neutral values are returned. + * + * \param framenr: is a frame number, relative to the clip (not relative to the scene timeline). + * \param width: is an effective width of the canvas (square pixels), used to scale the + * determined translation. + * + * Outputs: + * \param translation: of the lateral shift, absolute canvas coordinates (square pixels). + * \param scale: of the scaling to apply. + * \param angle: of the rotation angle, relative to the frame center. + * + * TODO(sergey): Use `r_` prefix for output parameters here. + */ void BKE_tracking_stabilization_data_get(struct MovieClip *clip, int framenr, int width, @@ -436,12 +658,30 @@ void BKE_tracking_stabilization_data_get(struct MovieClip *clip, float translation[2], float *scale, float *angle); +/** + * Stabilize given image buffer using stabilization data for a specified frame number. + * + * \note frame number should be in clip space, not scene space. + * + * TODO(sergey): Use `r_` prefix for output parameters here. + */ struct ImBuf *BKE_tracking_stabilize_frame(struct MovieClip *clip, int framenr, struct ImBuf *ibuf, float translation[2], float *scale, float *angle); +/** + * Build a 4x4 transformation matrix based on the given 2D stabilization data. + * mat is a 4x4 matrix in homogeneous coordinates, adapted to the + * final image buffer size and compensated for pixel aspect ratio, + * ready for direct OpenGL drawing. + * + * TODO(sergey): The signature of this function should be changed. we actually + * don't need the dimensions of the image buffer. Instead we + * should consider to provide the pivot point of the rotation as a + * further stabilization data parameter. + */ void BKE_tracking_stabilization_data_to_mat4(int width, int height, float aspect, @@ -450,17 +690,30 @@ void BKE_tracking_stabilization_data_to_mat4(int width, float angle, float mat[4][4]); -/* Dopesheet */ +/* Dope-sheet */ + +/** + * Tag dope-sheet for update, actual update will happen later when it'll be actually needed. + */ void BKE_tracking_dopesheet_tag_update(struct MovieTracking *tracking); +/** + * Do dope-sheet update, if update is not needed nothing will happen. + */ void BKE_tracking_dopesheet_update(struct MovieTracking *tracking); /* **** Query/search **** */ +/** + * \note Returns NULL if the track comes from camera object,. + */ struct MovieTrackingObject *BKE_tracking_find_object_for_track( const struct MovieTracking *tracking, const struct MovieTrackingTrack *track); struct ListBase *BKE_tracking_find_tracks_list_for_track(struct MovieTracking *tracking, const struct MovieTrackingTrack *track); +/** + * \note Returns NULL if the track comes from camera object,. + */ struct MovieTrackingObject *BKE_tracking_find_object_for_plane_track( const struct MovieTracking *tracking, const struct MovieTrackingPlaneTrack *plane_track); struct ListBase *BKE_tracking_find_tracks_list_for_plane_track( |