Integrando Realidad Aumentada en React Native con ViroReact: Guía Completa

La Realidad Aumentada (RA o AR por sus siglas en inglés) ha dejado de ser una fantasía de ciencia ficción para convertirse en una herramienta práctica que enriquece nuestras interacciones con el mundo digital y físico. Integrar RA en tus aplicaciones móviles puede ofrecer experiencias de usuario únicas e inmersivas, y React Native, junto con librerías como ViroReact, hace que este proceso sea sorprendentemente accesible.

Este tutorial te proporcionará una guía completa para comenzar a desarrollar aplicaciones de Realidad Aumentada en React Native utilizando ViroReact. Aprenderás a configurar tu entorno, crear tu primera escena AR, y explorarás algunas de las funcionalidades clave que ofrece esta librería.

🚀 ¿Qué es ViroReact y por qué usarlo para RA?

ViroReact es una plataforma de código abierto que permite a los desarrolladores crear experiencias de Realidad Aumentada (AR) y Realidad Virtual (VR) multiplataforma utilizando React Native. Bajo el capó, ViroReact se encarga de la compleja integración con las APIs nativas de ARKit (iOS) y ARCore (Android), abstrayendo estas complejidades para que puedas centrarte en la lógica de tu aplicación utilizando JavaScript y los componentes de React.

Ventajas clave de ViroReact:

• Multiplataforma: Desarrolla para iOS y Android desde una única base de código.
• React Native: Aprovecha el ecosistema y la familiaridad de React Native.
• Potente: Acceso a capacidades avanzadas de AR/VR como seguimiento de superficie, anclajes, reconocimiento de imágenes y más.
• Componentizado: La interfaz declarativa de React facilita la construcción de escenas 3D y componentes de RA.

🛠️ Requisitos Previos y Configuración del Entorno

Antes de sumergirnos en el código, asegúrate de tener todo lo necesario para empezar. Necesitarás un entorno de desarrollo de React Native ya configurado y un dispositivo móvil compatible con ARKit (iOS 11+) o ARCore (Android 7.0+ y Google Play Services for AR).

1. Entorno de Desarrollo React Native

Si aún no lo tienes, instala Node.js, npm/yarn y el CLI de React Native. Se recomienda usar npx react-native init para crear nuevos proyectos.

npm install -g react-native-cli # Si no lo tienes globalmente
npx react-native init MiProyectoAR
cd MiProyectoAR

2. Instalación de ViroReact

Una vez creado tu proyecto de React Native, instala el paquete react-viro.

yarn add react-viro
# o
npm install react-viro

Después de instalar el paquete, es crucial enlazarlo con los proyectos nativos. ViroReact requiere pasos de configuración específicos para iOS y Android que no se manejan automáticamente por react-native link (que ya está deprecado en RN 0.60+).

Configuración para iOS

1. Instalar CocoaPods: Si no lo tienes, sudo gem install cocoapods.
2. Modificar Podfile: Abre ios/Podfile y añade lo siguiente al final del archivo, antes de end:

target 'ViroSample' do
# ... tus otros pods
pod 'ViroReact', :path => '../node_modules/react-viro/ios'
end

Asegúrate de reemplazar `'ViroSample'` con el nombre de tu proyecto.

3. Instalar Pods: Ve a la carpeta ios y ejecuta pod install. 4. Habilitar ARKit: Abre tu proyecto .xcworkspace en Xcode. En las Capabilities de tu Target, asegúrate de que ARKit esté activado.

Configuración para Android

1. Modificar android/build.gradle (nivel de proyecto): Asegúrate de que los repositorios de Google Maven estén configurados.

buildscript {
repositories {
google()
mavenCentral()
}
dependencies {
classpath("com.android.tools.build:gradle:7.3.1") // Asegúrate de tener una versión reciente
classpath("com.facebook.react:react-native-gradle-plugin")
// ... otros plugins
}
}

allprojects {
repositories {
google()
mavenCentral()
maven { url "https://artifactory.viromedia.com/artifactory/maven" }
}
}

2. Modificar android/app/build.gradle (nivel de módulo):

   • Añade minSdkVersion 24 o superior.
   • Añade las dependencias de ViroReact.

android {
// ...
defaultConfig {
// ...
minSdkVersion 24 // Requerido para ARCore
// ...
}
// ...
}

dependencies {
implementation project(':react-viro')
// Dependencias de ViroReact. Verifica las versiones más recientes en la documentación oficial.
implementation 'com.viromedia.virocore:arcore:1.16.1' // Ejemplo de versión
implementation 'com.viromedia.virocore:gvr:1.16.1'  // Para VR, opcional si solo usas AR
}

<div class="callout warning">⚠️ <strong>Advertencia:</strong> Las versiones de `arcore` y `gvr` en `build.gradle` deben coincidir con la versión de `react-viro` que estás usando. Consulta la documentación oficial de ViroReact para las versiones exactas.</div>

3. Añadir permisos en android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.miproyectoor">

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="true"/>
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<application
android:name=".MainApplication"
android:label="@string/app_name"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:allowBackup="false"
android:theme="@style/AppTheme">

<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
android:launchMode="singleTask"
android:windowSoftInputMode="adjustResize">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
<meta-data android:name="com.google.ar.core" android:value="required" />
</application>

</manifest>

La línea `<meta-data android:name="com.google.ar.core" android:value="required" />` es crucial para que la aplicación reconozca los requisitos de ARCore.

✨ Creando Tu Primera Escena AR con ViroReact

Ahora que el entorno está configurado, podemos empezar a escribir código para nuestra aplicación AR. ViroReact proporciona una serie de componentes de React que puedes usar para construir tu escena 3D.

1. Estructura Básica de la Aplicación

Modifica tu App.js para usar los componentes de ViroReact.

import React, { useState } from 'react';
import {
  ViroARSceneNavigator,
  ViroARScene,
  ViroText,
  ViroConstants,
  ViroBox,
  ViroMaterials,
  ViroAmbientLight,
  ViroSpotLight,
  ViroNode
} from '@viro-community/react-viro';
import { StyleSheet, Text, View, Pressable }
  from 'react-native';

const HelloWorldSceneAR = () => {
  const [text, setText] = useState('¡Hola RA!');

  function onInitialized(state, reason) {
    console.log('onInitialized', state, reason);
    if (state === ViroConstants.TRACKING_NORMAL) {
      setText('¡Rastreo AR Iniciado!');
    } else if (state === ViroConstants.TRACKING_NONE) {
      setText('¡Rastreo AR Detenido!');
    }
  }

  return (
    <ViroARScene onTrackingUpdated={onInitialized}>
      <ViroAmbientLight color="#ffffff" intensity={1000} />
      <ViroSpotLight 
        innerAngle={5}
        outerAngle={90}
        direction={[0,-1,-.2]}
        position={[0, 3, 1]}
        color="#ffffff"
        castsShadow={true}
        influenceBitMask={1}
        shadowMapSize={2048}
        shadowNearClip={2}
        shadowFarClip={5}
        shadowOpacity={.8}
        />
      <ViroNode position={[0, -1, -2]}>
        <ViroText 
          text={text}
          position={[0, 0, 0]}
          width={2}
          height={1}
          color="#FFFFFF"
          style={{ fontFamily: 'Arial', fontSize: 20 }}
        />
        <ViroBox 
          position={[0, -0.5, 0]} 
          scale={[0.5, 0.5, 0.5]}
          materials={["boxMaterial"]}
          rotation={[0, 45, 0]}
        />
      </ViroNode>
    </ViroARScene>
  );
};

ViroMaterials.create({
  boxMaterial: {
    diffuseColor: "#E0E0E0",
    specularColor: "#FFFFFF",
    shininess: 2.0,
  }
});

export default () => {
  return (
    <ViroARSceneNavigator
      autofocus={true}
      initialScene={{ scene: HelloWorldSceneAR }}
      // Puedes añadir un renderLoadingIndicator para una pantalla de carga
      // renderLoadingIndicator={() => <Text>Cargando AR...</Text>}
      style={styles.container}
    />
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Explicación del Código:

• ViroARSceneNavigator: Este es el componente raíz de ViroReact que gestiona las escenas AR/VR. initialScene le indica qué componente de escena renderizar inicialmente.
• ViroARScene: Representa la escena de Realidad Aumentada. El prop onTrackingUpdated es crucial para saber cuándo el sistema de AR ha iniciado o detenido el rastreo del entorno.
• ViroAmbientLight y ViroSpotLight: Son componentes de iluminación. Es fundamental incluir alguna forma de iluminación para que los objetos 3D sean visibles y tengan sombras realistas en tu escena.
• ViroNode: Es un contenedor sin forma visible, similar a un View en React Native. Se usa para agrupar otros componentes 3D y aplicar transformaciones (posición, rotación, escala) a un conjunto de ellos.
• ViroText: Permite mostrar texto en 3D dentro de tu escena AR. Puedes ajustar su posición, tamaño y color.
• ViroBox: Es uno de los muchos objetos 3D primitivos que ViroReact ofrece (otros incluyen ViroSphere, ViroCylinder, Viro3DObject para modelos GLTF/OBJ, etc.). Le asignamos un material definido en ViroMaterials.
• ViroMaterials.create: Define materiales que pueden ser aplicados a objetos 3D. Esto controla cómo el objeto interactúa con la luz y su apariencia visual.

2. Ejecutando la Aplicación

Una vez que hayas modificado App.js, puedes ejecutar tu aplicación.

npm run ios
# o
npm run android

Si todo está configurado correctamente, la aplicación debería iniciarse en tu dispositivo. Apunta la cámara a una superficie plana (como una mesa o el suelo) y, después de un momento, deberías ver el texto "¡Rastreo AR Iniciado!" y un cubo flotando en el espacio virtual, anclado a tu entorno real.

💡 Interactividad y Objetos 3D Personalizados

Una vez que tienes objetos básicos en la escena, el siguiente paso es añadir interactividad y modelos 3D más complejos.

1. Añadiendo Interactividad

Los componentes de ViroReact exponen eventos como onClick, onDrag, onHover, etc., que te permiten responder a las interacciones del usuario.

Modifiquemos el ViroBox para que cambie de color al ser clickeado:

// ... dentro de HelloWorldSceneAR ...

const [boxColor, setBoxColor] = useState('#E0E0E0');

// ...

// Modificamos ViroMaterials para que el color sea dinámico
ViroMaterials.create({
  boxMaterial: {
    diffuseColor: boxColor, // Usamos el estado aquí
    specularColor: "#FFFFFF",
    shininess: 2.0,
  },
  clickedMaterial: {
    diffuseColor: "#FF0000", // Rojo cuando es clickeado
    specularColor: "#FFFFFF",
    shininess: 2.0,
  }
});

// ... dentro del return de HelloWorldSceneAR ...

<ViroBox 
  position={[0, -0.5, 0]} 
  scale={[0.5, 0.5, 0.5]}
  materials={[boxColor === '#E0E0E0' ? "boxMaterial" : "clickedMaterial"]}
  rotation={[0, 45, 0]}
  onClick={() => setBoxColor(prevColor => prevColor === '#E0E0E0' ? '#FF0000' : '#E0E0E0')}
/>

Ahora, al tocar el cubo en la pantalla, su color debería alternar entre gris y rojo.

2. Importando Modelos 3D (GLTF/OBJ)

ViroReact soporta la importación de modelos 3D en formatos populares como GLTF (.gltf/.glb) y OBJ (.obj/.mtl). Esto te permite usar modelos creados en software como Blender, Sketchfab o TurboSquid.

1. Añade tus modelos: Crea una carpeta res (o assets) en la raíz de tu proyecto React Native y coloca allí tus archivos .gltf, .glb, .obj, .mtl y texturas asociadas.
2. Importa el componente Viro3DObject:

// ... en tus imports de ViroReact
import { Viro3DObject } from '@viro-community/react-viro';

// ... dentro de HelloWorldSceneAR, por ejemplo:
<Viro3DObject
source={require('./res/astronaut/astronaut.gltf')} // Ruta a tu archivo GLTF
resources={[require('./res/astronaut/astronaut.bin'), require('./res/astronaut/texture.jpg')]}
position={[0, -0.5, -1]}
scale={[0.1, 0.1, 0.1]}
type="GLTF"
lightReceivingBitMask={1}
shadowCastingBitMask={2}
onClick={() => console.log('Astronauta clickeado!')}
/>

<div class="callout important">🔥 <strong>Importante:</strong> Para los modelos GLTF, a menudo necesitarás especificar los `resources` adicionales (archivos `.bin`, texturas) que acompañan al archivo `.gltf` principal. Para OBJ, asegúrate de que el `.mtl` y las texturas estén en la misma carpeta.</div>

🎯 Anclajes y Detección de Superficies

Una de las características más potentes de la RA es la capacidad de anclar objetos al mundo real, de modo que parezcan estar fijos en una superficie o en un punto específico del espacio. ViroReact abstrae las complejidades de ARKit/ARCore para esto.

ViroARPlaneSelector y ViroARPlane

Estos componentes te permiten detectar planos en el entorno del usuario (suelos, mesas, paredes) y colocar objetos sobre ellos de forma interactiva.

import React, { useState } from 'react';
import {
  ViroARSceneNavigator,
  ViroARScene,
  ViroText,
  ViroConstants,
  ViroBox,
  ViroMaterials,
  ViroAmbientLight,
  ViroSpotLight,
  ViroNode,
  ViroARPlaneSelector,
  ViroDirectionalLight
} from '@viro-community/react-viro';
import { StyleSheet, Text, View, Pressable }
  from 'react-native';

const InteractiveARScene = () => {
  const [text, setText] = useState('Buscando superficies...');
  const [modelPosition, setModelPosition] = useState([0, 0, 0]);

  function onInitialized(state, reason) {
    if (state === ViroConstants.TRACKING_NORMAL) {
      setText('Encuentra una superficie plana para colocar el objeto.');
    }
  }

  function onPlaneSelected(anchor) {
    console.log('Plano seleccionado:', anchor);
    setModelPosition([anchor.position[0], anchor.position[1] + 0.1, anchor.position[2]]); // Elevar un poco del plano
    setText('Objeto colocado!');
  }

  return (
    <ViroARScene onTrackingUpdated={onInitialized}>
      <ViroAmbientLight color="#ffffff" intensity={1000} />
      <ViroDirectionalLight color="#ffffff" direction={[0, -1, -0.5]} />

      <ViroText 
        text={text}
        position={[0, 0, -2]}
        width={2}
        height={1}
        color="#FFFFFF"
        style={{ fontFamily: 'Arial', fontSize: 20 }}
      />

      <ViroARPlaneSelector
        onPlaneSelected={onPlaneSelected}
        maxPlanes={1} // Detección de un solo plano a la vez
      >
        {/* Este contenido se renderiza en la posición del plano detectado */}
        <ViroNode position={modelPosition}>
            <ViroBox 
              position={[0, 0, 0]} 
              scale={[0.3, 0.3, 0.3]}
              materials={["boxMaterial"]}
              rotation={[0, 0, 0]}
              onClick={() => console.log('Cubo en plano clickeado!')}
            />
        </ViroNode>
      </ViroARPlaneSelector>
    </ViroARScene>
  );
};

ViroMaterials.create({
  boxMaterial: {
    diffuseColor: "#8888FF",
    specularColor: "#FFFFFF",
    shininess: 2.0,
  }
});

export default () => {
  return (
    <ViroARSceneNavigator
      autofocus={true}
      initialScene={{ scene: InteractiveARScene }}
      style={styles.container}
    />
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

En este ejemplo, ViroARPlaneSelector detectará automáticamente un plano. Cuando el usuario toque ese plano, la función onPlaneSelected se activará, recibiendo información sobre el ancla del plano, incluyendo su posición. Luego, utilizamos esta posición para renderizar un ViroBox en el lugar seleccionado.

⚖️ Comparativa de Librerías AR en React Native

Aunque ViroReact es una excelente opción, es bueno conocer otras alternativas, cada una con sus pros y contras.

✅ Buenas Prácticas y Consejos Avanzados

Para desarrollar aplicaciones AR robustas y eficientes, considera los siguientes puntos:

• Optimización de Modelos 3D: Los modelos complejos con muchos polígonos o texturas de alta resolución pueden afectar el rendimiento. Usa herramientas como Blender o MeshLab para optimizar tus modelos para dispositivos móviles.
• Iluminación Realista: La iluminación es clave para que los objetos virtuales se integren bien en el mundo real. Experimenta con diferentes tipos de luces (ViroAmbientLight, ViroSpotLight, ViroDirectionalLight) y sombras (castsShadow, receivesShadow).
• Manejo de Estados: Utiliza el estado de React para controlar la visibilidad, posición y propiedades de tus objetos AR, permitiendo una interfaz dinámica.
• Experiencia de Usuario: Guía al usuario. Inicialmente, muestra mensajes como "Mueve tu dispositivo para encontrar superficies" para ayudar al sistema AR a calibrarse.
• Pruebas en Dispositivos Reales: Siempre prueba tus aplicaciones AR en dispositivos físicos, ya que los emuladores no pueden replicar completamente la experiencia AR.
• Manejo de Errores: Considera escenarios donde ARKit/ARCore no están disponibles en el dispositivo del usuario o los permisos de la cámara no se conceden.

🔚 Conclusión

Integrar Realidad Aumentada en tus aplicaciones React Native con ViroReact es una forma fantástica de crear experiencias interactivas y futuristas. Desde la detección básica de superficies hasta la colocación de modelos 3D complejos y la interactividad, ViroReact ofrece un conjunto de herramientas potente y familiar para los desarrolladores de React Native.

Esperamos que esta guía te haya proporcionado una base sólida para comenzar tu viaje en el desarrollo de RA. ¡Ahora es tu turno de experimentar y crear experiencias AR increíbles!