# Package com.codename1.ar

package com.codename1.ar

Cross-platform augmented reality: world tracking, plane detection, hit testing, anchors, 3D content placement, light estimation, image tracking and face tracking, backed by ARKit on iOS and ARCore on Android.

Start at `AR`: check `AR#isSupported()` and per-feature `AR#getCapabilities()`, then `AR#open(ARSessionOptions)` a session and add its `ARSession#createView()` to a form. Place content by hit testing screen taps (`ARSession#hitTest(float, float)`), creating an `ARAnchor` at a hit and attaching an `ARNode` holding an `ARModel` (glTF or `com.codename1.gpu.Mesh` geometry).

Coordinates: world space is right-handed, in meters, with Y up and -Z forward from the initial camera direction - the convention shared by ARKit and ARCore. Poses are `ARPose` (translation + quaternion), convertible to `com.codename1.gpu.Matrix4` compatible matrices.

Threading: all listeners fire on the EDT and all getters reflect the latest delivered state. High-frequency refinements are coalesced.

Permissions and dependencies: referencing this package makes the build pipeline inject the camera permission and plist usage description plus the platform AR dependency into the application automatically; apps that do not use AR pay no cost. Devices without AR hardware report `AR#isSupported()` false, as do the simulator-less desktop targets - the Codename One simulator itself ships a simulated AR environment for development.

- Class
  Description
  AR
  Entry point for the cross-platform augmented reality API.
  ARAnchor
  A fixed position and orientation in the real world that the AR session keeps tracking as its understanding of the environment improves.
  ARAnchorEvent
  Describes a change to an `ARAnchor`, delivered to `ARAnchorListener`s on the EDT.
  ARAnchorEvent.Kind
  The kind of change that occurred.
  ARAnchorListener
  Observes anchor changes, including platform-recognized images and faces.
  ARCapabilities
  Describes which AR features the current device supports.
  ARFaceAnchor
  An anchor tracking a face in a `ARTrackingMode#FACE` session.
  ARFaceRegion
  Named face regions whose poses can be queried from an `ARFaceAnchor`.
  ARHitResult
  One intersection returned by `ARSession#hitTest(float, float)`: the world pose where the ray from the screen point met real-world geometry.
  ARHitResult.Type
  The kind of real-world geometry the hit ray intersected.
  ARImageAnchor
  An anchor tracking a recognized `ARReferenceImage` in the real world.
  ARLightEstimate
  An estimate of the real-world lighting around the device, used to shade virtual content so it blends with the camera image.
  ARModel
  The renderable content of an `ARNode`: geometry plus an optional base-color texture or solid color.
  ARNode
  A node in the small scene graph rendered at an `ARAnchor`.
  ARPlane
  A real-world surface detected by the AR session, such as a floor, table or wall.
  ARPlane.Type
  The orientation of a detected plane.
  ARPlaneDetection
  Which real-world surface orientations an `ARSession` should detect and report as `ARPlane`s.
  ARPlaneEvent
  Describes a change to a detected `ARPlane`, delivered to `ARPlaneListener`s on the EDT.
  ARPlaneEvent.Kind
  The kind of change that occurred.
  ARPlaneListener
  Observes plane detection.
  ARPose
  An immutable rigid transform - a rotation followed by a translation - that positions something in AR world space.
  ARReferenceImage
  A 2D image the AR session should recognize in the real world - a poster, a game board, a product label.
  ARSession
  Active augmented reality session.
  ARSessionOptions
  Configuration for an `ARSession`.
  ARTrackingFailureReason
  Why an `ARSession` reports `ARTrackingState#LIMITED` or `ARTrackingState#NOT_TRACKING`.
  ARTrackingListener
  Observes changes to a session's overall tracking quality.
  ARTrackingMode
  The tracking configuration of an `ARSession`.
  ARTrackingState
  The quality of pose tracking for an `ARSession` or an individual trackable such as an `ARAnchor` or `ARPlane`.
  ARView
  Component that renders the AR camera image composited with the session's anchored 3D content.