SAM3-tutorial (Segment Everything Model 3): bouw een privacyfilter

SAM 3 is Meta’s nieuwe “segment anything”-model dat elke instantie van een concept kan vinden via korte tekstprompts of voorbeelden en pixelnauwkeurige maskers retourneert voor afbeeldingen en video. Dit maakt het perfect voor praktische privacytaken zoals het vervagen van gezichten, kentekenplaten of schermen zonder handmatig selecties te tekenen of klassieke detectors te bouwen.

In deze tutorial bouwen we in Colab een SAM3 Privacy Filter met een Gradio-UI. Upload gewoon een afbeelding of video, typ een prompt (zoals faces, license plates), en SAM3 geeft instantiemaskers terug zodat we alleen die pixels kunnen vervagen. We doorlopen de setup, maskergeneratie, het toepassen van een Gaussiaanse blur en het koppelen van de Gradio-app om de eindbestanden te exporteren.

Wat is SAM3?

Segment Anything Model 3 (SAM 3) is Meta’s uniforme model voor open-vocabulary detectie, segmentatie en tracking in afbeeldingen en video. In plaats van aparte detectors te configureren voor elke klasse, kun je werken met korte zinnen of voorbeelden, en SAM 3 retourneert per-instantie maskers.

Onder de motorkap combineert SAM 3 een tekstencoder en beeldencoder met een DETR-achtige detector en een van SAM-2 afgeleide tracker met een geheugenbank. Bij elk frame detecteert het maskers voor je concept op basis van de prompt, propageert maskers vooruit via de tracker en voegt nieuw gedetecteerde en getrackte maskers samen tot de uiteindelijke output voor dat frame. 

Bron: SAM3 GitHub

SAM 3 wordt uitgebracht met modelgewichten, fine-tuningcode en evaluatiedata, inclusief de SA-Co-benchmark voor promptbare conceptsegmentatie. 

In Meta’s rapporten laat het ~2× winst zien ten opzichte van sterke baselines voor open-vocabulary segmentatie in afbeeldingen en video, terwijl de interactieve sterke punten van SAM-2 behouden blijven. 

In deze tutorial nemen we die SAM 3-maskers en zetten we ze om in een Gaussiaans vervaagde compositie voor zowel afbeeldingen als video’s, verpakt in een Gradio-UI. 

SAM3-voorbeeld: een privacyfilter bouwen voor afbeeldingen en video’s

In deze sectie bouwen we een privacyfilter met SAM3 voor afbeeldingen en video’s, ingebed in een eenvoudige Gradio-UI.

Zo werkt het:

• Begin met het typen van een doel, bijvoorbeeld faces, license plates, computer screens, etc
• SAM3 segmenteert instanties die overeenkomen met je tekstprompt en retourneert per-objectmaskers
• Daarna verenigen we die maskers en vervagen we alleen de gemaskeerde pixels
• Vervolgens gebruiken we de Gradio-UI-component om een afbeelding of video te uploaden, de vervagingssterkte en confidence aan te passen, en daarna een preview te bekijken en resultaten te downloaden.

We doorlopen de volledige implementatie in kleine stappen.

Stap 1: Installeer dependencies

Voordat we deze demo draaien, zorgen we dat alle vereisten aanwezig zijn. Om de SAM3 Privacy Filter in Colab te gebruiken, heb je de nieuwste Transformers-bibliotheek nodig, samen met enkele runtime-bibliotheken voor UI, tensorbewerkingen, afbeeldingen en video-I/O. De snippet hieronder installeert alles in één keer.

import subprocess
import sys
import os
def install(package):
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", package])
print(" Installing latest Transformers")
install("git+https://github.com/huggingface/transformers.git")
pkgs = [
    "accelerate",
    "gradio",
    "numpy",
    "pillow",
    "torch",
    "torchvision",
    "imageio[ffmpeg]" 
]
for p in pkgs:
    install(p)Mogelijk gemaakt door

Dit doet elke vereiste:

• git+https://github.com/huggingface/transformers.git: Dit haalt de nieuwste Transformers-bibliotheek uit de bron, zodat de klassen Sam3Processor en Sam3Model beschikbaar zijn.
• torch en torchvision: Dit zijn de tensorcompute- en beeldhulpprogramma’s die de SAM3-forwardpass uitvoeren
• accelerate: De inference-helper die door Transformers wordt gebruikt.
• gradio: Een lichtgewicht web-UI om media te uploaden en vervaagde resultaten te bekijken.
• numpy, pillow: Bevatten beeld-arrays en PIL-bewerkingen voor masker/blur-compositie.
• imageio[ffmpeg]: Leest/schrijft video’s en codeert MP4 (FFmpeg) voor het videotabblad.

Zodra de omgeving is opgezet en facebook/sam3 is geladen, kun je in de demo segmenteren met korte tekstprompts en de resulterende maskers in afbeeldingen of video vervagen via een simpele Gradio-app. 

Opmerking: Als je een GPU in Colab wilt gebruiken, stel de runtime dan vooraf in op GPU (T4/A100). Ik gebruikte een A100-GPU op Colab voor een snellere ervaring.

Stap 2: Imports

Met de omgeving klaar importeer je de bibliotheken voor de UI, modelinference, beeld-/videohandling en timing. Dit zijn de enige modules die je nodig hebt voor de SAM3-privacyfilter.

import gradio as gr
import torch
import numpy as np
import imageio
from PIL import Image, ImageFilter
from transformers import Sam3Processor, Sam3Model
import timeMogelijk gemaakt door

Nu levert Gradio de webinterface, de transformers-bibliotheek draait SAM3, en PyTorch voert inference uit op GPU of CPU. Terwijl PIL afbeeldingen laadt en bewerkt (inclusief Gaussiaanse blur), beheert NumPy de maskerarrays en leest en schrijft imageio videobestanden.

Vervolgens laden we het model en bouwen we een kleine engine die tekstprompts omzet in maskers die je kunt vervagen.

Stap 3: SAM3 laden en maskers voorspellen

Nu de omgeving klaar is, wikkelen we SAM3 in een kleine engine die het model één keer laadt, op aanvraag tekstgestuurde instantiesegmentatie uitvoert en binaire maskers retourneert die worden gebruikt voor vervaging.

class Sam3PrivacyEngine:
    def __init__(self):
        self.device = "cuda" if torch.cuda.is_available() else "cpu"
        self.model = None
        self.processor = None
        print(f"Initializing SAM3 on {self.device}")
        try:
            self.model = Sam3Model.from_pretrained("facebook/sam3").to(self.device)
            self.processor = Sam3Processor.from_pretrained("facebook/sam3")
            print("SAM3 Loaded Successfully!")
        except Exception as e:
            print(f"Error loading SAM3: {e}")
    def predict_masks(self, image_pil, text_prompt, threshold=0.4):
        if self.model is None: return []
        inputs = self.processor(
            images=image_pil,
            text=text_prompt,
            return_tensors="pt"
        ).to(self.device)
        with torch.no_grad():
            outputs = self.model(**inputs)
        results = self.processor.post_process_instance_segmentation(
            outputs, 
            threshold=threshold, 
            mask_threshold=0.5, 
            target_sizes=inputs["original_sizes"].tolist()
        )[0]
        masks = []
        if "masks" in results:
            for i, mask_tensor in enumerate(results["masks"]):
                mask_np = (mask_tensor.cpu().numpy() * 255).astype(np.uint8)
                mask_pil = Image.fromarray(mask_np)
                masks.append(mask_pil)
        return masks
engine = Sam3PrivacyEngine()Mogelijk gemaakt door

Zo past deze engine in de pipeline:

• Sam3PrivacyEngine.init(): Deze initializer kiest het beste apparaat (CUDA indien beschikbaar, anders CPU), laadt de facebook/sam3-gewichten en de bijbehorende Sam3Processor, en zet het model op het gekozen apparaat zodat inference efficiënt kan draaien.
• Sam3PrivacyEngine.predict_masks(): Deze methode bouwt modelinputs van een PIL-afbeelding en een tekstprompt, draait forward inference onder torch.no_grad() om gradient-overhead te vermijden, en post-processt de outputs met post_process_instance_segmentation met de opgegeven detectie- en masker­drempels en de originele doelsizes voor correcte schaling. Hij retourneert per-instantie segmentatiemaskers die van tensors naar NumPy-arrays en vervolgens naar PIL-“L”-maskers (8‑bit grijswaardenafbeeldingen (modus "L") waar elke pixel een waarde van 0–255 is) worden geconverteerd voor compositing.
• engine = Sam3PrivacyEngine(): Deze regel construeert één herbruikbare engine-instantie zodat het SAM3-model één keer laadt en herhaaldelijk kan worden aangeroepen voor afbeeldingen of videoframes zonder opnieuw te initialiseren.

Met deze zelfstandige engine kun je elke afbeelding en tekstprompt omzetten in instantiemaskers. Vervolgens passen we selectief vervaging toe met deze maskers en stoppen we alles in de Gradio-UI.

Stap 4: Vervaaglogica

In deze sectie nemen we de maskers van SAM3 en passen we privacy toe. Alleen de gemaskeerde gebieden worden vervaagd terwijl de rest behouden blijft. We beginnen met een herbruikbare Gaussiaanse blur-functie en koppelen die daarna in twee pipelines: één voor afbeeldingen en één voor video’s.

Stap 4.1: Gaussiaanse blur

Deze helper neemt een afbeelding en een of meer PIL-"L"-maskers, voegt ze samen tot één composietmasker en plakt een vervaagde kopie van de afbeelding alleen waar het masker wit is (255). 

def apply_blur_pure(image_pil, masks, blur_strength):
    if not masks:
        return image_pil
    radius = blur_strength
    blurred_image = image_pil.filter(ImageFilter.GaussianBlur(radius=radius))
    composite_mask = Image.new("L", image_pil.size, 0)
    for mask in masks:
        composite_mask.paste(255, (0, 0), mask=mask)
    final_image = image_pil.copy()
    final_image.paste(blurred_image, (0, 0), mask=composite_mask)
    return final_imageMogelijk gemaakt door

Zo werkt deze functie:

• De functie GaussianBlur() maakt eerst een volledig vervaagde versie van de afbeelding. Terwijl composite_mask een “L” (grijswaarden) masker is dat is geïnitialiseerd als zwart (0 = origineel behouden). 
• Voor elk SAM3-masker plakken we het in dit composiet zodat witte pixels (255) zich opstapelen waar de vervaging moet verschijnen. 
• Ten slotte plakken we de vervaagde afbeelding over het origineel met composite_mask, zodat alleen de witte gebieden vervagen.
• De methode final_image.paste() vervangt alleen gemaskeerde pixels en laat de rest onaangetast voor maximale visuele kwaliteit.

Met één aanroep kun je elk stel regio’s, zoals gezichten, schermen of kentekenplaten, vervagen terwijl de achtergronden blijven zoals ze zijn.

Stap 4.2: Afbeeldingspipeline

Deze substap behandelt de end-to-end beeldstroom: van het normaliseren van input tot het ophalen van maskers van SAM3, vervolgens het vervagen van gemaskeerde pixels en tot slot het resultaat retourneren.

def process_image(input_img, text_prompt, blur_strength, confidence):
    if input_img is None: return None, None
    if isinstance(input_img, np.ndarray):
        image_pil = Image.fromarray(input_img).convert("RGB")
    else:
        image_pil = input_img.convert("RGB")
    masks = engine.predict_masks(image_pil, text_prompt, confidence)
    result_pil = apply_blur_pure(image_pil, masks, blur_strength)
    output_path = "privacy_image.png"
    result_pil.save(output_path)
    return np.array(result_pil), output_pathMogelijk gemaakt door

We verwerken afbeeldingen met de volgende stapsgewijze pipeline:

• We converteren eerst elke Gradio-NumPy-array naar een PIL-RGB-afbeelding voor consistente verwerking.
• Vervolgens roepen we engine.predict_masks() aan om SAM3-instantiemaskers op te halen voor de opgegeven text_prompt.
• Daarna passen we de functie apply_blur_pure() toe met de gekozen blur_strength zodat alleen de gemaskeerde gebieden worden vervaagd.
• Na verwerking slaan we het resultaat op als een png en retourneren we zowel een NumPy-array als een downloadbaar bestand.

Met de beeldstroom rond kunnen we nu door naar de videopipeline.

Stap 4.3: Videopipeline

De videostroom spiegelt het beeldpad, maar streamt frame voor frame met imageio. Voor elk frame segmenteren we, vervagen we de gemaskeerde gebieden en schrijven we naar een H.264-gecodeerd MP4-bestand.

def process_video(video_path, text_prompt, blur_strength, confidence, max_frames):
    if not video_path: return None, None
    try:
        reader = imageio.get_reader(video_path)
        meta = reader.get_meta_data()
        fps = meta.get('fps', 24)  
        output_path = "privacy_video.mp4"
        writer = imageio.get_writer(
            output_path, 
            fps=fps, 
            codec='libx264', 
            pixelformat='yuv420p',
            macro_block_size=1
        )  
        print("Starting video processing...")
        for i, frame in enumerate(reader):
            if i >= max_frames:
                break  
            frame_pil = Image.fromarray(frame).convert("RGB")
            masks = engine.predict_masks(frame_pil, text_prompt, confidence)
            processed_pil = apply_blur_pure(frame_pil, masks, blur_strength)
            writer.append_data(np.array(processed_pil))
            if i % 10 == 0:
                print(f"Processed frame {i}...")
        writer.close()
        reader.close()
        print("Video processing complete.")
        return output_path, output_path
    except Exception as e:
        print(f"Error: {e}")
        return None, NoneMogelijk gemaakt door

Zo verwerken we video’s met de volgende pipeline:

• We openen eerst het bestand met imageio.get_reader(), itereren vervolgens over frames en lezen de FPS uit metadata (standaard 24 als die ontbreekt).
• Daarna converteren we elk frame naar een PIL-afbeelding, voorspellen we maskers met SAM3 via de methode engine.predict_masks() en vervagen we de gemaskeerde gebieden met de functie apply_blur_pure().
• Vervolgens voegen we elk verwerkt frame toe aan een MP4-writer geconfigureerd met pixelformat='yuv420p' voor brede compatibiliteit en macro_block_size=1 om uitlijningsartefacten te voorkomen.
• Na verwerking knippen we de output bewust af door te stoppen na een specifiek aantal frames, standaard 60 frames (~2 seconden), om Colab-tests vlot te houden en time-outs te vermijden.

Met deze videostroom kun je gevoelige gebieden in vergaderopnames, dashcamclips of screencaptures vervagen via een eenvoudige tekstprompt.

Stap 5: Gradio-inference

Nu de masking en vervaging klaar zijn, wikkelen we alles in een lichtgewicht Gradio-UI zodat iedereen een afbeelding of video kan uploaden, een tekstprompt kan typen en de output kan downloaden.

with gr.Blocks(title="SAM3 Privacy Filter", theme=gr.themes.Soft()) as demo:
    gr.Markdown("# SAM3 Privacy Filter")
    gr.Markdown("Auto-detect and blur faces/objects.")
    with gr.Tabs():
        with gr.Tab("Image"):
            with gr.Row():
                with gr.Column():
                    im_input = gr.Image(label="Input Image", type="numpy")
                    im_prompt = gr.Textbox(label="Text Prompt", value="faces")
                    im_blur = gr.Slider(5, 100, value=30, label="Blur Strength")
                    im_conf = gr.Slider(0.1, 1.0, value=0.4, label="Confidence")
                    im_btn = gr.Button("Blur Image", variant="primary")
                with gr.Column():
                    im_output = gr.Image(label="Preview")
                    im_dl = gr.File(label="Download Image")   
            im_btn.click(process_image, [im_input, im_prompt, im_blur, im_conf], [im_output, im_dl])
        with gr.Tab("Video"):
            with gr.Row():
                with gr.Column():
                    vid_input = gr.Video(label="Input Video")
                    vid_prompt = gr.Textbox(label="Text Prompt", value="faces")
                    vid_blur = gr.Slider(5, 100, value=30, label="Blur Strength")
                    vid_conf = gr.Slider(0.1, 1.0, value=0.4, label="Confidence")
                    vid_limit = gr.Slider(10, 300, value=60, step=10, label="Max Frames")
                    vid_btn = gr.Button("Blur Video", variant="primary")
                with gr.Column():
                    vid_output = gr.Video(label="Preview")
                    vid_dl = gr.File(label="Download Video")
            vid_btn.click(process_video, [vid_input, vid_prompt, vid_blur, vid_conf, vid_limit], [vid_output, vid_dl])
demo.launch(share=True, debug=True)Mogelijk gemaakt door

De Gradio-app embedt de SAM3-maskerings- en vervagingspipeline in een eenvoudige web-UI met:

• App-shell (gr.Blocks): Dit blok maakt een single-page Gradio-app met een titel en twee tabbladen, één voor afbeeldingen en één voor video’s, zodat gebruikers van modus kunnen wisselen zonder de pagina te verlaten.
• Tabblad Afbeelding: Inputs zijn onder meer een afbeeldinguploader, een tekstvak voor de tekstprompt en schuifregelaars voor vervagingssterkte en confidence. De uitvoervelden tonen een verwerkte preview en een downloadbare PNG, terwijl de knop Blur Image alles doorstuurt naar process_image, dat SAM3 voor maskers aanroept en Gaussiaanse blur alleen op gemaskeerde pixels toepast.
• Tabblad Video: Voor videovervaging omvatten de inputs een videouploader, een tekstvak voor de tekstprompt, schuifregelaars voor vervagingssterkte en confidence, en een maximumaantal frames voor snelle demo’s. De uitvoervelden bieden een inline preview en een downloadbare MP4, terwijl de knop Blur Video process_video aanroept, over frames itererend om maskers te voorspellen, gemaskeerde gebieden te vervagen en een H.264-video te encoderen.
• Launch: De methode demo.launch() start de app, genereert een deelbare link en toont gedetailleerde stacktraces wanneer debuggen is ingeschakeld.

Nu is onze SAM3 Privacy Filter klaar om media (afbeelding/video) te uploaden, prompt en drempels in te stellen en de vervaagde outputs te exporteren.

Opmerking: Alle afbeeldingen en video’s in deze demo zijn afkomstig van Pexels.com en vrij te gebruiken.