User guide¶
FlockFlow is an offline iPhone sheep counter. It analyzes the rear camera, the bundled example sheep video, or a video selected from Photos with a bundled Core ML detector, tracks each visible sheep, and counts directional crossings.
Before you begin¶
For live counting:
- Mount the iPhone securely and keep it upright in portrait orientation.
- Keep the gate or crossing route centered in the preview.
- Make sure sheep cross the counting zone rather than walking along it.
- Avoid sudden camera movement after counting begins.
The Simulator cannot provide a rear camera. Use a physical iPhone for live counting.
Start a count¶
- Open FlockFlow. The on-device detector begins preparing in the background.
- Choose Try Example Video on Home to open the included 18-second sample immediately, or choose Start Count to open camera setup. Detection and tracking start automatically when the detector is ready; setup does not count crossings or record video.
- If you chose Start Count, keep the rear camera selected or open the video control. Choose Add videos from Photos, select one or more movies, and confirm to add them to Selected videos. This stays in the chooser without opening or analyzing a movie. Tap a thumbnail separately to use that movie and open calibration. Try Example Video is also available under More options.
- Optionally choose a pasture. Unassigned is always available.
- Draw or adjust the counting zone across the route.
- Confirm the inbound direction and choose Start Count. Camera tracking continues without restarting; crossing counts and recording begin now. Movement before this tap is not counted.
The same preview stays open through setup, calibration, and counting; Start changes the controls without reopening the camera. Camera and selected-video inputs remember separate zone placements, so switching sources does not reuse an unsuitable off-screen zone.
In setup, drag either endpoint to move it, or drag across an empty part of the preview to draw a new center line. Open Edit counting zone for Adjust (precise endpoint controls) and Flip (reverse inbound direction). Starting a count saves the placement. The zone stays locked during counting; stop the session before changing it.
Understand the live labels¶
| Label | Meaning |
|---|---|
| Tracking | The sheep is visible and has not entered a complete crossing. |
| Pending | The sheep crossed the first boundary and is moving through the zone. |
| Counted | The sheep completed a valid directional crossing. |
The displayed track ID identifies an internal track; it is not the running total. IDs can exceed the count because they also cover sheep that retreat, disappear, or are detected again.
The live FPS figure is the trailing rate of frames that completed preprocessing, on-device prediction, tracking, and counting. It is not the camera capture rate or model-only latency.
Finish and review¶
For a camera session, choose Stop. A selected video finishes automatically at the end of the file.
The summary includes:
- Inbound, outbound, and net movement
- Duration and input source
- Optional pasture association
- Model and processing details
- Session-scoped track diagnostics
FlockFlow creates a temporary annotated recording during a count. Every copy includes a clear app icon and name in the bottom-left corner. Selected-video results keep the source aspect ratio at an HD-sized resolution (up to 1280 pixels on the long edge) so on-device rendering does not waste work upscaling frames to 4K, and target the source frame cadence up to 60 fps. Copies made from selected videos retain the source audio when present; live-camera copies remain silent. The in-app result preview starts muted; choose Unmute in the preview to hear available audio and Mute to turn it off again.
Choose a Save resolution of 480p, 720p, or 1080p. The output keeps the temporary recording's aspect ratio and portrait or landscape orientation. The recording made during counting is capped at HD size, so 1080p output may be upscaled without adding image detail.
Turn on Add session details before saving if you want the pasture, completion date and time, and final total shown on the Photos copy. The preview shows the placement immediately. FlockFlow prepares any resized or details-bearing copy while you review, and Video is ready to save means preparation is complete, not that the video has been saved to Photos. Session details start turned off for every session.
Choose Save to Photos at any time: it reuses the prepared copy or waits for the current preparation rather than starting again. Source audio is retained. Changing the resolution or pasture prepares a fresh copy; selecting a resolution that already matches the temporary recording, turning details off, or leaving Summary cancels obsolete preparation and removes the extra temporary file. FlockFlow never overwrites the selected source movie.
Photos access is requested only after choosing Save. Saved to Photos appears only after the library confirms the save. If the Photos save fails, the prepared copy stays available for Retry Save without repeating the export. You can change the resolution or turn session details off before retrying.
Use diagnostics¶
Turn on diagnostics from a completed summary or saved History session to review local evidence for each track, including observed and predicted states, confidence, pending transitions, counted direction, and lost or not-counted outcomes.
- Observed means a detector result was associated with the track.
- Predicted means short-lived tracker extrapolation during a missed detection.
Older sessions created before diagnostics were available can show an empty diagnostics state.
Manage pastures¶
The Pastures tab lets you create and select an optional location for completed counts.
You can:
- Move the map to place a pasture
- Enter latitude and longitude manually
- Choose Use My Location for a one-time foreground location request
- Count without assigning a pasture
Pasture coordinates remain in the app's local storage and are not added to completed session summaries.
Choose detection settings¶
Open Model & Parameters to inspect the active model and fixed input size, or choose another bundled model. All included models are available offline in the released app. Only the selected model processes frames. Switching is available while counting is stopped; FlockFlow prepares the new model before activating it and remembers your selection.
The Settings tab provides three on-device overlap-suppression profiles:
- Fewer duplicates
- Model default
- Crowded flocks
The selected profile stays on the iPhone and applies to the next count.
Permissions¶
Camera¶
Required only for live counting. If access is denied, video counting remains available with the bundled example or through the system Photos picker.
Photos¶
The video control shows Selected videos as thumbnails with duration badges only. Add videos from Photos opens Apple's native multi-selection picker, which shares only the movies you choose without general photo-library access. Adding movies only copies them and reads their metadata; it does not switch inputs or start playback, calibration, or inference on those movies. Tap a thumbnail separately to open count setup for that video, then choose Start Count when ready.
You can add more movies later or switch between thumbnails without losing earlier selections. Photos controls browser ordering; the list keeps the returned selection order and appends later additions without sorting filenames or import timestamps. Already-added Photos identifiers are not imported again. FlockFlow stores app-owned copies and their picker identifiers privately on this iPhone, so selections return in the same order after relaunching the app. They are excluded from device backups. Choose Clear Selected Videos to delete every app-owned selected-video copy and its metadata without changing the original movies in Photos; an active selected video is unloaded and the input returns to the camera. The copies are also removed when the app is removed. A failed addition keeps successful selections, and a failed activation keeps the previous usable input. The bundled example does not use the picker. Add-only Photos permission is requested only after choosing Save to Photos.
Location¶
Optional. FlockFlow asks only after you choose Use My Location while adding a pasture, receives one usable coordinate, and then stops location updates.
Language¶
FlockFlow supports English and Simplified Chinese. It follows the iPhone language by default.
To choose a language specifically for FlockFlow, open Settings → Apps → FlockFlow → Language.
Get help¶
See Support for troubleshooting and contact options. Do not post private field recordings, coordinates, model artifacts, credentials, or signing material in a public issue.
Comments
Comments are public and powered by GitHub Discussions through Giscus.