Projects

When opening ThruTracker, you are prompted to create or open an existing project.

Project Creation

When working with a video set that has not yet been processed, select New Project on the welcome dialog when launching ThruTracker. If the dialog has been closed, you can create a new project by going to File in the top menu and selecting New Project.

Give your project a unique name that is easy to distinguish from other projects or runs. You can also specify a location where the new project folder will be saved. We recommend creating a dedicated folder within your existing video project directory to keep processing runs organized, particularly if videos will be processed across multiple runs.

Adding Videos to Projects

After entering a project name and selecting a file location, click OK to proceed to video selection. You can either copy videos directly into the project folder — which creates duplicates of the original files — or reference them in place, which links to the original files without modifying them. Additional videos can be added at any time by going to File in the top menu and selecting Add Videos.

Opening Projects

When working with an existing project, select Open Project on the welcome dialog when launching ThruTracker. If the dialog has been closed, you can open an existing project by going to File in the top menu and selecting Open Project.

The most frequently used files and folders are accessible directly within the application via buttons that open their respective locations after processing. For a full breakdown of the folders a project creates, see the Project File Structure appendix.

Detection Settings

The Detection Settings tab is where you can view videos included in your project and configure the settings ThruTracker uses to automatically detect and count targets.

Video Viewing

The main panel on the left in Detection Settings is the view window, where you can watch the selected video. You can adjust the playback speed (the default is 100%), loop the video for continuous replay, or jump to a specific frame. Use the zoom buttons to zoom in, zoom out, or fit the video to the screen. When zoomed in, click and drag with the left mouse button to pan around the image. Press the Play button or Space to play or pause the video. To step through frames one at a time, use the left/right arrow buttons or press the left/right arrow keys after clicking the timeline.

Basic Processing Guide

1. Video Selection

After adding videos to your project, use the Select Video dropdown to switch between them.

Configuration

A configuration is a saved settings file (a .yaml file in the project's config folder) holding the detection settings for a video or project. A default configuration is generated when a new project is created. Settings can be adjusted between videos, but changes are not saved unless separate settings files are created.

• Create one configuration per camera view. If your project includes videos with different camera views that need different detection settings, create a separate configuration for each view: click New, enter a name that clearly associates it with its video, and click OK to save.
• Switch and import. Use the dropdown to switch between configurations, or import configurations from other runs in the project.
• Edit is only needed when a settings file has been modified outside the application and needs to be reloaded.

Each time you switch your active video, select the matching configuration — this keeps video-specific settings from being overwritten by a single file shared across all videos in the project.

2. Target Diameter

When Target Diameter is selected, you can specify a diameter in pixels and left-click on the video to see a visual reference of a target at that size. If targets vary slightly in size but fall within a close range, choose a diameter toward the smaller end. If you are getting multiple detections on a single target (for example, one on each wing and one on the body), try increasing the target diameter or enabling Multiple Sizes. If real detections are being missed, try decreasing the diameter before adjusting sensitivity or max density.

If your targets form distinct clusters of large and small detections, or change size on screen (such as when flying toward the camera), enable Multiple Sizes. The single diameter field becomes a minimum diameter (for the smallest targets) and a maximum diameter (for the largest). Left-clicking the video with Multiple Sizes enabled shows the minimum diameter as a green circle and the maximum as a blue circle.

3. Sensitivity

Sensitivity controls how prominent targets must be against the background — specifically, the brightness contrast between a detection and its surrounding area. The scale ranges from 1 to 7:

• 1 — For very faint detections. May produce false detections or split tracks.
• 4 — The default. Suitable for the majority of runs.
• 7 — For detections with very high contrast to the background. May cause some detections to be missed.

If a test run shows too few detections and adjusting target diameter did not help, try lowering the sensitivity (1–3). If there are too many detections and adjusting target diameter did not help, try increasing the sensitivity (5–7).

Suppress Background filters out noise from parts of the scene that aren't moving. It is enabled by default and works best for stable footage from fixed cameras or scenes with consistent backgrounds. Consider disabling it if the camera is moving, the background is changing rapidly (such as clouds or fast lighting transitions), or if faint detections appear to be suppressed by the filter. This should be treated as a last resort — adjust target diameter, sensitivity, and max density first. Disabling suppress background may increase false noise detections. Note that this setting is automatically turned off when Max Density is set to its highest level (20+ Extreme).

4. Target Polarity

Target polarity defines the brightness of targets relative to the background.

• Lighter target on dark background — Select when targets are brighter than the background.
• Darker target on light background — Select when targets are darker than the background.
• Both lighter and darker — Select when the background is dynamic and targets may appear either brighter or darker.

5. Max Density

Max density represents the peak number of targets visible in a single frame.

• 1–5 animals per frame — For sparse, occasional targets.
• 6–20 animals per frame — For many targets visible at once.

Both settings automatically filter out noise and are recommended for most videos. For extremely dense footage, 20+ animals per frame (Extreme) is available. This mode trades noise filtering for the ability to handle very dense groups — it turns off Suppress Background and may increase false detections.

6. Bounding Box (Gate)

The bounding box, or gate, defines an area within the frame that ThruTracker uses to count target entries, exits, or boundary crossings. You can use a rectangle gate and specify boundary ranges from the top, bottom, left, and right edges, or draw a custom shape using the polygon tool. When drawing a gate, leave a small buffer around the edges of the area of interest. We recommend keeping the gate at least 5–10% away from any frame edge where you want to count boundary crosses — the program needs to detect a target on both the inside and outside of the gate to register a crossing.

7. Exclusion Zone (Mask)

The exclusion zone mask removes areas of the frame where you do not want detections to occur. This is useful for suppressing persistent false detections in areas such as timestamps, logos, and high-density swirling regions that generate many overlapping fragmented tracks (such as the mouth of a cave or building entrance). To draw a mask, set the brush size in pixels, click Paint to draw, and use Erase to refine edges. Click Finish when done. To remove all masks, click Clear Exclusion Mask.

Advanced Processing Guide

Advanced settings are used after finding the best-performing basic settings and are intended to further refine and isolate tracks.

8. Exclusion Size

Set the minimum detection diameter and check Filter detections smaller than this to remove detections below that threshold. Setting this a few pixels smaller than your smallest expected target provides a useful buffer. This is helpful when small noise detections — such as bugs or dust — persist after optimizing basic settings, or when you want to exclude distant, low-resolution detections in favor of close, clearly visible targets.

9. Exclusion Brightness

Exclusion brightness removes detections that fall below a minimum brightness threshold. This is particularly useful when counting exits from a thermal video in white-hot mode, where exiting targets are typically hotter and brighter than fly-bys or targets in open flight. Use Pick from Frame to sample the average brightness at a location in the video — zooming in first using the + button or Ctrl/Cmd + scroll wheel will improve precision. Set the slider to zero to disable this filter. Exclusion brightness can also reduce false detections on darker wing tips by focusing on high-temperature body detections.

10. Variable Size Tracking

Enable Variable Size Tracking (on by default) when detections gradually increase or decrease in size and are not distinct size clusters. Disable it if tracks are incorrectly joining or jumping between nearby detections.

11. Target Speed

Target speed tells ThruTracker how far a target can move between frames and still be treated as the same track.

• Default (3) — Suitable for most targets.
• Increase (4–5) — Use if fast-moving targets are being split into multiple tracks, after first checking target diameter, sensitivity, and max density.
• Decrease (2) — Use for very dense, slow-moving groups where tracks are jumping between nearby detections (extreme cases only).

Testing Current Settings

To evaluate your settings, navigate to a start frame with representative activity, specify the number of frames to test (default: 60), and click Test Current Settings. This plays a clip from the start frame with the gate overlay, frame number, and an in-frame track counter — note that this counts tracks currently visible in the frame, not cumulative tracks across the entire clip. You can adjust the playback speed for review (default: 50%). Enabling Bg_sub switches to a high-contrast view that makes faint detections easier to see.

You can adjust settings while the test clip is open, though clicking Exit Test Clip is recommended before redrawing the gate or editing masks. To undo all changes made in the current session, click Discard. Once the results look good, click Save and Advanced to proceed to full video processing.

Video Processing

Process Single Video

Before processing, confirm that the correct video and configuration file are selected. Click Process Single Video to generate tracks for one video in the project.

Process Multiple Videos

To process multiple videos in a single project using the same configuration, confirm that the correct configuration and all intended videos are selected before processing. Click Process Multiple Videos to begin.

Make Review Video From Last Run

To generate a custom review video without reprocessing the dataset, click Make Review Video From Last Run.

Configure Run Outputs

When processing a video or creating a review video, the Configure Run Outputs dialog opens.

• Track Overlay draws a colored box over each unique detection. A trail follows each detection, showing its trajectory from past frames as a series of circles. You can specify the number of circles per trail and the line thickness in pixels for both the trails and boxes.
• Gate Overlay Video produces a full processed video displaying gate counts, including exits, entries, and boundary crosses.
• Tracks-Only Video trims frames with no activity and adds a buffer before and after each track segment (default: 0.10 seconds).
• Colorize Output applies a color scheme to the review video for easier identification of individual target IDs:
  • None (original) — Uses the standard color scheme of the recorded video.
  • Inferno — Blue, purple, orange, and yellow from cold to hot.
  • Hot (Iron) — Dark red to bright yellow from cold to hot.
  • Turbo — Blue, green, yellow, and red from cold to hot.
  • Greyscale — Black to white from cold to hot.

Tracking Review

Tracking Review is where you assess the quality of your detections and view the timeline of gate exits over the duration of the entire video. Review moments of interest to confirm that processing accurately identified your targets before deciding whether settings need adjustment for a rerun.

Selecting a Review Video

After processing your video, go to the Tracking Review tab and select the video you want to use to evaluate detection quality. Use the dropdown or browse to the overlay video folder to choose a review video.

Reviewing Detection Quality

Use the review video to confirm that:

• Targets of interest are being consistently detected.
• Individual tracks are maintained without track jumping or splitting.
• Each target is assigned a single track, with no duplicates.
• No real targets are being missed.

Emergence-Rate Graph

The emergence-rate graph displays the gate exit timeline across the full video, showing the number of exits per frame and the cumulative track count over time. Review the graph to confirm that the rate and pattern of exits match your expectations.

Classify Tracks

The Classify Tracks tab allows for additional track review and enables you to assign identification categories to tracks based on your project's requirements.

Track Review

Use the tools in the top menu to view and classify tracks.

1. Load Tracks

Select Load Tracks to review one track at a time. Navigate between tracks using the Previous/Next buttons or the left/right arrow keys. This mode is recommended for lower-volume videos and allows you to classify each track individually.

2. View All Tracks

Select View All Tracks to display all tracks simultaneously, along with options for selecting multiple tracks at once. This mode is best suited for moderate- to high-volume videos, or videos with a clearly defined exit of interest to separate from other tracks.

Classification Categories

Category	Description
Star	A high-interest or high-quality track
Good	A good-quality track
Bad	Poor tracking, or a track generated from a false detection
Uncertain	Used when a complete single-detection track is difficult to distinguish from surrounding tracks; most common in high-volume, dense, or overlapping video
1 — Exit	A detection exiting a roost
2 — Entry	A detection entering a roost
3 — Fly-by	A detection flying across a roost or area of interest
4–9 (Unlabeled)	Custom categories you can define for your project (e.g., turns, conspecific interactions, investigative approaches)

Additional Tools

• Clear All — Clears the currently loaded classification in Load Tracks mode.
• Comment — Adds a comment to one or more selected tracks.
• Make Review Video (Shown Tracks) — Use the Show dropdown to select which track categories to include, then generate a review video containing only the tracks of interest.
• Edit Number Labels — Add or rename custom classifications for labels 4–9.
• Save Classifications — Saves all applied categories, labels, and track reviews.

Generate Review Images

Select Generate Review Images to create still images for each track, showing the detection highlighted within the frame across the full track duration. You can specify a maximum number of images and the frequency at which images are captured. Navigate between images using the Previous/Next buttons or the left/right arrow keys. To open previously generated images, select Open Track Images from the menu.

Frequently Asked Questions

Troubleshooting Detections and Settings

Getting your first detections, and the common problems you fix by adjusting the core settings.

1. No Detections

ThruTracker looks for things that change from frame to frame, and the target settings (Target Diameter, Contrast sensitivity, Target Polarity, Max density) tell it how. The defaults work for most videos.

• Inverted target polarity. If you've set ThruTracker to find light targets on a dark background but your bats are the opposite (or vice versa), your targets of interest get filtered out and nothing is detected. Switch the Light/Dark setting — or pick "Both" if you're unsure.
• Target size too small. Size the Target Diameter circle to enclose the bat's brightest body. If larger bats are missed, increase the target diameter value (ThruTracker tolerates targets a little smaller than expected better than larger ones).
• Bats too faint (low contrast). A low-contrast bat blends into its background — a similar temperature in thermal video, or a similar color/brightness in regular video — so it barely stands out even as it moves. If the default Contrast sensitivity is too strict to catch them, set it toward 1 (the "Maximum" end) so fainter targets register.

2. Multiple Detections per Bat

ThruTracker marks each spot that stands out as its own target — and a bat's wings can stand out separately from its body. So if the expected target size is too small to cover the whole bat, you get one detection on the body plus extra ones on the wings, instead of a single box on the bat.

• Increase the target size (and consider Multiple sizes). Make the Target Diameter big enough to cover the whole bat, so the body and wing spots merge into one detection. If your bats appear at very different sizes in the video, turn on Multiple sizes under Target Diameter and set the largest with the blue Max diameter circle.
• Turn on Variable Size Tracking. This tells ThruTracker that a bat's bounding box is allowed to grow and shrink to match its actual size. It's especially helpful when bats are viewed from above or below, where the wingbeat cycle changes the apparent size dramatically — particularly large, broad-winged fruit bats.
• As a last resort, raise Exclusion Brightness. Wing detections tend to be cooler (dimmer) than the body, so a brightness floor can drop them — but try the size adjustments first.

3. False Detections

Because ThruTracker keys on things that move and stand out, anything else that does the same can look like a bat — foliage, insects, clouds, water ripples, even a bat's own reflection or shadow. These fixes help it tell that clutter apart from real bats.

• Start with the core settings. Get Target Diameter, Contrast sensitivity, and Max density dialed in first.
• Mask static noise (Exclusion Zone). If the noise sits in a fixed spot that isn't near anything important (e.g., away from the gate crossing), paint over it with the Exclusion Zone so it's ignored.
• Turn on the Exclusion Size filter. Great for insects and video static — it drops detections smaller than a real bat. Size the orange circle to your smallest true bat.
• Use Exclusion Brightness. Great for false detections that stand out less than your bats (lower contrast — e.g. cooler than the body in thermal); a brightness floor drops them.
• Keep people out of frame. Someone walking in front of the camera throws huge false detections. We're working on code to filter these "sasquatches" automatically; for now, prevent it at capture — and note ThruTracker may warn you that part of the video has suspicious detections.

4. Detections but No Gate Counts

Counting is a separate step from detecting: ThruTracker only counts a bat when its track crosses the gate — passing from one side of the line to the other. So you can get plenty of detections but a count of zero when bats never actually cross the gate, or aren't tracked on both sides of it.

• Gate isn't across the flight path. A bat is only counted when it crosses the gate, so the gate has to sit across the bats' direction of travel (perpendicular to how they fly). If it runs along the flight path instead, bats fly parallel to it and never cross — lots of detections, no counts. Reorient the gate so it cuts across the flight.
• Gate touching the frame edge. A crossing only counts if the bat is tracked on both sides of the line. If the gate touches the edge of the frame, bats that leave right where the gate meets the edge are never seen on the far side, so they go uncounted. Pull the gate in from the edges so there's room on both sides.

5. Finding the Action in Long, Low-Activity Recordings

These are the long recordings where bats only show up in short bursts, with a lot of empty video before and after. Scrolling through all of it to find the action is tedious and time-consuming, so let ThruTracker point you to the activity instead:

1. Start from default settings, but set the polarity and draw a rough, generous gate.
2. Run a test over a large chunk of the video (not tracks-only).
3. Open the activity rate graph on the Tracking Review tab and scroll to a peak.
4. See how the detections are performing there, and iterate as usual.
5. Alternatively, run a test over a large chunk of the video (tracks-only) to create a composite of only periods where bats are detected on screen.

Fast, Blurry, Low-Contrast Bats

Some clips are hard because the bats move fast and barely register. Here's what's going on, and how to set ThruTracker up for it.

When this is your problem

The bats are easy to follow while the video plays. Pause and step through it frame by frame, though, and they nearly disappear. Each one is a faint comet or streak of light instead of a clear shape. Your eye is using the motion to find them, and a single still doesn't give it much to work with.

Why it happens

A video frame isn't a frozen instant. It's a short exposure, a small slice of time. A bat that barely moves during that slice puts all of its light on one spot, so it looks bright and sharp. A bat that's moving spreads that same light along its path, so any one point is only a little brighter than the background. It's the streak a moving car leaves in a long-exposure photo. A fast bat is the extreme version, smeared into a faint comet. The faster it goes, the less it stands out in any single frame.

Fixing it comes with a trade-off. To pick up faint bats you turn detection sensitivity way up, and that also lets in more noise. The fast/blurry settings handle both sides. They find faint targets that jump further between frames, and they clean up the noise that high sensitivity brings in.

Setting it up

1. Load your video and the fast/blurry settings file.
2. Set your core target settings for the clip: light or dark, number of bats (this workflow is for under about 20 per frame), and size. For size, match the width of the comet, the short way across the streak, not its length.
3. Draw the gate somewhere with good contrast and little noise.
4. Run a test and watch the result.
5. If noise turns up, clean it with the exclusion filters: size first, then brightness, then mask off any stationary junk away from the gate. The False Detections guide covers what each one does. Re-run and adjust until it looks right.

Reflections Over Water

When bats fly low over water, the surface mirrors them, and ThruTracker can read the reflection as a second bat. Here's how to keep the real bats and drop the reflections.

When this is your problem

Bats are flying low over calm water, and you're getting close to double the detections you should: a real bat up top and a mirrored one on the water below it.

Why it happens

Calm water acts like a mirror. Each bat casts a reflection below the waterline that moves just like the real one, so ThruTracker picks it up as its own target.

Setting it up

Reflections give you two things to work with: where they are (down on the water, below the bats) and how bright they are (dimmer than the real bat).

1. Load your video and the water-reflections settings file.
2. Mask the water (Exclusion Zone). If the camera is angled so the bats stay above the water surface, paint over the water and the reflections there are ignored. This only works when the bats and their reflections land in different parts of the frame. If the angle stacks them on top of each other, a mask would drop real bats too, so lean on brightness instead.
3. Brightness exclusion. A reflection is a dimmer copy of the bat, so set a brightness floor to drop the faint reflections and keep the brighter real bats.
4. Set your core target settings (light or dark, size, number of bats), and draw the gate above the waterline so only real bats crossing it count.
5. Run a test and review.

---

Roost Types – Challenges and Examples

Working through how to count different roost types — what's unique about each, the field decisions (camera placement), and the analysis decisions (gating + settings). Every roost type has its own quirks. This page works through them one at a time, split into the two places decisions get made: out in the field when you place the camera, and later in ThruTracker when you set the gate and detection settings.

Bat Condos / Boxes on a Pole

What it is. A bat box or multi-chamber "condo" on a pole. Bats emerge from openings at the bottom and drop out into the open.

What's unique

• Usually one of the cleaner setups. The camera looks up at the box against open sky, so bats stand out at high contrast.
• The exit is small and predictable — one known opening — so the action is concentrated in a small part of the frame.
• The pole and box are fixed structures, easy to mask or keep the gate clear of.

In the field (camera placement)

• Put the camera below or to the side, looking up at the bottom opening against open sky. That's your cleanest, highest-contrast background.
• Frame the opening and the drop-out path with room around them. Don't let the exit sit right at the edge of the frame.
• Set the distance or zoom so a single bat is a reasonable size on screen, while still having sufficient buffer around the roost.

In analysis (gating + settings)

• Gate: just below the opening, across the drop-out path, draw the gate sufficiently above the area where bats exit.
• Core settings: light/dark to match, size to a single bat, density to match the emergence.
• Use exclusion size filters to ignore smaller free-flying bats in the distance.

Buildings

What it is. Bats emerging from a large structure — a building or barn. Often you don't know exactly where the exits are, and the structure can sit warmer or cooler than the bats depending on its material, the weather, and the time of night.

What's unique

• You often don't know where the bats will come out. A building has lots of possible gaps, vents, and eaves, and the exit may not be obvious until you watch the emergence.
• Hot or cold is ambiguous. The wall and the bats can be almost any temperature relative to each other, and it can flip over the night — a sun-baked wall can read warmer than the bats early on, then cooler once it cools off.
• The background is the structure itself — bricks, siding, windows, vents — so it's busy and uneven, not clean sky.

In the field (camera placement)

• Capture the whole likely exit area. Since you may not know the exact exit, frame broadly enough to catch wherever the bats come out, with the most uniform stretch of wall you can manage behind them.
• Shooting thermal, mind the wall's heat: a shaded wall and a sun-baked wall give very different contrast.

In analysis (gating + settings)

• Start with a big gate. Because you don't know where the bats exit, draw a very large rectangle over the whole likely exit area to start. Do a default run with it to find where the activity is (see Finding the action in long, low-activity recordings), then tighten the gate onto the real exit once you've spotted it.
• Light or dark: check a few frames first — are the bats brighter or darker than the wall? If the contrast flips partway through (wall cooling off), try "Both."

Related guides. Finding the action in long, low-activity recordings (for the scouting run).

Cave Entrances – Camera Close to Bats

What it is. A cave or rock opening, usually filmed with the camera up close to the exit.

What's unique

• The camera is often right up close to the exit, so the entrance fills much of the frame.
• Bats swarm and circle at the entrance and re-enter the cave, crossing back and forth — so careful gating is what keeps that from inflating the count.

In the field (camera placement)

• Get the whole exit in frame with a little room around it. Ideally the bats move perpendicular to the camera — exiting left or right across the frame.
• Favor a clean rock backdrop over foliage where you can — bats are easier to pick out against the thermal profile of rock.

In analysis (gating + settings)

• Gating is essential for a proper count — you can't just count the tracks. The swirling and re-entering before emergence generate far more tracks than there are bats actually leaving, so a raw track count would be badly inflated. The gate counts true crossings instead. Place it outside the swirling zone so looping bats mostly don't get counted at all. (A looping bat that does cross gets both an exit and an entry, so it cancels out of the net count.)
• When you draw the gate, also favor the areas with the best contrast, so detections and counts come out cleanest.

Related guides. Detections but No Gate Counts (gate placement); fast/blurry bats, since cave bats can be fast and blurry.

Large Cave Entrances

What it is. A big cave mouth or large rock opening, filmed from far enough back to fit the whole entrance in frame. Because the opening is so large, the bats end up tiny and often faint on screen, and there's usually a lot of them moving at once. Typical of Mexican free-tailed bat and Grey bat colonies.

What's unique

• The bats are small and low-contrast. The camera is far from a big opening, so each bat is only a few pixels and can be faint — easy to miss, and easy to mistake for noise.
• Lots of activity. Large entrances move big numbers, so the frame can get crowded with overlapping bats.

In the field (camera placement)

• Get the whole entrance in frame, but no further back than you have to — every extra bit of distance shrinks the bats and makes them fainter.
• Favor a clean, uniform backdrop (rock) where you can; slight foliage movement is more likely to create false detections.
• Ideally the bats move perpendicular to the camera, crossing the frame, so the gate has a clear flow to count.

In analysis (gating + settings)

• Try it first without the 20+ animals (Extreme density) filter. The heavy activity makes it tempting to reach for, but it can generate a lot of false detections.
• May need to bump up the sensitivity.
• Depending on the distance, the exclusion size and brightness won't be useful filters (valid detections are both small and dim).

Related guides. fast/blurry bats (the bats are small and faint); Detections but No Gate Counts (gate placement).

Appendix: Project File Structure

When a project is created, ThruTracker generates a folder in the designated location containing the following subfolders:

• config — Contains the project's saved settings files.
• logs — Contains a history of runs and the settings used for each.
• outputs
  • detections — Contains detection CSVs.
  • figures — Contains graphics of emergence counts.
  • overlay_videos — Contains processed gate count videos and any additional review video outputs.
  • review_clips — Contains short review videos ~15s to be used for manually vetting counts.
  • suspicious — Contains videos with unusually high activity that might be a person crossing the field of view or camera shake.
  • review_images — Contains processed video review images.
  • tracks — Contains track data CSVs.

The most frequently used files and folders are accessible directly within the application via buttons that open their respective locations after processing.