Guía de usuario de Annotate

Annotate es una aplicación local para el análisis de vídeo de fútbol. Un proyecto contiene vídeos importados, clips capturados, marcadores, datos de anotación, presentaciones, exportaciones, cachés y una papelera recuperable.

Las anotaciones de clip son objetos con fotogramas clave que se dibujan sobre el vídeo. Las anotaciones de marcador son documentos asociados a un fotograma exacto del vídeo de origen y pueden incluir animaciones de entrada. El seguimiento genera los fotogramas clave de los resaltados, y la homografía proporciona coordenadas de campo para rectángulos y círculos.

Los datos se guardan en la carpeta del proyecto elegida. La aplicación se comunica con un servicio de Python en el mismo ordenador para importar vídeo, seguir jugadores, calcular la homografía y exportar. Las versiones de escritorio incluyen y gestionan ese servicio; en el desarrollo con navegador se ejecuta por separado.

Descarga el DMG para Mac o el instalador de Windows desde las versiones de GitHub. En macOS, abre el DMG y arrastra Annotate a Aplicaciones. En Windows, ejecuta el instalador y abre Annotate desde el acceso directo del escritorio. Las versiones están pensadas para Mac con Apple Silicon y macOS 14 o posterior, y para Windows 10/11 x64.

Son versiones de evaluación sin firmar, aunque GitHub las marque como «Latest». El sistema puede pedir autorización; no desactives sus protecciones de seguridad. Python, las herramientas de vídeo y los modelos van incluidos. No hace falta terminal ni un navegador aparte. Los servicios se inician y se detienen con la aplicación; el primer inicio puede tardar más mientras se cargan las bibliotecas.

Los registros de los servicios están en ~/Library/Application Support/Annotate/logs/services.log en macOS y en %APPDATA%\Annotate\logs\services.log en Windows. Los editores de clips y de marcadores se abren en ventanas separadas.

El desarrollo con navegador sigue siendo posible con Chrome, Edge, Brave, Arc o Chromium; Safari y Firefox no pueden conceder el acceso necesario a la carpeta del proyecto. El antiguo instalador para navegador y sus instrucciones están en la carpeta legacy/browser-install del repositorio.

El panel de etiquetado es una superficie de trabajo fija, no un menú. Haz clic una vez en una casilla para iniciar un clip y otra vez en la misma casilla para terminarlo. Una casilla que está grabando muestra un punto rojo y el fotograma de inicio, y el clip en curso aparece en la línea de tiempo antes de terminarlo. Los clips de distintos tipos pueden solaparse.

Los modificadores añaden detalles estructurados a la captura iniciada más recientemente, así que elígelos mientras esa captura está en curso. Su disponibilidad cambia según la casilla, pero el panel no se mueve. No hay margen automático antes ni después: los fotogramas en los que haces clic son los límites del clip.

Haz clic en un clip de la línea de tiempo o de la lista para seleccionarlo e ir a su inicio. Con el vídeo en pausa, elige Reetiquetar selección y después los modificadores y la nueva casilla; el clip conserva sus fotogramas y pasa al nuevo grupo de la lista. También puedes arrastrar un clip a otro grupo. Abrir editor abre el clip, o lo muestra si ya está abierto, en una ventana separada.

La línea de tiempo de captura separa los grupos en carriles y coloca los solapamientos en subcarriles. Haz clic o arrastra para desplazarte, desplázate en horizontal para avanzar en el tiempo y usa el control de zoom para pasar del detalle fotograma a fotograma al partido completo. Un desplazamiento manual pausa durante cinco segundos el seguimiento automático del cabezal.

El panel integrado sigue el idioma elegido en el encabezado. Los paneles personalizados conservan sus propias etiquetas. Cambiar de idioma no renombra los clips guardados ni cancela las capturas en curso.

El editor de clips reúne el vídeo original, los objetos tácticos animados, un inspector de propiedades y una línea de tiempo de fotogramas clave a nivel de fotograma. La reproducción nunca sale de los límites actuales del clip.

Al dibujar un objeto se crea su primer fotograma clave de posición en el fotograma actual. Avanza con los botones de fotograma o haz clic en la línea de tiempo para ir a otro fotograma y allí mueve, cambia de tamaño o gira el objeto: Annotate añade un fotograma clave e interpola entre ellos. Haz clic en un fotograma clave para volver a su fotograma; los cambios que hagas allí modifican ese fotograma clave en lugar de añadir otro.

El color, el grosor de línea, la opacidad del relleno, el patrón, el nombre y las demás propiedades de estilo pertenecen al objeto entero y se aplican en todos los fotogramas. Con Seleccionar, haz clic en un objeto o arrastra sobre una zona vacía para seleccionar con un rectángulo. Mayús-clic añade objetos, en el vídeo o en la lista, y los cambios del inspector se aplican entonces a todos. Cmd-clic en macOS o Ctrl-clic en Windows quita objetos. Fusionar objetos está disponible para objetos del mismo tipo cuyos fotogramas clave de posición no se solapan.

Elige Recortar y arrastra cualquiera de los tiradores hacia dentro. El resumen indica cuántos marcadores, fotogramas clave y objetos quitaría el recorte. Aplicar recorte confirma los nuevos límites y Cancelar los deja como estaban. Deshacer recorte restaura los límites anteriores mientras no hagas otro cambio en el clip. Recortar solo acorta un clip; no puede ampliarlo más allá de sus límites originales.

Cuando se pierde la continuidad, el resaltado seguido se oculta y vuelven los candidatos provisionales. Selecciona el candidato correcto y elige Continuar; Annotate rellena el hueco y sigue. Si el jugador correcto no se detecta en ese fotograma, avanza de fotograma en fotograma hasta que se detecte y continúa. A veces hay que hacerlo varias veces.

Si el seguimiento ha pasado al jugador equivocado, reproduce hasta el cambio, retrocede al último fotograma correcto y elige Repetir seguimiento desde aquí. Selecciona al jugador correcto y continúa. Listo sustituye el final del seguimiento anterior; Cancelar conserva el original.

El seguimiento usa coordenadas de imagen y no necesita homografía. Los identificadores del seguimiento indican continuidad, no la identidad de un jugador, así que cuenta con corregir seguimientos en solapamientos, cambios de plano y cuando los jugadores salen del encuadre.

Selecciona un resaltado y escribe el nombre del jugador en Nombre. Marca Mostrar nombre para verlo en el vídeo y ajusta Tamaño del texto si hace falta. El nombre también identifica el objeto en la línea de tiempo.

Flecha, Pase bombeado, Sombra defensiva y Polígono pueden unirse a los resaltados. Con Flecha, haz clic en un resaltado y luego en otro: los dos extremos quedan unidos, y la flecha sigue a los jugadores durante el movimiento sin volver a dibujarla.

Un marcador señala un fotograma exacto dentro de un clip. Elige Añadir marcador en el editor de clips para abrir el marcador en su propia ventana, en ese fotograma. El editor de marcadores usa las mismas herramientas de dibujo que el editor de clips, y una flecha trazada de un resaltado a otro queda unida a ambos. Elige Guardar y después Cerrar marcador para volver al clip.

Mantén ← o → para ver hasta cinco segundos de vídeo alrededor del marcador; las anotaciones se ocultan y la edición se bloquea fuera del fotograma del marcador. Espacio vuelve al fotograma editable. Un marcador también puede tener varios conjuntos de anotaciones con nombre cuando un mismo momento admite otras explicaciones, e Importar al clip copia el conjunto activo en el clip, en el fotograma del marcador.

Abre Animaciones en el editor de marcadores, selecciona una forma y elige Añadir. Cada paso tiene un efecto (Aparecer, Desvanecer, Crecer o Barrido) y un inicio: Al hacer clic, Con la anterior o Después de la anterior, con retraso y duración ajustables. Por defecto: Desvanecer, Al hacer clic. Las formas sin paso se muestran desde el principio. Vista previa y Siguiente recorren la secuencia.

Cuando un clip llega a un marcador con animaciones, la reproducción se detiene en el marcador con las formas animadas ocultas. Reproducir, Espacio o un clic en el vídeo ejecuta cada paso de clic, y el siguiente clic después del último paso reanuda el clip.

Para dibujar sobre el propio campo, el clip necesita una homografía. Elige Calcular H. La barra de progreso muestra la carga de los modelos y después la calibración de fotogramas de muestra a lo largo del clip; el primer cálculo tras iniciar la aplicación tarda más. Cancelar se detiene sin sustituir un resultado existente. Los resultados se guardan en caché, y Volver a calcular H los sustituye.

Mostrar H superpone la cuadrícula del campo para compararla con las líneas. Cuando hay una homografía, Rectángulo y Círculo dibujan sobre el campo (Dibujo: campo): toman la perspectiva del campo, sus tiradores se mueven sobre el campo y permanecen en la misma zona de césped cuando la cámara se mueve. Las formas dibujadas en coordenadas de imagen, en cambio, quedan fijas en pantalla.

Eliminar H quita la homografía y vuelve a dibujar en coordenadas de imagen. La calibración de un marcador ofrece el mismo cálculo automático y, como alternativa, H manual para un solo fotograma. El seguimiento no necesita homografía.

Crea una presentación desde la página del proyecto: escribe un nombre, elige Crear y después Abrir. El espacio de edición tiene un explorador de recursos, una vista previa, una fila horizontal de diapositivas y un inspector.

Haz clic en un recurso para previsualizarlo; no se añade nada hasta que lo arrastres a la presentación. Despliega los marcadores de un clip para arrastrar uno como diapositiva propia. Usa Añadir título para títulos, secciones o separadores, y arrastra las miniaturas para reordenarlas. Selecciona una diapositiva de clip para elegir en qué marcadores se pausa.

Presentar oculta la interfaz de edición y ocupa toda la ventana. Las diapositivas de clip reproducen el vídeo original con sus anotaciones animadas y se pausan en los marcadores elegidos; los clics muestran los pasos de animación antes de que el clip siga o la presentación avance. Corte pasa directamente a la siguiente diapositiva, y Vídeo del partido está disponible entre marcadores del mismo vídeo en orden cronológico.

Exportar informe… en la página del proyecto escribe clips.csv, clips.json y una imagen PNG a la resolución del vídeo por cada conjunto de anotaciones de marcador, dentro de la carpeta del proyecto en exports/report/. Los PNG muestran la anotación completa, no un instante de una animación.

Para quitar un clip, selecciónalo en el reproductor de captura y elige Eliminar clip. Los clips, marcadores y conjuntos de anotaciones eliminados se copian primero en .trash/; usa enseguida Deshacer eliminación para restaurar uno. Vaciar papelera borra definitivamente los datos de recuperación guardados.

Para quitar un vídeo, usa Eliminar junto a él en la página del proyecto y confirma con Eliminar vídeo y clips. Esto borra definitivamente la copia del vídeo en el proyecto y todos sus clips, marcadores y conjuntos de anotaciones. El archivo original y las presentaciones no cambian; las diapositivas afectadas indican que falta su origen. La eliminación de un vídeo no se puede deshacer.

El informe de integridad de la página del proyecto enumera los medios que faltan, los documentos ilegibles y las referencias de presentación sin resolver. Sirve para diagnosticar: Annotate no intenta adivinar cómo reescribir tu trabajo. Para tenerlo todo a salvo, haz una copia de seguridad de toda la carpeta del proyecto.

Flecha, Pase bombeado, Sombra defensiva y cada vértice de un Polígono pueden unirse a los resaltados. Una forma unida sigue a su resaltado, tanto si se mueve a mano como por seguimiento. Solo Rectángulo y Círculo usan coordenadas de campo; las demás herramientas usan coordenadas de imagen.

Un proyecto es una carpeta normal. Su manifiesto es project.json; los medios de origen están en media/; los clips y sus documentos de anotación están en analysis/; las presentaciones, exportaciones, cachés y la papelera tienen sus propias carpetas.

No cambies el nombre ni muevas archivos internos mientras un proyecto está abierto. Para hacer una copia de seguridad o mover un proyecto, ciérralo y copia la carpeta completa. Los vídeos se copian en el proyecto, así que durante la importación necesitas espacio para el archivo de origen y para su copia.

Los proyectos de Annotate 0.2 usan el modelo project.v2 y no son compatibles con Annotate 0.1. Conserva una instalación de 0.1 para los proyectos antiguos.