PDF de programación - Tutorial de uso de OHAE sobre windows

Guión 6. Versión 0

Tutorial de uso de OHAE sobre windows

Este tutorial ha sido generado gracias al trabajo de María Luisa Pinto Salamanca, de la

Universidad Nacional de Colombia

Resumen. Se distinguen dos partes:

•

•

una primera donde se explica la instalación bajo windows de la librería y el desarrollo de
aplicaciones en C++,
Se presenta un ejemplo de aplicación de las librerías Open Haptics para el manejo de un
dispositivo háptico Phantom Omni ® de SensAble Technologies, con OpenGL como una
interface de programación para creación de un entorno virtual 3D en tiempo real.

Prerrequisitos:
Se requiere la instalación previa de un programa de compilación de C++, en este caso, los ejemplos
fueron desarrollados con Microsoft Visual Studio 2005.

PARTE 1. Openhaptics ® SDK:
El OpenHaptics ® SDK permite desarrollar aplicaciones de software para el manejo de los
dispositivo hápticos Phantom® de SensAble Technologies, sobre el lenguaje de programación C++.
Incluye el conjunto de librerías HDAPI (Haptic Device API), HLAPI (Haptic Library
API), Utilidades, Controladores del Dispositivo (PHANTOM Device Drivers PDD) y ejemplos de
códigos fuente (ver figura 1) [1].

Figura 1. Arquitectura OpenHaptics ® Toolkit [refoh]

Versión de trabajo e Instalación:

-

-

-

Si se va a trabajar con la versión OpenHaptics Academic Edición (OHAE) copiar el archivo
comprimido OHAE_Windows_v2.zip.
Instalar los controladores del dispositivo: OHAE_Windows_v2\PHANTOM Device Drivers
setup.exe
Instalar Open Haptics desde \OHAE_Windows_v2\OpenHaptics Academic Edition
setup.exe.

- El directorio de los ejemplos de construcción y compilación se realizaran teniendo en cuenta

© OpenSurg 2009

Guión 6. Versión 0

que el directorio de instalación de SensAble será C:\Archivos de programa\SensAble).
- Verificar desde la barra de inicio que se hayan instalado las aplicaciones SensAble Dice

Demo y Phantom Test.
OpenHaptics Academic Edition: API reference, Programmer’s Guide, y Simple Source Code

guide.

Construcción y compilación de una aplicación con Microsoft Visual Studio:

 Si es MSVC 6.0:

o Generar un nuevo proyecto.
o Enlazar ejecución multi-hilo.
o Incluir el path o directorios adicionales, para el caso

$(3DTOUCH_BASE)\include Main include directory for the HD library.
$(3DTOUCH_BASE)\utilities\include Include directory for utilities.

o Adicionar las librerías requeridas como entrada para la ejecución del programa, por

ejemplo:

hd.lib Release version of HDAPI

hdu.lib Release version of HDU library (HD Utilities)
hdud.lib Debug version of HDU library (HD Utilities)


ii. Si es MSVC 2005:

o Generar un nuevo proyecto con con MSVisualC++ por ejemplo ir a File New
o Inclusión de librerías de OpenHaptics: Nombre del Proyecto Property Pages 

Project  Win32 Console Application  Empty Project.

Configuration Properties  C/C++  General  Additional Include Directories:
include,$(3DTOUCH_BASE)\include,$(3DTOUCH_BASE)\utilities\include.

o Incluir las librerías de enlace: Nombre del Proyecto Property Pages 

Configuration Properties  Linker  General  Additional Library Directories:
$(3DTOUCH_BASE)\lib,$(3DTOUCH_BASE)\utilities\lib.

o Incluir las dependencias adicionales: Nombre del Proyecto Property Pages 

Configuration Properties  Linker  Input  Additional Dependencies: hl.lib
hlud.lib hd.lib hdu.lib glut32.lib.

o Incluir como los archivos de cabecera de Open haptics necesarios para la aplicación,

por ejemplo:

#include <HL/hl.h>
#include <HDU/hduMath.h>
#include <HLU/hlu.h>
#include <HD/hd.h>
#include <HDU/hdu.h>

 NOTA: Pueden haber problemas de enlace al compilar el proyecto con una versión de Visual

Studio superior a la 6.0, porque puede ser que las librerías de Open Haptics hayan sido
compiladas desde una versión inferior a msvs 8.0. Después de convertir el proyecto, para
solucionar errores como: “hduError.obj”:
Ir a C:\Archivos de programa\SensAble\3DTouch\utilities\src\HDU

-
- Abrir el proyecto HDU.vcproj
- Convertilo si es necesario.

© OpenSurg 2009

Guión 6. Versión 0

-
-

-

Solucionarlo (Release) y depurarlo.
Ir a C:\Archivos de programa\SensAble\3DTouch\utilities\src\HDU\Debug y copiar los
archivos *.lib (para el caso HDUD.lib) en la carpeta predeterminada para la compilación. Si
ya esta generado mejor.
Ir nuevamente al proyecto que generaba el error (hduError.obj) y volver a compilarlo.

HDAPI:

La librería HDAPI permite además de otras utilidades, el acceso a bajo nivel al Phantom Omni®,
ofreciendo al programador la posibilidad de renderizar fuerzas directamente; configurar los
controladores en tiempo de ejecución; leer el estado (posición, velocidad, fuerza aplicada), entre
otras [2]. A través de HD se puede integrar el dispositivo háptico en diferentes aplicaciones
desarrolladas sobre C o C++, para la manipulación de sólidos generados a partir de imágenes de
otros paquetes gráficos o de librerías especializadas que incluyan propiedades de deformación o
colisión (por ejemplo VTK [3], Open Tissue [4], VCollide [5], etc.).

Figura 2. Arquitectura HDAPI [2].

La arquitectura de HDAPI se muestra en la figura 2. Algunas de las posibilidades de programación
ofrecidas con esta librería son [6]:

- Leer el estado del dispositivo (Get Identification, Safety, Last Values Parameters):

o Modelo versión, numero de serie
o Dimensiones del espacio de trabajo y GDL
o Temperatura de los motores
o Niveles máximas de dureza, fuerza y velocidad

© OpenSurg 2009

Guión 6. Versión 0

o Entradas digitales: Posición de los interruptores

- Configurar el estado del dispositivo (Set Forces, Safety Parameters):

o Asignar fuerzas y par motor en el espacio cartesiano
o Valor de velocidad a los motores DAC

-

Scheduler (Scheduler Priority Codes):

o Definir callbacks asíncronas y síncronas
o Definir un Scheduler y sus callback según los requerimientos del usuario
o Facilita la sincronización de los hilos grafico y háptico
o Definir la frecuencia del hilo háptico (servo loop rate)

- Opciones de habilitación / deshabilitación (hdEnable, hdDisable Parameters):

o Fuerzas y velocidades de salida, parámetros máximos
o 1 Salida digitales para el led del dispositivo

- Manejador de errores (Device Error Codes)

o Funciones
o Valores inválidos
o Niveles máximos
o Configuración del dispositivo
o Scheduler

- Funciones de calibración (Calibration Return Codes, Styles):

o Manual
o Automática

La figura 3 muestra el diagrama de flujo que debe seguirse para generar una aplicación de
renderizado de fuerzas con objetos virtuales. De forma general el procedimiento consiste en:

i. Inicializar el dispositivo.
ii. Crear el Scheduler con sus callback necesarias para definir los efectos de fuerza.
iii. Habilitar la salida de fuerzas.
vi. Iniciar el Scheduler.
v. Actualizar posiciones e iniciar efectos de fuerza.

Suponiendo que el cursor háptico colisiona con un objeto de la escena virtual, e inmediatamente
después de esto el cursor es desplazado a un lugar donde no hay colisiones, durante este tiempo la
CPU realiza una serie de cálculos para tratar la colisión: compara la posición del cursor con la
posición de los objetos virtuales, pregunta el estado del dispositivo, determina las fuerzas adecuadas
y envía las órdenes para su generación.

Si la escena no garantiza un mínimo de estabilidad, puede ocurrir que el envío de fuerzas se realice
de forma inadecuada, por ello debe generarse un entorno que se mantenga estable durante el tiempo
que la CPU está realizando los cálculos, en este concepto se basa la existencia de los marcos. El
marco háptico es una herramienta que garantiza estabilidad en el entorno de simulación durante el

© OpenSurg 2009

Guión 6. Versión 0

tiempo en el que se están realizando los cálculos para el renderizado de la escena. Se crea
encapsulando las instrucciones de renderizado entre las llamadas a hdBeginFrame y hdEndFrame.

El Servoloop se refiere al lazo o bucle de control encargado de calcular las fuerzas y enviarlas el
dispositivo haptico. Para una realimentación táctil estable, este bucle se debe ejecutar en una tasa de
1 kHz, por lo que generalmente debe ejecutarse en un hilo diferente (Servo Thread) del renderizado
grafico (que se ejecuta a 30Hz aprox.).

© OpenSurg 2009

Guión 6. Versión 0

HLAPI:

La librería HLAPI Haptic Library API proporciona una programación a alto nivel del Phantom
Omni® [7]. Incluye funciones de renderizado háptico para aplicaciones gráficas desarrolladas con
OpenGL, permitiendo especificar sobre primitivas geométricas tales como triángulos, líneas y
puntos, con propiedades como rigidez y fricción, facilitando además la integración con entornos
virtuales cuyo código ya ha sido implementado.

La figura 4 presenta la arquitectura de HLAPI, a través de la cual se oculta al desarrollador de
operaciones control del entorno: la sincronización entre de hilos háptico y grafico, detección de
colisiones, cálculo y generación de fuerzas sobre un punto de contacto virtual (proxy). Algunas de
las posibilidades de programación ofrecidas con esta librería son [6]:

- Renderizado de fuerzas dependientes del movimiento; constante, modelo masa muelle,

amortiguador, fricción, inercia, etc.

- Especificación de las propiedades físicas sobre los materiales superficiales: fricción, dureza,

amortiguamiento, sensibilidad de todas las caras, etc.

- Definición y atención a gráficos y hapticos complementarios a la aplicación: para Windows

incluye la posibilidad que el dispositivo se comporte como un ratón 2d; entradas digitales
(interruptores del phamton), contactos virtuales (touch, untouch), etc.

El procedimiento para generar una aplicación con HLAPI (figura 5) se resume en:

Figura 4. Arquitectura HLAPI [7].

Inicializar el dispositivo