Wildlife Mask Extractor

A simple script that finds an animal in your photos and saves cut-out / masked versions of it. It uses SAM3 (Meta's segmentation model) with a plain English text prompt — no manual clicking or bounding boxes needed.

It defaults to "arctic fox" (that's what it was originally built for), but it's not fox-specific — pass --prompt "salamander", --prompt "frog", --prompt "fox", or any other animal description, and it'll look for that instead. Try it on whatever species you're working with.

What it does

Point it at a folder of photos. For every photo where the animal is found, it saves an output image in the same folder structure, in one of three styles (you choose with --mode):

Mode	What you get
mask	Plain black & white silhouette of the animal, full image size
masked	The original photo with everything except the animal blacked out, full image size
masked-crop (default)	Same as masked, but cropped tightly around the animal

Photos where nothing is found are simply skipped — nothing is written for them. At the end you get a summary of how many photos had a match vs. not.

1. Install SAM3

SAM3 needs a GPU (NVIDIA, with CUDA) and Python 3.10+. These steps assume a Linux machine with an NVIDIA GPU and conda/miniforge already installed.

1. Create a dedicated environment:

conda create -n sam3 python=3.12 -y
conda activate sam3

2. Install PyTorch with CUDA support (check pytorch.org for the exact command matching your CUDA version — this is an example for CUDA 12.6):

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

3. Install SAM3:

pip install git+https://github.com/facebookresearch/sam3.git

4. Install the remaining small dependencies:

pip install pillow numpy tqdm huggingface_hub

5. Get access to the SAM3 model weights on Hugging Face:

The model weights (facebook/sam3) are gated — you need a (free) Hugging Face account and to accept the model's license before you can download it.

1. Create an account at huggingface.co if you don't have one.
2. Go to huggingface.co/facebook/sam3 and accept the license/terms on that page.
3. Create an access token at huggingface.co/settings/tokens (a "Read" token is enough).
4. Log in from the terminal, in the same environment:

   huggingface-cli login

   and paste the token when asked.

That's it — the first time you run the script, it will automatically download the model weights (a few GB) and cache them; every run after that reuses the cached copy.

2. Usage

Always activate the environment first:

conda activate sam3

Basic usage — cropped, masked fox images (the default):

python mask_extractor.py path/to/photos path/to/results

Get the full-size masked image instead of a crop:

python mask_extractor.py path/to/photos path/to/results --mode masked

Get just the black & white mask:

python mask_extractor.py path/to/photos path/to/results --mode mask

Use it on a different species:

python mask_extractor.py path/to/photos path/to/results --prompt "polar bear"

Optional settings

Flag	Default	What it does
--prompt	arctic fox	Plain-English description of the animal to find. Change this for any other species.
--mode	masked-crop	mask, masked, or masked-crop (see table above)
--conf	0.20	Detection confidence threshold. Lower = more (but less certain) detections.
--padding	10	Extra pixels of margin around the crop (only affects masked-crop)
--device	cuda	cuda (default GPU), cuda:N if you have multiple GPUs and want a specific one, or cpu (very slow)

Example with custom settings:

python mask_extractor.py path/to/photos path/to/results --prompt "wolf" --mode masked --conf 0.3

3. What you'll see while it runs

Loading SAM3 on cuda (120 images)...
Processing: 100%|██████████| 120/120 [02:00<00:00, 1.0it/s]

=== Summary ===
Prompt:           'arctic fox'
Total images:     120
Found:            47
Not found:        73
Errors:           0
Time:             120s (1.0s/image)
Output folder:    /path/to/results

Troubleshooting

• "CUDA out of memory": another program may be using the GPU. Try --device cuda:1 if you have a second GPU, or ask whoever manages the machine what else is running.
• Model download fails / 401/403 error: you likely haven't accepted the license on the facebook/sam3 page, or aren't logged in (huggingface-cli login).
• Very slow / running on CPU: check nvidia-smi shows a GPU, and that --device is set to cuda (not cpu).