Hugging Face's logo

Spaces:
kerojohan
/
bat_tracker
Sleeping

App Files Community
bat_tracker / README.md
kerojohan
Sync Space project with latest bat_tracker upstream
aed2053
preview code
|
raw
history blame contribute delete
15 kB

A newer version of the Gradio SDK is available: 6.15.2

Upgrade
metadata 
title: Bat Tracker
emoji: 🦇
colorFrom: yellow
colorTo: gray
sdk: gradio
app_file: app.py
pinned: false

bat_tracker

Proyecto Python para Linux orientado a CPU (con opcion CUDA cuando esta disponible) que procesa videos IR monocromos de cueva y genera:

  • background.png: fondo por mediana temporal
  • valid_region/: mascara vertical de zona valida estimada por perfil de iluminacion o profundidad
  • tracks.csv: trayectorias 2D por objeto
  • track_candidates.csv: evaluacion de todos los tracks candidatos con score y motivos de rechazo
  • events.csv: resumen por track con direccion, duracion, desplazamiento y estadisticas
  • tracks.svg: artefacto vectorial autocontenido con las trayectorias 2D en coordenadas originales
  • tracks_render.json: geometria normalizada por track para consumo externo
  • tracks_overlay.png: trayectorias sobre el fondo
  • meta.json: parametros y metricas de ejecucion

No genera video anotado y no usa modelos entrenados.

Instalacion 

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Opcionalmente, instalacion como paquete:

pip install -e .

Uso 

bat-tracker --input /path/video.mp4 --output /path/out_dir --config /path/config.yaml

O sin --config para usar defaults.

Tambien puede ejecutarse sin instalar entrypoint:

python -m bat_tracker --input /path/video.mp4 --output /path/out_dir --config /path/config.yaml

Generacion standalone de mascara vertical valida:

bat-valid-region \
  --input /path/out_dir/background.png \
  --output /path/out_dir/valid_region \
  --blur-kernel-size 151 \
  --threshold-ratio 0.45 \
  --safety-margin 10

Alternativamente:

python -m bat_tracker.valid_region --input /path/out_dir/background.png --output /path/out_dir/valid_region

Ejemplo de Resultados

El pipeline genera visualizaciones de depuración y tracking como:

  • valid_region/overlay.png: máscara de zona válida superpuesta sobre el fondo.
  • tracks_overlay.png: trayectorias 2D sobre el fondo calculado.

Entradas

  • --input (obligatorio): ruta a video IR monocromo, por ejemplo .mp4.
  • --output (obligatorio): carpeta de salida donde se escriben resultados.
  • --config (opcional): YAML con parametros; si no se pasa, usa defaults internos.

Ejemplos de configuracion incluidos:

  • config.yaml.example (base)
  • config.out3_clean.yaml (perfil limpio para escenas tipo out3 con menos ruido)

Salidas

Se escriben en la carpeta indicada por --output:

  • background.png: fondo estimado por mediana temporal.
  • valid_region/mask.png: mascara binaria vertical (255 zona valida, 0 laterales invalidos).
  • valid_region/overlay.png: debug visual de banda valida sobre la imagen.
  • valid_region/gate_overlay.png: debug visual del gate real usado en tracking tras aplicar valid_region_gate_dilate_px.
  • valid_region/profile.png: debug de region valida (perfil horizontal en modo horizontal_illumination_profile; mapa de profundidad en modos central_deep_layer/hybrid_deep_layer_profile).
  • tracks.csv: trayectorias 2D por deteccion y frame.
  • track_candidates.csv: auditoria opcional de todos los tracks candidatos tras merge, con accepted, score y reject_reasons.
  • events.csv: resumen por track con inicio/fin, duracion, desplazamiento, recorrido, straightness y direccion.
  • tracks.svg: export vectorial autocontenido de todas las trayectorias en el sistema de coordenadas original del video, con el mismo color por track_id y las mismas etiquetas opcionales que tracks_overlay.png.
  • tracks_render.json: export JSON con width, height, puntos por track y metadatos minimos (track_id, frame_start, frame_end, duration_sec, direction, point_start, point_end).
    • direction usa el vocabulario entry, exit, inside, outside, unknown.
  • tracks_overlay.png: trayectorias dibujadas sobre background.png.
  • tracks_overlay_raw.png y tracks_overlay_smoothed.png (opcionales): overlays adicionales cuando output.trajectory_smoothing_enabled esta activo.
  • track_clips/ (opcional): clips de video por track (track_0001_000120-000186.mp4, etc.).
  • meta.json: metadatos del video, parametros efectivos y metricas de ejecucion.
    • incluye bloques video, parameters, background, valid_region, metrics, execution, performance, outputs, trajectory_smoothing y postprocess.
    • postprocess resume tambien cuantos candidatos se aceptaron/rechazaron y las causas mas frecuentes.

Formato de tracks.csv

Columnas exactas:

video_id,track_id,frame,time_sec,x,y,vx,vy,bbox_x1,bbox_y1,bbox_x2,bbox_y2,area

Formato de events.csv

Columnas exactas:

video_id,track_id,time_start_sec,time_end_sec,duration_sec,frame_start,frame_end,num_detections,x_start,y_start,x_end,y_end,displacement_px,path_length_px,straightness,mean_speed_px_sec,mean_area,start_in_valid_region,end_in_valid_region,direction

direction usa el vocabulario entry, exit, inside, outside, unknown.

Pipeline implementado

  1. Lectura del video y metadatos.
  2. Generacion de background.png por mediana temporal de un muestreo de frames.
  3. Deteccion de foreground por diferencia absoluta con el fondo.
  4. Umbral binario (fijo u Otsu) + morfologia (open/close) + contornos.
  5. Filtrado de blobs por area minima/maxima.
  6. Tracking 2D frame a frame con asignacion greedy por distancia maxima y prediccion por velocidad para reducir cortes.
  7. Merge automatico opcional de tracks fragmentados antes del filtrado final.
  8. Evaluacion centralizada de tracks candidatos (score + motivos de rechazo) y export de tracks.csv, events.csv, tracks.svg, tracks_render.json y render final tracks_overlay.png.
  9. Si valid_region.enabled, calculo de banda vertical valida desde iluminacion horizontal y guardado en valid_region/*.
  10. Export de meta.json con parametros, metadatos y metricas.
  • incluye postprocess.auto_merges_applied cuando tracking.auto_merge_suggested esta activo.
  • incluye trajectory_smoothing.enabled/window y rutas extra de overlay cuando el suavizado esta activado.

Configuracion

Usa config.yaml.example como base.

  • background.sample_frames: numero de frames para mediana temporal
  • background.uniform_sampling: muestreo uniforme en todo el video
  • background.input_image: si se define, reutiliza un fondo precomputado y omite la mediana temporal
  • background.context_start_sec: segundo inicial de la ventana usada para estimar background.png
  • background.context_duration_sec: duracion de esa ventana; -1 usa el video entero
  • detection.*: parametros de blur, threshold, morfologia y area
    • detection.threshold_mode: fixed o otsu
    • detection.otsu_offset: ajuste fino sobre umbral Otsu (negativo = mas sensible)
    • detection.max_global_intensity_shift: descarta frame si el brillo medio difiere demasiado del fondo (-1 desactiva)
    • detection.max_foreground_ratio: descarta frame si el porcentaje de foreground es demasiado alto (-1 desactiva)
    • detection.max_detections_per_frame: descarta frame si supera este numero de blobs (0 desactiva)
    • detection.roi_x_min/roi_x_max/roi_y_min/roi_y_max: limita detecciones a una ROI por centroide (-1 desactiva cada limite)
    • detection.temporal_burst_*: gate temporal por rafagas de detecciones (desactiva con 0)
      • temporal_burst_min_detections: umbral de detecciones altas por frame
      • temporal_burst_window_frames: tamano de ventana temporal
      • temporal_burst_trigger_frames: frames altos dentro de ventana para activar suppression
      • temporal_burst_cooldown_frames: frames suprimidos tras activacion
  • tracking.*: distancia maxima de asociacion, tolerancia a frames perdidos y filtros minimos por trayectoria
    • tracking.min_track_length: minimo de puntos por trayectoria
    • tracking.min_track_duration_sec: duracion minima en segundos (si se define, se combina con min_track_length)
    • tracking.min_track_displacement: desplazamiento neto minimo (pixeles)
    • tracking.min_track_path_length: recorrido acumulado minimo (pixeles)
    • tracking.min_track_straightness: rectitud minima desplazamiento/recorrido (0..1)
    • tracking.require_start_or_end_in_valid_region: conserva solo tracks que empiezan o acaban dentro de la mascara valida
    • tracking.valid_region_gate_dilate_px: dilata la mascara valida en pixeles antes de aplicar el filtro inicio/fin
    • tracking.auto_merge_suggested: fusion automatica postproceso de tracks potencialmente duplicados
    • tracking.export_track_candidates: escribe track_candidates.csv con todos los tracks evaluados, incluidos los rechazados
    • tracking.merge_max_gap_frames y tracking.merge_max_endpoint_distance: merge por handoff cercano (fin->inicio)
    • tracking.merge_overlap_min_common_frames: minimo de frames comunes para evaluar merge por solape
    • tracking.merge_overlap_max_mean_distance: distancia media maxima en frames comunes
    • tracking.merge_overlap_min_direction_cosine: coherencia minima de direccion entre tracks solapados
  • valid_region.*: mascara vertical valida para eliminar vignette lateral IR sin recortar interior oscuro de cueva
    • valid_region.enabled: activa/desactiva etapa
    • valid_region.method: horizontal_illumination_profile (default), central_deep_layer o hybrid_deep_layer_profile (perfil primero y profundidad despues, sin laterales)
    • valid_region.apply_to_detection: aplica mascara en deteccion por frame (si no, se usa solo para filtros de track)
    • valid_region.hybrid_combine_mode: and/or para combinar capa de profundidad + umbral por perfil
    • valid_region.input_image: si se define, usa esta imagen en vez de background.png
    • valid_region.input_mask: si se define, reutiliza exactamente esta mascara y omite su estimacion
    • valid_region.context_start_sec y valid_region.context_duration_sec: permiten estimar la mascara con una ventana temporal distinta a la del fondo de deteccion
    • valid_region.blur_kernel_size y valid_region.profile_smooth_window: deben ser impares
    • valid_region.threshold_ratio: fraccion del pico del perfil para definir region valida
    • valid_region.safety_margin: recorte adicional en pixeles por lado
    • valid_region.min_region_width_ratio: evita regiones absurdamente estrechas
    • valid_region.depth_percentile/depth_morph_kernel/depth_min_area_ratio: parametros del modo central_deep_layer
    • valid_region.depth_layer_percentiles + valid_region.depth_layer_dilate_px: expansion no uniforme por capas de profundidad (listas emparejadas)
    • valid_region.bottom_contour_*: refinado opcional del borde inferior ajustandolo al gradiente vertical de profundidad (*_search_* define ventana de busqueda, *_smooth_window suaviza la curva, *_gradient_quantile controla sensibilidad, *_regularization/*_max_step_px reducen muescas, *_downward_bias permite bajar cuando hay empate, *_regularization_mix mezcla ajuste local/global, *_deepest_strong_ratio favorece el borde fuerte mas profundo frente a crestas intermedias)
  • output.*: estilo del overlay y artefactos de salida
    • output.overlay_line_thickness: grosor de linea en tracks_overlay.png y tracks.svg
    • output.overlay_start_radius: radio del marcador del primer punto del track
    • output.overlay_alpha: alpha del overlay raster tracks_overlay.png
    • output.overlay_draw_track_labels: dibuja el numero de track_id junto al inicio de cada track en tracks_overlay.png y tracks.svg
    • output.overlay_draw_track_labels_at_end: dibuja el numero de track_id al final del track en tracks_overlay.png y tracks.svg
    • output.overlay_label_font_scale y output.overlay_label_thickness: estilo de etiqueta compartido por tracks_overlay.png y tracks.svg
    • output.progress_enabled: muestra trazas de avance global por consola durante todo el pipeline (etapas + frames)
    • output.progress_step_percent: porcentaje global entre trazas (1..100, por defecto 5)
    • output.export_track_clips: exporta clips por track en una carpeta
    • output.track_clips_subdir: nombre de la carpeta de clips dentro del output
    • output.track_clips_padding_frames: frames extra antes/despues del rango del track
    • output.trajectory_smoothing_enabled: genera una version suavizada de las trayectorias para overlays y events.csv
    • output.trajectory_smoothing_window: ventana impar >= 3 usada en el suavizado
  • execution.*: seleccion de backend de computo
    • execution.device: auto (default), cpu o cuda
    • execution.strict_parity: cuando esta en true, compara mascara CPU/GPU y conserva la salida CPU para mantener resultados equivalentes al pipeline original
    • etapa extra GPU: el calculo de background.png por mediana usa CuPy si esta instalado; si no, cae automaticamente a CPU

Ajuste rapido para mejorar recall/continuidad

Si faltan sujetos o aparecen tracks cortados:

  1. subir tracking.max_distance (ej. 70-90)
  2. subir tracking.max_missed (ej. 15-25)
  3. bajar detection.min_area (ej. 4-8)
  4. usar detection.threshold_mode: otsu y ajustar detection.otsu_offset (ej. -6 mas sensible)

Si aparecen demasiados tracks de ruido:

  1. subir tracking.min_track_displacement (ej. 20-40)
  2. subir tracking.min_track_path_length (ej. 30-80)
  3. subir tracking.min_track_straightness (ej. 0.1-0.3)
  4. subir background.sample_frames (ej. 100-300) para estabilizar background.png
  5. activar gates anti-flicker en detection: max_global_intensity_shift, max_foreground_ratio, max_detections_per_frame
  6. activar gate temporal detection.temporal_burst_* para suprimir rafagas cortas de ruido

Tests minimos 

pytest

Los tests cubren deteccion, tracking y export/render de salida.

Agradecimientos / Referencias

Parte de los parámetros y perfiles de uso incluidos en este proyecto se han inspirado en el enfoque y resultados de la herramienta ThruTracker desarrollada por Aaron J. Corcoran. Recomendaos consultar su repositorio en GitHub.

Licencia

Este proyecto está bajo la licencia Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

Esto significa que eres libre de compartir, copiar, distribuir, ejecutar y comunicar públicamente la obra, así como hacer obras derivadas, bajo las siguientes condiciones:

  • Atribución (Attribution): Debes reconocer adecuadamente la autoría, proporcionar un enlace a la licencia e indicar si se han realizado cambios.
  • No Comercial (NonCommercial): No puedes utilizar el material para una finalidad comercial.

Para ver una copia de esta licencia, visita https://creativecommons.org/licenses/by-nc/4.0/ o revisa el archivo LICENSE incluido en este repositorio.