Para desarrolladores - Entendimiento y manejo de demos oficiales HEOP

Acceso a Documentación y Recursos Oficiales

Podemos encontrar mas información respecto a la preparación de datos y el proceso de compilación de demos en la documentación oficial de HEOP al darnos de alta en el portal TPP de Hikvision.

Portal TPP

Tipos de aplicaciones en HEOP

Aplicación no inteligente
Una aplicación no inteligente es aquella que expone capacidades a través de ISAPI, lo que permite al desarrollador interactuar de forma nativa con el hardware del dispositivo para obtener resultados específicos.
En los demos oficiales de Hikvision incluidos en el contenedor encontramos varios ejemplos de este tipo.

Uno de los más representativos es el IsapiDemo, el cual habilita dos endpoints accesibles por ISAPI:

GET /ISAPI/HEOP/System/capabilities
PUT /ISAPI/Image/channels/1/color

Con el segundo endpoint se pueden modificar parámetros de imagen. Al ejecutarse, se establecen los siguientes valores:

Brillo: 59
Contraste: 50
Saturación: 50

Y estos parámetros no se pueden revertir manualmente después de aplicar el cambio, aunque básica esta funcionalidad permite al desarrollador como interactuar con la cámara desde fuera habilitando endpoints para su comunicación abriendo la puerta para la creación de otras capacidades o usos específicos de aplicaciones HEOP.

Compilación y empaquetado del demo isapi_demo

Para crear un ejecutable del demo, se siguen estos pasos:

Ingresar al directorio de la aplicación:
```
cd /heop/demo/isapi_demo
```
Compilar el binario:
```
make
```
Esto generará el archivo ejecutable isapi_demo.
Copiar el binario al directorio APP:
```
cp isapi_demo ./APP
```
Empaquetar la aplicación:
- Para generar una versión de prueba (debug):
```
pack.sh
```
- Para generar una versión comprimida lista para subir al portal y liberar en la cámara:
```
pack.sh -t
```

Aplicación Inteligente en HEOP: Ejemplo Hikflow

Una aplicación inteligente dentro del ecosistema HEOP integra modelos de inteligencia artificial que permiten realizar tareas de análisis avanzado, como detección de objetos, personas, animales o vehículos.
A diferencia de las aplicaciones no inteligentes (que solo exponen capacidades mediante ISAPI), estas aplicaciones requieren modelos entrenados y un flujo de procesamiento más complejo.

El ejemplo oficial proporcionado por Hikvision es el Hikflow Demo, que demuestra cómo montar y ejecutar un modelo de IA en la cámara.

Estructura del proyecto Hikflow

El directorio del demo contiene:

demo/ 
├── bin # Ejecutables 
├── build # Directorio de compilación 
│ ├── makefile_g5 
│ └── MakeOption # Opciones de compilación 
├── code # Código fuente del demo 
├── custom_layer # Código de capas personalizadas 
├── data # Imágenes de prueba 
├── imagelist_*.txt # Lista de imágenes de prueba 
├── config_*.txt # Archivos de configuración del modelo 
└── readme.txt # Instrucciones G5/ 
├── inc # Archivos de cabecera 
└── lib # Bibliotecas

Esta organización refleja que, además del código base, en este demo tenemos también capas personalizadas, datos de prueba y archivos de configuración del modelo para usar.

Preparación de datos

Custom Layer: Copiar las capas personalizadas desde ModelZoo/inference/custom_layer hacia demo/custom_layer.
Data: Copiar las imágenes de prueba desde ModelZoo/inference/data/ hacia demo/data/.
Archivos de configuración: Copiar config_xxx.txt e imagelist_xxx.txt correspondientes al modelo elegido desde ModelZoo/inference.]

Compilación del demo

Dentro del directorio build, se encuentra el archivo makefile_g5 con las reglas de compilación.
El comando para compilar en dispositivos G5 es:

make -f makefile_g5 clean make -f makefile_g5 -j

Esto generará el ejecutable correspondiente (hikflow_demo_g5).

Montar el demo en la cámara

El demo compilado debe montarse en el dispositivo Hikvision usando NFS:

mount -t nfs your_ip_addr:/your_path/demo /mnt/your_name -o nolock

your_ip_addr: IP del servidor donde compilaste el demo.
your_path/demo: Ruta al directorio del demo.
your_name: Carpeta creada en el dispositivo para el montaje.

Ejecutar la aplicación

Existen dos modos de ejecución que podemos modificar directamente en el codigo:

Modo archivo (FILE):
```
./hikflow_demo_g5 ./config_yolov3_tiny_pytorch.txt FILE
```
Usa las imágenes definidas en el archivo de configuración.
Modo flujo de dispositivo (YUV):
```
./hikflow_demo_g5 ./config_yolov3_tiny_pytorch.txt YUV
```
Usa la entrada de video del dispositivo.

El empaquetado por defecto usa el modo de flujo YUV. Si se desea cambiar a lectura por archivo, es necesario modificar el script hikflowDemo.sh dentro de packapp.

Empaquetado de la aplicación

El proyecto incluye scripts para generar paquetes listos para subir a la cámara:

Versión Release:
```
./MakeAll_release.sh
```
Versión Debug:
```
./MakeAll_debug.sh
```

Estos scripts generan el paquete final en el directorio packapp, listo para importarse al dispositivo.

Proceso de desarrollo

La compilación completa de ambos demos permite observar de manera integral el flujo de construcción de aplicaciones en HEOP, así como las diferencias entre compilar una aplicación inteligente y una aplicación no inteligente.

Estas diferencias se reflejan principalmente en la estructura de directorios, la cantidad de archivos involucrados y las herramientas requeridas para cada tipo de aplicación.

Diferencias entre compilar una aplicacion inteligente y una aplicaciones no inteligente.

Como pudimos ver la diferencia entre la cantidad de directorios y archivos entre una aplicación no inteligente a una inteligente es remarcable, dado que para la creacion de una aplicacion inteligente la cantidad de herramientas y capacidades es mayor teniendo como estuctura basica lo siguiente:

Aplicacion no Inteligente.

Al ingresar al directorio del demo correspondiente, se observa una estructura mínima y sencilla. Generalmente incluye:

Herramientas de compilación necesarias para generar el binario.
Un archivo README con instrucciones de uso.
Un archivo principal .c que contiene la lógica básica de la aplicación.
Un directorio app/ con los componentes adicionales, como:
- Frontend en HTML para la interfaz configurable.
- Scripts asociados a la interfaz.
- Archivos necesarios para el proceso de compilación.

La simplicidad de esta estructura permite realizar modificaciones rápidas: basta con alterar el código fuente o los elementos del frontend para obtener diferentes resultados en la aplicación final sin omitir el proceso de empaquetamiento y subido al dispositivo correspondiente.

Aplicaciones inteligentes.

En contraste, las aplicaciones inteligentes cuentan con una estructura mucho más robusta y extensa, debido a que integran modelos de inteligencia artificial (IA) y requieren mayor cantidad de herramientas. Un ejemplo de estructura es la siguiente:

hikflow/
├── demo/                           #DIRECTORIO PRINCIPAL DE DESARROLLO
│   ├── bin/                       #Binarios del modelo IA
│   ├── build/                     #Configuración de compilación
│   │   ├── makefile_g5           #Makefile para plataforma G5
│   │   └── MakeOption            #Opciones de compilación
│   ├── code/                     #Código fuente del demo
│   ├── custom_layer/             #Capas personalizadas de IA
│   ├── data/                     #Imágenes de prueba
│   ├── config_*.txt              #Archivos de configuración del modelo
│   └── imagelist_*.txt           #Lista de imágenes de prueba
├── G5/                           #SDK ESPECÍFICO PLATAFORMA G5
│   ├── inc/                      #Headers/archivos de cabecera
│   └── lib/                      #Librerías del sistema
├── packapp/                      #Directorio de empaquetado
│   ├── package.conf              #Configuración del paquete
│   └── hikflowDemo.sh           #Script de ejecución
├── model_trans/                  #Herramientas de transformación
├── MakeAll_debug.sh             #Script compilación debug
├── MakeAll_release.sh           #Script compilación release
└── readme.txt                   #Documentación oficial

Dentro de esta estructura, destacan los siguientes puntos:

El directorio code/ contiene todo el código de la aplicación. Aquí se pueden:
- Agregar archivos con nuevas funcionalidades.
- Modificar el archivo demo_alg.c, que implementa la lógica de identificación de objetos y personas.
- Integrar el modelo de detección (por ejemplo, YOLO) y manejar los resultados que se reflejan en los logs del dispositivo.
Para que la compilación y empaquetado sean exitosos, además del código fuente se requieren dos archivos esenciales:
- makefile_g5 → Define el proceso de compilación y generación del binario backend.
- package.conf → Configura el empaquetamiento de la aplicación en formato .app para su despliegue en el dispositivo.

Habiendo hecho el análisis correspondiente se concluye que la diferencia entre ambas aplicaciones proviene directamente de su naturaleza y funcionalidad esperada, teniendo un proceso de ejecución similar en ambos casos, sin embargo, Hikvision ya nos brinda herramientas como manuales y cogido de ejemplo que podemos utilizar para crear nuestras propias soluciones.