Manual de Uso

PipoFilTrack se desarrolló en el Instituto Tecnológico de Bs As, Argentina como parte del Proyecto Final de la carrera de Ing. Informática de T. Brandy, F. Pannunzio e I. Sagüés, dirigido por la Dra. L. Bruno (UBA-CONICET) en 2022.

Está pensado como una herramienta para ser utilizada con fines de docencia e investigación y su uso es libre.

Si publica resultados basados en PipoFilTrack, esperamos que lo reconozca citando del siguiente modo: Brandy, T., Pannunzio, F. & Sagüés, I. PFT, 2022, https://fernet.exp.dc.uba.ar & https://pf-pipo.it.itba.edu.ar

Objetivo

El objetivo de la aplicación es recuperar las posiciones de un segmento de filamento seleccionado a lo largo de una secuencia de frames.

Pasos a seguir

1. Inicio

Esta es la pantalla inicial de la aplicación.

• MANUAL DE USO: redirige a este manual.
• SELECCIONE LAS IMÁGENES QUE DESEA TRACKEAR: permite subir la secuencias de imágenes que se desea trackear.
• Parámetros de tracking: Formulario de selección de los parámetros de tracking. Los mismos se detallan más adelante.

2. Selección de secuencia de imágenes a trackear

1. Hacer click en SELECCIONE LAS IMÁGENES QUE DESEA TRACKEAR.
2. Se abre una ventana similar a la de la imagen. Se muestran las imágenes que es posible subir a la aplicación. Se soportan los formatos TIF, JPG y PNG.
3. Seleccionar todos los frames de la secuencia. Se puede hacer manteniendo presionado Ctrl y haciendo click en todos los frames. Para seleccionar un rango, seleccionar el primer frame, y luego presionar Shift hacer click en el último frame.
4. Confirmar haciendo click en Open, o un botón similar.

Consideraciones extra

Orden

El orden en el que vemos las imágenes en la ventana de selección es el orden en el que los frames aparecerán en la secuencia. Se recomienda nombrar a todos las imágenes de la secuencia con el mismo nombre, y solo diferenciarlas por un número final que represente su posición en la secuencia. Luego, ordenar los archivos por nombre de forma descendente, en general haciendo click en el encabezado Name.

Tamaño máximo

El tamaño máximo total de la secuencia de imágenes que la aplicación permite subir para el análisis es 250 MB. En caso de superarlo, se recomienda previamente utilizar métodos de compresión. En caso de no poder evitar superar este límite, un administrador de la aplicación es capaz de aumentarlo, ya sea temporal o permanentemente.

3. Selección de filamento y sus puntos de control

Una vez seleccionadas las imágenes de la secuencia, aparecerá en el centro de la pantalla la primera imagen de la secuencia. El siguiente paso es seleccionar puntos de control sobre el filamento que describan su forma, como podemos ver en la siguiente imagen. Las líneas que conectan estos puntos deben estar idealmente siempre dentro del filamento. Además, los parámetros de tracking deseados deben ser seleccionados.

Controles de selección de puntos

El selector de puntos posee 3 elementos de control a su derecha. En orden de arriba hacia abajo:

• Zoom: Los símbolos + y - permiten acercar y alejar la imagen, respectivamente.
• Undo/Redo: Permiten eliminar o volver a colocar el último punto seleccionado.
• Modo: Por defecto ons encontramos en el modo "lápiz", que nos permite colocar puntos al hacer click. El modo "cruz", en cambio, nos permite arrastrar la imagen con el mouse, en caso de que esté acercada.

Preview del primer frame

Debajo del formulario de selección de parámetros, se puede encontrar el resultado de trackear el primer frame. El mismo se refresca cada vez que se modifique la selección de puntos, o los parámetros del algoritmo. El mismo permite rápidamente estimar el resultado de tracking que obtendremos con la configuración seleccionada.

4. Ejecución de tracking

Una vez que se esté seguro de la selección de puntos y de parámetros, con el botón TRACK se podrá iniciar el tracking.

5. Visualización y Exportación de Resultados

Una vez que el tracking haya resultado exitoso podremos visualizar las imágenes resultantes de manera animada o cuadro a cuadro, y descargarlas. Además, se podrá descargar las coordenadas de los puntos en formato Json o TSV, ambos amigables tanto para sistemas informáticos (ej. planillas de cálculo) como para humanos.

Visualizador de resultados

• PLAY/PAUSE: Iniciar o pausar el pasaje de imágenes automático.
• STOP: Pausar el pasaje de imágenes automático, y volver al primer cuadro.
• Pasaje manual: Abajo al centro se puede ver el cuadro actual de la secuencia, y pasarla mediante las flechas de los costados.
• Velocidad: Se puede aumentar o disminuir la velocidad de la reproducción automática de las imágenes.

Interpretación de resultados

Los puntos graficados sobre la imagen pueden ser de 3 colores distintos, los cuales transmiten información adicional sobre la confianza que se le tiene a dicho punto.

• Verde: Color estándar. Es decir que dicha coordenada fue recuperada siguiendo el método estándar definido de ajustar mediante una función gaussiana, por lo que se le tiene una alta confianza.
• Azul: El error del ajuste gaussiano utilizado del punto superó el límite configurado. Entonces, el mismo es calculado empleando la rutina de reposición de puntos globales, interpolando linealmente. Estos puntos poseen una menor confianza. Este color suele aparecer en zonas donde existe un alto ruido, o donde hay una intersección entre filamentos, lo cual distorsiona la información.
• Rojo: Este color solo puede aparecer en los extremos del filamento. Son puntos que serían azules, pero que están ubicados al extremo del filamento, por lo que no se puede realizar la interpolación lineal. En cambio, se mantiene la posición calculada en el cuadro anterior. Este método es el menos confiable. En general hay que buscar evitar este tipo de puntos cambiando el segmento seleccionado, o los parámetros del algoritmo.

Parámetros de visualización

Por encima del visualizador de resultados se encuentran 2 checkbox para modificar la información que se grafica en los resultados.

• Puntos codificados con colores: Activa la codificación de colores. Si no, todos los puntos son verdes.
• Perfiles de intensidad: Grafica como barras celestes los perfiles de intensidad utilizados para cada punto durante el algoritmo. Útil para entender por qué el algoritmo puede estar fallando.

Exportación de resultados

Imágenes

Se pueden exportar las imágenes como son vistas en el visualizador de resultados haciendo click en el link ZIP. Las mismas se descargan en un archivo .ZIP en formato .PNG.

Coordenadas - JSON

Se pueden descargas las coordenadas recuperadas en formato JSON haciendo click en el link correspondiente.

La estructura utilizada es una lista donde cada item contiene los puntos de cada imagen, en orden. Cada item está compuesto por un objeto de clave "points" y valor un array con las coordenadas de todos los puntos del filamento de esa imagen, ordenados. Las coordenadas están modeladas como un objeto con las propiedades "x" e "y", cuyo valor es un número decimal que representa el sub-píxel donde el punto está ubicado dentro de la imagen. Un ejemplo de 2 imágenes y 2 puntos es:

      [
        { "points": [
          { "x": 1.5, "y": 2.5 },
          { "x": 5.0, "y": 3.0 }
        ] },
        { "points": [
          { "x": 5.5, "y": 0.5 },
          { "x": 8.0, "y": 0.1 }
        ] }
      ]
      

Coordenadas - TSV

Se pueden descargas las coordenadas recuperadas en formato TSV haciendo click en el link correspondiente.

El formato del archivo TSV se compone de únicamente 3 headers: frame, x, y. El primero indica el número de imagen, el segundo es la coordenada x de posición sub-pixel de un punto dentro del filamento en la imagen correspondiente, y el tercero es equivalente para la coordenada y. Un ejemplo de 2 imágenes y 2 puntos es:

      frame   x   y
      0   1.5 2.5
      0   5.0 3.0
      1   5.5 0.5
      1   8.0 0.1
      

Parámetros de tracking

• Tolerancia de error: Número decimal que indica el máximo error tolerado durante el ajuste gaussiano para obtener las coordenadas de un punto a partir de su perfil de intensidad asociado. En caso de que se supere, el punto pasara a considerarse "azul", y será calculado a partir de la rutina de reposición de puntos. El error es calculado como la desviación estándar de la media de la gaussiana. Si en los resultados vemos puntos azules en lugares donde no parecería haber problemas, una solución puede ser aumentar este parámetro. Si vemos que aún en zonas problemáticas donde el tracking falló los puntos están verdes, puede ser que este parámetro está muy alto y permisivo.
• Ancho de perfil de intensidad: Número entero que representa el largo en píxeles del perfil de intensidad que se toma por cada punto. Estos perfiles de intensidad se pueden visualizar en la sección de resultados como barras celestes. Es muy importante que el ancho de intensidad sea más largo que el ancho del filamento y que incluya un poco de fondo, así se puede formar correctamente la gaussiana.
• Densidad de puntos: Número entero que representa cada cuantos píxeles se toma un punto para analizar. Es decir, sería nuestro periodo de muestreo del filamento. Por defecto es 1, por lo que tomamos tantos puntos como píxeles haya. Esto mejora la precisión del análisis, pero aumenta los tiempos de procesado. En casos de muy alta resolución donde los tiempos de análisis sean demasiado altos, es posible que convenga sacrificar precisión por velocidad.
• Cantidad de puntos para interpolar: Número entero que representa la cantidad de puntos máximos que tomamos a ambos lados de un punto que necesita ser repuesto (es decir, un punto "azul") para calcular la interpolación lineal que necesita la rutina de reposición. El valor por defecto parece funcionar bien en la gran mayoría de casos, pero puede haber casos donde tomar más puntos mejore los resultados de la rutina.
• Puntos para calcular la tangente: Para calcular la dirección normal de un punto del filamento por la cual se deberá tomar su perfil de intensidad, primero se debe calcular la dirección tangente (pendiente del filamento) en ese punto. Para calcularla se toma la recta que une los puntos que están a la distancia (en puntos) que este parámetro indica, dividido 2. El valor por defecto de 15 funciona bien para la gran mayoría de los casos, aunque es posible que en filamentos de alta densidad de puntos este parámetro deba ser aumentado.
• Longitud del segmento de suavizado: Para la rutina de suavizado final del algoritmo, se ajustan todos los puntos del filamento obtenidos previamente a curvas de Bézier. Este parámetro indica la cantidad de puntos que serán ajustados a la misma curva. Estos ajustes se hacen de manera independiente, y luego son unidos nuevamente por los extremos. Idealmente, queremos ajustar todos los puntos a una misma curva de bezier, es decir que querríamos que este parámetro sea superior a la cantidad de puntos que estamos trackeando. Sin embargo, si encontramos que el filamento que estamos trackeando es demasiado largo, o vemos que no permitimos que el tracking se pueda curvar lo suficiente como para recuperar con precisión el filamento de la imagen, este parámetro puede ser disminuido. La cantidad de segmentos de Bézier es la cantidad de puntos totales dividido este parámetro.
• Suavizado final: Se decidió que la rutina final de suavizado sea opcional. Este parámetro indica si el algoritmo debe realizar la misma, o saltearla.
• Imágenes invertidas: Este parámetro debe ser activado en caso de que el filamento a trackear sea negro sobre un fondo blanco. Así, la imagen es invertida antes de ser analizada.

Errores

Es posible que durante la ejecución de algoritmo de tracking suceda algún error. En dicho caso, se mostrará un mensaje de error debajo de la imagen de selección de puntos. Se intenta que dichos mensajes sean descriptivos. Los siguientes son excepciones:

• Server Connection Error: TypeError: NetworkError when attempting to fetch resource: Este es un error de conexión al servidor. Lo más probable es que el servidor donde la aplicación está alojada este caído. Otra opción es que el navegador no tenga acceso a internet. Si se posee conexión y el error persiste, se recomienda contactarse con algún administrador del sistema.
• Server Error: 413 - Request Entity Too Large: Se está intentando subir una secuencia de imágenes cuyo tamaño total es superior al permitido, actualmente 250 MB.