ComfyUI Node
CoachBate H3 Subject Track + Crop
Per-frame subject track -> smoothed, normalised crop -> constant-size batch for H3, plus the transform needed to paste the result back.
CoachBate H3 Subject Track + Crop
- images
- crops
- transform
- preview
- report
- canvas_w
- canvas_h
- frame_count
◄detector▾►
◄confidence0.35►
◄crop_factor2.5►
◄canvas_width768►
◄canvas_height768►
◄canvas_modemanual►
◄smooth_window21►
◄size_smooth_window51►
◄smooth_methodgaussian►
◄size_modeper_frame►
◄selectlargest►
◄cut_detectionnone►
◄cut_threshold3.00►
◄select_index0►
◄crop_size_fromlongest_side►
◄select_override►
◄X0►
◄Y0►
◄frame_index0►
CategoryCoachBate/H3 Subject Refine
Inputs (20)
| Name | Type | Default | Description |
|---|---|---|---|
| images | IMAGE | — | |
| detector | COMBO | 1 options: face_yolov8m.pt | |
| confidence | FLOAT | 0.350.05–0.95 | — |
| crop_factor | FLOAT | 2.51.2–8 | Crop side as a multiple of the detected box (see crop_size_from). 2.5 puts the subject at ~40% of the crop, comfortably inside H3's good regime. Bigger = more context so the seam lands in hair/background, but less magnification. 2.0-3.0 is the useful range. |
| canvas_width | INT | 768128–1344 | Resolution H3 generates at. 768 is H3's native short edge and the default here; 512 is cheaper. In manual mode this is used exactly as typed, high or low. Ignored when canvas_mode is not 'manual', where the canvas comes from the crop instead and never falls below 512x512. Cost scales with area: 768 is 2.25x the latent tokens of 512. |
| canvas_height | INT | 768128–1344 | — |
| canvas_mode | COMBO | manual | manual: use canvas_width/height as given. auto_no_downscale: size the canvas from the LARGEST crop in the video so no frame is ever downscaled (magnification never drops below 1.0x). Can get expensive on videos that include close-ups. auto_capped_768: same, but clamped to 768 - H3's native short edge and a sane VRAM ceiling. Both auto modes clamp UP to a minimum of 512x512, whatever the crop, so a small subject in a low-resolution clip is still magnified. manual is not clamped - it uses canvas_width and canvas_height exactly as typed. |
| smooth_window | INT | 211–201 | Frames of smoothing on the crop CENTRE. 21 at 24fps is ~0.9s. Raise if the box still shivers; lower if it lags behind fast movement. |
| size_smooth_window | INT | 511–201 | Frames of smoothing on the crop SIZE. Wants MORE than the centre: size jitter makes the crop breathe, which changes the resample factor every frame and reads as shimmer. Real zoom moves are slow, so heavy smoothing here costs nothing. |
| smooth_method | COMBO | gaussian | gaussian: best jitter rejection. savgol: preserves the shape of a push-in better at large windows. moving_average: the old boxcar, leaves residual jitter. |
| size_mode | COMBO | per_frame | per_frame: constant subject-fraction in every crop (correct for push-ins). max_of_clip: one size for the whole video, only useful when the shot is genuinely static. |
| selectopt | COMBO | largest | How the subject is chosen. It is chosen ONCE per shot, on the first frame that holds it, and continuity follows that same subject from there - it is NOT re-ranked each frame. A subject who walks from the left of frame to the right while someone else crosses the other way is still tracked correctly. largest / smallest: biggest or smallest subject by height. left_most / right_most / top_most / bottom_most: by the CENTRE of the subject box. centre_most: nearest the centre of the frame. closest_to_xy: nearest the X, Y you give, measured on frame_index. detector_score: the detection the detector is most confident about. AT A HARD CUT a rank means nothing across the join - everyone is renumbered. With cut_detection ON, each shot chooses again by this rule, so a cut can land on a different person. With it OFF the video counts as one shot and continuity runs straight through a real cut onto whichever subject is nearest the last position, which may be any of them. |
| cut_detectionopt | COMBO | none | Hard-cut detection, so the crop is not smoothed ACROSS a cut. none: off. Correct for single-shot videos, which is what H3 generates. auto: split at the cuts and treat each shot as its own window for the smoothing, interpolation and composite fade. The canvas is still sized once for the whole video. |
| cut_thresholdopt | FLOAT | 3.000.5–20 | How far a frame has to stand out from its NEIGHBOURS to count as a cut. 3.0 is PySceneDetect's adaptive default. Lower catches more and risks splitting a continuous shot, which costs smoothing on both sides. Higher takes only unambiguous cuts. Only used when cut detection is on. The report says how many cuts were found and where, so tune it from that. |
| select_indexopt | INT | 00–63 | Which subject in that ranking to track. 0 is the first, 1 the second, and so on. The subject is locked on the first frame that actually contains this index, so a video that opens on one subject and only later shows several still finds subject 1. Frames before that lock-on are interpolated from it and faded out of the composite, the same as a detection dropout; the report counts them. Clamped, with a warning in the report, if the video never shows that many subjects at once. |
| crop_size_fromopt | COMBO | longest_side | What the crop is sized from. 'height' suits a roughly square subject (a face). 'longest_side' uses the larger of the box's smoothed height and width, so a subject lying sideways is not cut off at the sides of the crop. |
| select_overrideopt | STRING | When not empty, replaces `select`. Lets a loop drive the subject choice per round (CoachBate H3 Loop Subject). | |
| Xopt | INT | 00–16384 | Only used by select=closest_to_xy. Horizontal position in PIXELS of the source video frame, measured from the TOP-LEFT corner, increasing to the right. On a 960x544 clip, 0 is the left edge, 960 the right, 480 the middle. The point does not have to sit on a subject: the nearest subject CENTRE wins, however far away it is. |
| Yopt | INT | 00–16384 | Only used by select=closest_to_xy. Vertical position in PIXELS of the source video frame, measured from the TOP-LEFT corner, increasing DOWNWARD. On a 960x544 clip, 0 is the top edge, 544 the bottom, 272 the middle. |
| frame_indexopt | INT | 00–999999 | Only used by select=closest_to_xy. The frame the X, Y measurement is taken on, counting from 0 for the FIRST frame. It counts the frames this node loaded, so with skip_first_frames or select_every_nth set it counts from the first frame kept, not the first frame of the file. The subject found there is followed forwards and backwards through its shot, so pick a frame where the subject is clearly visible rather than one the detector may miss them on. |
Outputs (7)
| Name | Type | Description |
|---|---|---|
| crops | IMAGE | — |
| transform | H3FACEXFORM | — |
| preview | IMAGE | — |
| report | STRING | — |
| canvas_w | INT | — |
| canvas_h | INT | — |
| frame_count | INT | — |