RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile
Plantilla para Proyectos en C/C++ del RAL / Estructura y L´ogica del Programa .
1 Objetivos
• Proveer una plantilla con la estructura y l´ogica b´asica para la implementaci´on m´as r´apida de algorit- mos en proyectos del ´area de rob´otica, como algoritmos de control, estimaci´on y otros de adquisici´on, procesamiento e interpretaci´on de datos.
• Fijar un est´andar m´ınimo para los proyectos del grupo RAL que garantice:
– Orden y simplicidad ⇒ claridad. – Modularidad y reusabilidad. – Portabilidad.
2 Descripci´on
La estructura general de toda soluci´on de automatizaci´on requiere de tres pasos fundamentales:
1. Sensado: Medir ciertas variables que se desean controlar.
2. Procesamiento: Procesar los datos medidos para extraer informaci´on de inter´es.
3. Decisi´on/Acci´on: Verificar que las variables de inter´es cumplan un cierto objetivo fijado por el usuario, y de lo contrario, tomar acciones que ajusten las variables de inter´es del sistema.
Las tres etapas anteriores se repiten una y otra vez durante la operaci´on del sistema. Cabe notar que en estas etapas est´an implicitos dos hechos. Primero, que el programa recoge o recibe datos, luego opera sobre estos y finalmente entrega ciertos resultados. Por otra parte, est´a el hecho de que existe un usuario que de alguna manera interactua con el sistema para fijar tanto objetivos como otros par´ametros deseados de operaci´on. En este sentido, la soluci´on puede descomponerse en tareas o funciones de bajo nivel, aquellas encargadas de interactuar con el hardware, y otras de m´as alto nivel encargadas de la interacci´on entre el usuario y la m´aquina. Por lo anterior podemos afirmar que existen por lo menos tres dimensiones principales con respecto a las cuales debe concebirse la soluci´on:
• Entradas-Salidas: Consistente en las especificaciones de datos requeridos por el programa y los resultados que este debe generar.
• Temporal: Relacionada con la secuencia de ejecuci´on de tareas necesarias para obtener los resultados.
• Niveles de abstracci´on de tareas: Relacionada con la separaci´on de las funciones en grupos que abarcan desde la capa f´ısica hasta capas o niveles de abstracci´on mayor que implementan la interacci´on humano- m´aquina. En otras palabras, las capas inferiores implementan lo que en el ´ambito del control autom´atico se conocen como interfaces controlador-proceso, mientras que las capas superiores implementan las interfaces usuario-controlador en alguna forma como una GUI (Graphical User Interface), HMI (Human- Machine Interface), MMI (Man-machine Interface) o una simple CLI (Command-Line Interface).
Para una implementaci´on eficiente, que garantice las caracter´ısticas de claridad, modularidad, reusabilidad del c´odigo, es conveniente dedicar el tiempo que sea necesario a la definici´on clara y precisa de c´omo ser´ıa el programa en cada una de las tres dimensiones anteriores. Esta inversi´on inicial de tiempo siempre es 2008.12.14 1 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL recompensada, pues evita tener que reparar errores de dise˜no o estructuraci´on que de lo contrario ocurren a medio camino. En las siguientes secciones se discuten brevemente las tres dimensiones tomando el programa plantilla PTZ como modelo de referencia. El documento concluye con una serie de recomendaciones para implementaci´on de soluciones seg´un el programa plantilla PTZ para proyectos RAL.
3 Especificaciones Funcionales
En ingenier´ıa de sistemas y desarrollo de software, las especificaciones funcionales (llamadas en ingl´es functional specifications, functional specs o FSD = functional specifications document) corresponden al conjunto de documentos que describen el comportamiento requerido de un cierto sistema de ingenier´ıa. Las espcificaciones funcionales permiten fijar un marco general de trabajo entre diversos programadores de un proyecto y describir lo que se requiere implementar. El documento t´ıpicamente se compone de las siguientes listas con descripciones de las propiedades de los datos y funciones que las componen:
1. Inputs del Usuario: Lista de datos entregados por el usuario a la aplicaci´on. Algunos datos pueden ser variables modificables durante la ejecuci´on a trav´es de la interfaz de usuario, otros datos pueden ser par´ametros establecidos al inicio de la ejecuci´on de la aplicaci´on.
2. Inputs del Entorno/Proceso: Lista de datos requeridos por la aplicaci´on que son obtenidos desde el entorno.
3. Outputs al Usuario: Lista de datos o resultados que son entregados al usuario.
4. Outputs al Entorno/Proceso: Lista de datos que son entregados por la aplicaci´on al entorno de modo que otras partes del entorno o sistema puedan realizar las acciones para las cuales fueron creadas.
5. Funcionalidad: Lista de funciones y comportamientos que debe poseer la aplicaci´on.
2008.12.14 2 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Ejemplo Especificaciones Funcionales PTZ
Nombre de la Aplicaci´on ptz Objetivos Abrir un archivo, secuencia de archivos, archivo de video o captura de una c´amara y seg- mentar cada imagen o cuadro en base a caracter´ısticas de color empleando las componentes de crominancia roja y crominancia azul del espacio de colores YCrCb. Adem´as aplica un proceso simple de detecci´on de bordes a la imagen segmentada. Inputs del Usuario Opciones de l´ınea de comando -h Prints some help. -nv Turns verbose off. -np Do not wait for user to press ESC when done. -nd Do not display images. -no Do not save the output. -e Filename extension [=jpg] -sq initial value final value Tells ptz to process a sequence of images starting at filename
2008.12.14 3 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Outputs al Usuario Segmentation Image containing the segmentation of the input into the differnt classes. Edges Image containing the edges of the segmented input. Outputs al Entorno Segmentation map Image containing the segmentation map (result). Funcionalidad
1. La aplicaci´on detecta en forma autom´atica el tipo de input (archivo ´unico de imagen, secuencia de archivos de video, archivo de video AVI o captura directa de c´amara USB).
2. La imagen puede ser segmentada seg´un las caracter´ısticas de color seleccionadas por el usuario. Para esto el usuario primero debe seleccionar una regi´on de inter´es con Mouse-R+CTRL, luego a˜nadir una clase con ’a’, y actualizar los valores de la clase actual con ’u’. El procesamiento se inicia cuando el usuario presiona ’h’.
Referencias sobre Especificaciones Funcionales
[1] Wikipedia. Functional Specifications. Versi´on 28 de octubre, 2008. http://en.wikipedia.org/wiki/Functional specifications
[2] Allen Smith. Functional Spec Tutorial: What and Why. Visitada 16 de diciembre, 2008. http://www.mojofat.com/tutorial/
4 Estructura Temporal
La estructura temporal se refiere a la secuencia l´ogica de ejecuci´on. Esta puede describirse mediante diagramas de flujo o pseudoc´odigo. Los diagramas de flujo pueden resultar m´as explicativos que los pseudoc´odigos cuando se requiere describir el flujo de datos, pasos de un proceso o sistema con muchas etapas de decisi´on. En cambio los pseudoc´odigos resultan m´as eficaces para describir funciones o algoritmos, los cuales por lo general contienen m´as pasos de c´alculo que etapas de decisi´on. Ejemplos de Pseudoc´odigo Para ilustrar el uso de pseudoc´odigos y diagramas de flujo se presentan a continuaci´on algunos procesos computacionales. El algoritmo 1 corresponde a una descripci´on en pseudoc´odigo de alto nivel de los pasos principales llevados a cabo en el programa PTZ. Esta estructura corresponde a la estructura general de toda aplicaci´on de automatizaci´on, como se explic´oen la secci´on 2. La secuencia de tareas principales realizadas por el programa PTZ tambi´en puede describirse empleando un pseudoc´odigo de bajo nivel como se muestra en el algoritmo 2. La diferencia entre un pseudoc´odigo de alto nivel y uno de bajo nivel yace en que el primero est´aescrito empleando oraciones similares a las del lenguaje habitual de las personas junto con f´ormulas matem´aticas, mientras que el pseudoc´odigo de bajo nivel emplea t´erminos y un lenguaje que asemeja un lenguaje de programaci´on. En un pseudoc´odigo de bajo nivel es habitual observar t´erminos que representan las bifurcaciones condicionales (if-then-else) y otros t´erminos que usualmente se emplean para loops o bucles de programa (for-from-to-do, while-do, do-while o repeat-until). Otro ejemplo de pseudoc´odigo de bajo nivel se muestra en el algoritmo 3. Este ´ultimo algoritmo corresponde a la implementaci´on de la funci´on ComputeSegmentation del programa PTZ. Al comparar el pseudoc´odigo con el c´odigo original en C/C++ de la funci´on, podr´anotar que el pseudoc´odigo es bastante m´as f´acil y r´apido de leer que el c´odigo fuente. 2008.12.14 4 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Finalmente, el pseudoc´odigo de bajo nivel de un proceso general de automatizaci´on se muestra en el programa 4. Cabe destacar que en este caso el pseudoc´odigo de bajo nivel hace uso de una sintaxis similar a la del lenguaje C/C++. Por ejemplo, el inicio y el fin de cada funci´on est´an definidos por los delimitadores {, }, respectivamente. Por otro lado, los comentarios emplean // y las funciones indican el tipo de dato que retornan.
¿Cu´ando utilizar pseudoc´odigo de alto o de bajo nivel? Utilice pseudoc´odigo de alto nivel para describir procesos muy generales o procesos en los que las etapas de decisi´on son pocas o son elementos secundarios del proceso. Un pseudoc´odigo de alto nivel es ideal para entregar una visi´on general de la secuencia de pasos que se debe realizar, sin entrar en los detalles de cada paso. Los pseudoc´odigos de bajo nivel permiten explicar de mejor manera algoritmos y funciones. Los pseudocdigos´ de bajo nivel no ofrecen mayor ventaja para explicar una secuencia general de pasos de un programa o aplicaci´on. Al emplear pseudoc´odigo de bajo nivel, procure utilizar un A lenguaje gen´erico como en los algoritmos 2 y 3. Existen herramientas en LTEX, como el paquete algorith2e que permiten escribir pseudoc´odigo de bajo nivel est´andar (vea el c´odigo fuente de este documento). Evite utilizar pseudoc´odigo de bajo nivel que recurra a t´erminos y sintaxis de un lenguaje de programaci´on espec´ıfico. Recuerde que el prop´osito del pseudoc´odigo es que sea entendido por cualquiera y pueda ser implementado en cualquier lenguaje de programaci´on. Utilice una sintaxis espec´ıfica a un cierto lenguaje solo cuando sea necesario referirse a programas escritos en ese lenguaje, como en ejemplos de programaci´on o aplicaci´on del lenguaje particular.
Algorithm 1: Main Program Structure (High-level Pseudocode) input : Image sequence output: Segmented image using YCrCb color features 1. Initialize data structures
2. Parse command line parameters and update data structures
3. Get the input image Depending on the context some of the typical actions may include commands with names such as: Allocate/Create/Open/Load/Read/Get/Retrieve/Grab/Capture
4. Process image
5. Store the results Depending on the context some of the typical actions may include commands with names such as: Save/Write/Set/Put/Close/Release/Free/Clear/Destroy
6. Show/display results
7. Handle keyboard inputs from user
8. Repeat 3-7 until some ending condition is met, skipping 6 and 7 if no user interaction through CLI or GUI is required in order to save time.
2008.12.14 5 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL
Algorithm 2: Main Program Structure (Low-level Pseudocode) input : Image sequence output: Segmented image using YCrCb color features —— Initialization ——; InitCmdLineStruct(&CmdLineParam); ParseCmdLine(&CmdLineParam); CheckInputType(&CmdLineParam); CreateInputContainer; if &CmdLineParam.display = TRUE then CreateGUI; end InitProcessParam(&ProcessParam); —— Begin Process ——; while (capture)∧(run) do &img ← GetImage(); &img ← ProcessImage(&img, &ProcessParam); StoreImage(&img); if &CmdLineParam.display = TRUE then DisplayImage(); end ProcessKeyboard(); end
Algorithm 3: ProcessImage (Low-level Pseudocode) input : &img (input image), &ProcessParam (process parameters) output: &img (segmented image) &imgaux ← &img; —— ComputeSegmentation ——; for row = 0 to &img.height do for col = 0 to &img.width do for class = 1 to &ProcessParam.Nclasses do if kConvertToYCrCb(&imgaux(row,col))−&ProcessParam.FeatureVector(class)k 2008.12.14 6 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Control Program Procedure double sensor(void) { // Initialize/Connect/Synchronize Sensor Open(SensorParam); Connect(SensorParam); Enable(SensorParam); // Retrieve sensor data measurement = Read(SensorParam); // Other names for this function are Get/Load // Close sensor Disable(SensorParam); Disconnect(SensorParam); Close(SensorParam); return measurement; } Procedure void actuator(double value) { // Initialize/Connect/Synchronize Actuator Open(ActuatorParam); Connect(ActuatorParam); Enable(ActuatorParam); // Set actuator Write(ActuatorParam,value); // Other names for this function are Set/Put // Close actuator Disable(ActuatorParam); Disconnect(ActuatorParam); Close(ActuatorParam); } Procedure void main(int argc, char** argv) { // ------Define constants and parameters ------double measurement; double value; struct {...} SensorParam; struct {...} ActuatorParam; ... // ------Process Loop ------while ( getch() ! = 0x1B) // Wait till ESC is pressed { // ------Read sensor ------measurement = sensor(SensorParam); printf(“Measured value [unit]: %f”, measurement); // ------Write actuator ------value = Process(measurement); actuator(ActuatorParam,value); // ------Read keyboard ------ProcessKeyboard(); } } 2008.12.14 7 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Ejemplos de Diagramas de Flujo El diagrama de flujo del programa plantilla PTZ se muestra en las figuras 1 y 2. Este diagrama de flujo corresponde a los pseudoc´odigos 1 o 2. La comparaci´on del diagrama de flujo con los pseudoc´odigos revela ciertas diferencias que no est´an indicadas en forma expl´ıcita en el pseudoc´odigo. Por una lado, podemos ver que el diagrama de flujo toma par´ametros iniciales de la l´ınea de comando, inicializa las estructuras de datos apropiadas, luego determina si el input a ser procesado es una imagen de archivo o un video de entrada. A continuaci´on verifica si se deben o no desplegar las pantallas con las im´agenes y los resultados procesados, es decir si debe o no desplegar la interfaz gr´afica o graphical user interface (GUI). El proceso, que continua en la figura 2, inicializa otras variables propias de la etapa de procesamiento de las im´agenes y dependiendo de si el usuario indic´oo no la opci´on de generar un resultado de manera “verbosa”, la aplicaci´on informar´a o no al usuario sobre lo que esta se encuentra ejecutando. En el caso en que el procesamiento del input es verboso, las im´agenes se despliegan y el usuario tiene la opci´on de interactuar con la aplicaci´on a trav´es del teclado. Espec´ıficamente, el usuario puede activar o desactivar la realizaci´on del proceso. Cuando el holding esta desactivado (en off), la aplicaci´on procesa las im´agenes. En otras palabras, cuando holding off es verdadero la aplicaci´on deja un modo tipo stand-by en el cual las im´agenes que se obtienen se despliegan al usuario sin ser procesadas. Cuando holding no est´aen off, se tiene holding on, caso que corresponde a la rama izquierda de la bifurcaci´on del programa. En ambos casos, holding off u on, el paso siguiente es verificar si el usuario presion´ola tecla ESC para terminar la aplicaci´on o si se acab´ola secuencia de im´agenes, de lo contrario la aplicaci´on sigue procesando im´agenes indefinidamente en el loop que se cierra antes de la verificaci´on de la condici´on de holding. La figura 3 muestra otro ejemplo de diagrama de flujo. Este diagrama corresponde al algoritmo de proce- samiento de segmentaci´on por color, cuyo pseudoc´odigo se present´oen el algoritmo 3. Una comparaci´on cuidadosa del pseudoc´odigo del algoritmo 3 y el diagrama de flujo 3 permite verificar que efectivamente son equivalentes y hay dos bucles for-from-to-do anidados. Sin embargo, es posible concluir que en este caso la descripci´on del proceso de segmentaci´on mediante un diagrama de flujo es menos eficiente, pues es m´as extensa y no se comprende tan r´apidamente como el pseudoc´odigo que requiere de unas pocas l´ıneas. ¿Cu´ando utilizar un diagrama de flujo y cu´ando un pseudoc´odigo? Como se mencion´o, usualmente conviene utilizar diagramas de flujo para describir la estructura general de una aplicaci´on, mientras que algoritmos y funciones espec´ıficas se pueden expresar de manera m´as concisa mediante pseudoc´odigo. Para crear diagramas A de flujo en LTEX existen diversas herramientas. Se recomienda consultar para mayores detalles y ejemplos el tutorial de la referncia [1] de esta secci´on. Referencias sobre Diagramas de Flujo y Pseudoc´odigo A [1] Miguel Torres Torriti. Creating flowcharts in LTEX Using the pic Language. 21 de diciembre, 2008. Disponible en: http://www.ing.puc.cl/ mtorrest/downloads.htm [2] Wikipedia. Flowchart. Visitada 17 de diciembre, 2008. http://en.wikipedia.org/wiki/Flowchart [3] Wikipedia. Algorithms on Wikipedia. Visitada 17 de diciembre, 2008. http://en.wikipedia.org/wiki/Wikipedia:Algorithms on Wikipedia [4] Wikipedia. Pseudocode. Visitada 17 de diciembre, 2008. http://en.wikipedia.org/wiki/Pseudo-code [5] Wikipedia. Pidgin Code. Visitada 17 de diciembre, 2008. http://en.wikipedia.org/wiki/Pidgin Algol 2008.12.14 8 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Program Initialization Parse Command Line Arguments no Video yes stream? Capture Load image image from from file video source no Display yes GUI? Capture image from video source A Figura 1: Diagrama de flujo del programa PTZ (continua en la figura 2). 2008.12.14 9 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL A Process Initialization yes no Verbose? yes Process input no holding off? Process input no End of yes Display input and input? display results Process keyboard yes Esc key ∨ End of no Input? End Figura 2: Diagrama de flujo del programa PTZ (continuaci´on de la figura 1). 2008.12.14 10 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL &imgaux←&img; p ← (0, 0) no p ∈ DI yes Compute feature vector f(p) c = 0 no c yes no kf(p) − fck < λ yes &img(p)=0 &img(p)=c Increment class c ← c + 1 Update position p ← p + ∆p End Figura 3: Proceso de segmentaci´on de im´agenes por color. 2008.12.14 11 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL 5 Niveles de Abstracci´on La mayor parte de las aplicaciones se puede descomponer al menos en las siguientes categor´ıas de funciones: • Funciones Utilitarias B´asicas / Basic Utility Functions: IntiCmdLineStruct, ParseCmdLine, etc. • Funciones Matem´aticas B´asicas / Basic Math Functions: mvectoralloc, mmatrixalloc, etc. • Funciones del Proceso / Process Functions: AddClass, ComputeSegmentation, etc. • Funciones GUI / GUI Functions: on mouse, proceso de teclado, etc. La lista anterior incluye ejemplos de funciones del programa PTZ que pertenecen a cada categor´ıa. Uno podr´ıa pensar en otras descomposiciones, por ejemplo, funciones de soporte de hardware, funciones de control de acceso a discos, funciones gr´aficas, funciones de acceso a bases de datos, funciones de comunicaci´on entre equipos, etc. Lo importante es establecer una estructura que permita agrupar funciones en archivos que puedan reutilizarse. As´ıla clasificaci´on anterior permitir´ıa tomar las funciones b´asicas de servicio y emplearlas en otro proyecto o emplear las funciones matem´aticas en otro programa, tal como si fuesen funciones de una librer´ıa o toolbox de software. Ejemplo de Diagrama de Niveles de Abstracci´on La figura 5 muestra los distintos niveles de abstracci´on del programa PTZ. Las funciones que aparecen con asterisco (*) no necesariamente est´an implementadas como un procedimiento, sino como l´ıneas dentro del c´odigo, o son funciones con un nombre distinto al que se presenta en la figura 5 con el fin de facilitar la comprensi´on. Es posible ver en el esquema de la figura 5 que existen funciones en distintas categor´ıas que entregan informaci´on al usuario a trav´es de la pantalla. Si bien uno podr´ıa pensar que estas funciones pertenecen a la categor´ıa GUI, considerando el hecho de que el despliegue de datos en pantalla realizado por estas funciones es b´asico (directo al terminal o ventana de comando) y m´as bien son funciones auxiliares de su categor´ıa (permiten visualizar los contenidos de estructuras de datos como vectores o matrices), su clasificaci´on en una categor´ıa distinta a GUI es m´as apropiada. En la categor´ıa GUI solo debieran aparecer funciones que soportan la creaci´on y gesti´on de la interfaz gr´afica de usuario, las cuales habitualmente requieren de librer´ıas propias al entorno de programaci´on utilizado. 6 Recomendaciones Finales 1. Utilice la plantilla PTZ para sus proyectos y aproveche su estructura. En principio solo requiere reemplazar las Funciones del Proceso del programa PTZ (ver figura 5) por sus propias funciones. Si adicionalmente emplea su propia librer´ıa de funciones matem´aticas, como la GNU Scientific Library (GSL), entonces deber´aeliminar las funciones del grupo de Funciones Matem´aticas B´asicas del programa PTZ. 2. Antes de empezar a escribir c´odigo en el computador dedique algo de tiempo a pensar como implementar´a la soluci´on en t´erminos de las tres dimensiones sen˜aladas en este documento. Genere sus especificaciones funcionales, su diagrama de flujo, pseudoc´odigos y esquemas con los niveles o grupos de abstracci´on. Este tiempo invertido lo recuperar´ar´apidamente y ver´aque con la experiencia este enfoque resultar´aser el camino natural y m´as expedito para hacer las cosas bien a la primera. 3. No olvide comentar su c´odigo. Ciertas soluciones a las que uno llega despu´es de pensar mucho resultan obvias o triviales, y con frecuencia su raz´on o la manera de llegar a ellas se olvida, dificult´andose as´ıla posterior comprensi´on y reutilizaci´on del c´odigo. 2008.12.14 12 RAL - Robotics and Automation Laboratory - Prof. M. Torres T. Departamento de Ingenier´ıa Electrica´ Pontificia Universidad Catolica´ de Chile Plantilla para Proyectos en C/C++ del RAL Figura 4: Niveles de abstracci´on. 2008.12.14 13