unreal.ARLibrary

class unreal.ARLibrary(outer: Object | None = None, name: Name | str = 'None')

Bases: BlueprintFunctionLibrary

ARBlueprint Library

C++ Source:

  • Module: AugmentedReality

  • File: ARBlueprintLibrary.h

classmethod add_manual_environment_capture_probe(location, extent) bool

Adds an environment capture probe to the ar world

Parameters:
Return type:

bool

classmethod add_runtime_candidate_image(session_config, candidate_texture, friendly_name, physical_width) ARCandidateImage

Create an ARCandidateImage object and add it to the ARCandidateImageList of the given c UARSessionConfig object.

Note that you need to restart the AR session with the c UARSessionConfig you are adding to to make the change take effect.

On ARCore platform, you can leave the PhysicalWidth to 0 if you don’t know the physical size of the image or the physical size is dynamic. And this function takes time to perform non-trivial image processing (20ms - 30ms), and should be run on a background thread.

Parameters:
Returns:

A c UARCandidateImage Object pointer if the underlying ARPlatform added the candidate image at runtime successfully. Return nullptr otherwise.

Return type:

ARCandidateImage

classmethod add_tracked_point_with_name(world_transform, point_name, delete_points_with_same_name=True) bool

Manually add a tracked point with name and world transform. WorldTransform:: transform in the world space where the point should be created. PointName:: the name of the created point, must be non-empty. bDeletePointsWithSameName:: if existing points with the same name should be deleted.

Parameters:
  • world_transform (Transform) –

  • point_name (str) –

  • delete_points_with_same_name (bool) –

Returns:

if the operation succeeds. Note that this is an async operation - the added point won’t be available until a few frames later.

Return type:

bool

classmethod calculate_alignment_transform(transform_in_first_coordinate_system, transform_in_second_coordinate_system) Transform

Computes a transform that aligns two coordinate systems. Requires the transform of the same known point in each coordinate system.

Parameters:
  • transform_in_first_coordinate_system (Transform) –

  • transform_in_second_coordinate_system (Transform) –

Returns:

alignment_transform (Transform):

Return type:

Transform

classmethod calculate_closest_intersection(start_points, end_points) Vector

Alignment helpers

Parameters:
Returns:

closest_intersection (Vector):

Return type:

Vector

classmethod debug_draw_pin(ar_pin, world_context_object, color=[1.000000, 1.000000, 0.000000, 0.750000], scale=5.000000, persist_for_seconds=0.000000) None

Given a c UARPin, draw it for debugging purposes.

Parameters:
classmethod debug_draw_tracked_geometry(tracked_geometry, world_context_object, color=[1.000000, 1.000000, 0.000000, 0.750000], outline_thickness=5.000000, persist_for_seconds=0.000000) None

Given some real-world geometry being tracked by the Augmented Reality system, draw it on the screen for debugging purposes (rudimentary)

Parameters:
classmethod find_tracked_points_by_name(point_name) Array[ARTrackedPoint]
Parameters:

point_name (str) –

Returns:

a list of the tracked points with the given name

Return type:

Array[ARTrackedPoint]

classmethod get_alignment_transform() Transform
Returns:

the alignment transform, see “SetAlignmentTransform”

Return type:

Transform

classmethod get_all_geometries() Array[ARTrackedGeometry]
Returns:

a list of all the real-world geometry as currently seen by the Augmented Reality system

Return type:

Array[ARTrackedGeometry]

classmethod get_all_geometries_by_class(geometry_class) Array[ARTrackedGeometry]
Parameters:

geometry_class (type(Class)) –

Returns:

a list of all the real-world geometry of the specified class as currently seen by the Augmented Reality system

Return type:

Array[ARTrackedGeometry]

classmethod get_all_pins() Array[ARPin]

Get a list of all the c UARPin objects that the Augmented Reality session is currently using to connect virtual objects to real-world, tracked locations.

Return type:

Array[ARPin]

classmethod get_all_tracked2d_poses() Array[ARPose2D]
Returns:

all the 2D poses tracked by the AR system

Return type:

Array[ARPose2D]

classmethod get_ar_session_status() ARSessionStatus

It is intended that you check the status of the Augmented Reality session on every frame and take action accordingly. e.g. if the session stopped for an unexpected reason, you might give the user a prompt to re-start the session

Returns:

The status of a current Augmented Reality session: e.g. Running or Not running for a specific reason.

Return type:

ARSessionStatus

classmethod get_ar_texture(texture_type) ARTexture
Parameters:

texture_type (ARTextureType) –

Returns:

the AR texture for the specified type

Return type:

ARTexture

classmethod get_ar_world_scale() float
Returns:

the AR world scale, see “SetARWorldScale”

Return type:

float

classmethod get_camera_intrinsics() ARCameraIntrinsics or None
Returns:

the intrinsics of the AR camera.

out_camera_intrinsics (ARCameraIntrinsics):

Return type:

ARCameraIntrinsics or None

classmethod get_current_light_estimate() ARLightEstimate

An AugmentedReality session can be configured to provide light estimates. The specific approach to light estimation can be configured by the c UARSessionConfig specified during c StartARSession(). This function assumes that you will cast the returned c UARLightEstimate to a derived type corresponding to your session config.

Returns:

a c UARLighEstimate that can be cast to a derived class.

Return type:

ARLightEstimate

classmethod get_number_of_tracked_faces_supported() int32
Returns:

the max number of faces can be tracked at the same time

Return type:

int32

classmethod get_object_classification_at_location(world_location, max_location_diff=10.000000) (out_classification=ARObjectClassification, out_classification_location=Vector) or None

Try to determine the classification of the object at a world space location InWorldLocation:: the world location where the classification is needed OutClassification:: the classification result OutClassificationLocation:: the world location at where the classification is calculated MaxLocationDiff:: the max distance between the specified world location and the classification location return:: whether a valid classification result is calculated

Parameters:
  • world_location (Vector) –

  • max_location_diff (float) –

Returns:

out_classification (ARObjectClassification):

out_classification_location (Vector):

Return type:

tuple or None

classmethod get_point_cloud() Array[Vector]
Returns:

the raw point cloud view of the AR scene

Return type:

Array[Vector]

classmethod get_session_config() ARSessionConfig
Returns:

the configuration that the current session was started with.

Return type:

ARSessionConfig

classmethod get_supported_video_formats(session_type) Array[ARVideoFormat]
Parameters:

session_type (ARSessionType) –

Returns:

The list of supported video formats for this device

Return type:

Array[ARVideoFormat]

classmethod get_tracking_quality() ARTrackingQuality
Returns:

how well the tracking system is performing at the moment

Return type:

ARTrackingQuality

classmethod get_tracking_quality_reason() ARTrackingQualityReason
Returns:

The reason for the current limited tracking state

Return type:

ARTrackingQualityReason

classmethod get_world_mapping_status() ARWorldMappingState
Returns:

the current world mapping status for the AR world

Return type:

ARWorldMappingState

classmethod is_ar_pin_local_store_ready() bool

Is ARPin Local Store Ready

Returns:

True if local store is ready for use.

Return type:

bool

classmethod is_ar_pin_local_store_supported() bool

Is ARPin Local Store Supported

Returns:

True if Local Pin saving is supported by the device/platform.

Return type:

bool

classmethod is_ar_supported() bool

Checks if the current device can support AR

Return type:

bool

classmethod is_scene_reconstruction_supported(session_type, scene_reconstruction_method) bool
Parameters:
Returns:

if a particular scene reconstruction method is supported with the specified session type on the current platform

Return type:

bool

classmethod is_session_tracking_feature_supported(session_type, session_tracking_feature) bool
Parameters:
Returns:

if a particular session feature is supported with the specified session type on the current platform

Return type:

bool

classmethod is_session_type_supported(session_type) bool

Test whether this type of session is supported by the current Augmented Reality platform. e.g. is your device capable of doing positional tracking or orientation only?

Parameters:

session_type (ARSessionType) –

Return type:

bool

classmethod is_wmr_anchor_store_ready() bool

deprecated: ‘is_wmr_anchor_store_ready’ was renamed to ‘is_ar_pin_local_store_ready’.

classmethod line_trace_tracked_objects(screen_coord, test_feature_points=True, test_ground_plane=True, test_plane_extents=True, test_plane_boundary_polygon=True) Array[ARTraceResult]

Perform a line trace against any real-world geometry as tracked by the AR system.

Parameters:
  • screen_coord (Vector2D) – Coordinate of the point on the screen from which to cast a ray into the tracking space.

  • test_feature_points (bool) –

  • test_ground_plane (bool) –

  • test_plane_extents (bool) –

  • test_plane_boundary_polygon (bool) –

Returns:

a list of c FARTraceResult sorted by distance from camera.

Return type:

Array[ARTraceResult]

classmethod line_trace_tracked_objects3d(start, end, test_feature_points=True, test_ground_plane=True, test_plane_extents=True, test_plane_boundary_polygon=True) Array[ARTraceResult]

Perform a line trace against any real-world geometry as tracked by the AR system.

Parameters:
  • start (Vector) – Start point of the trace, in world space.

  • end (Vector) – End point of the trace, in world space.

  • test_feature_points (bool) –

  • test_ground_plane (bool) –

  • test_plane_extents (bool) –

  • test_plane_boundary_polygon (bool) –

Returns:

a list of c FARTraceResult sorted by distance from camera.

Return type:

Array[ARTraceResult]

classmethod load_ar_pins_from_local_store() Map[Name, ARPin]

Load all ARPins from local save Note: Multiple loads of a saved pin may result in duplicate pins OR overwritten pins. It is reccomended to only load once.

Returns:

Map of SaveName:ARPin.

Return type:

Map[Name, ARPin]

classmethod pause_ar_session() None

Pause a running Augmented Reality session without clearing existing state.

classmethod pin_component(component_to_pin, pin_to_world_transform, tracked_geometry=None, debug_name='None') ARPin

Pin an Unreal Component to a location in tracking spce (i.e. the real world).

Parameters:
  • component_to_pin (SceneComponent) – The component that should be pinned.

  • pin_to_world_transform (Transform) – A transform (in Unreal World Space) that corresponds to a physical location where the component should be pinned.

  • tracked_geometry (ARTrackedGeometry) – An optional, real-world geometry that is recognized by the AR system; any correction to the position of this geometry will be applied to the pinned component.

  • debug_name (Name) – An optional name that will be displayed when this pin is being drawn for debugging purposes.

Returns:

an object representing the pin that connects c ComponentToPin component to a real-world location and optionally to the c TrackedGeometry.

Return type:

ARPin

classmethod pin_component_to_ar_pin(component_to_pin, pin) bool

Associate a component with an ARPin, so that its transform will be updated by the pin. Any previously associated component will be detached.

Parameters:
  • component_to_pin (SceneComponent) – The Component which will be updated by the Pin.

  • pin (ARPin) – The Pin which the component will be updated by.

Returns:

True if the operation was successful.

Return type:

bool

classmethod pin_component_to_trace_result(component_to_pin, trace_result, debug_name='None') ARPin

A convenient version of c PinComponent() that can be used in conjunction with a result of a c LineTraceTrackedObjects call.

Parameters:
Return type:

ARPin

classmethod remove_all_ar_pins_from_local_store() None

Remove all ARPins from the local store

classmethod remove_all_ar_pins_from_wmr_anchor_store() None

deprecated: ‘remove_all_ar_pins_from_wmr_anchor_store’ was renamed to ‘remove_all_ar_pins_from_local_store’.

classmethod remove_ar_pin_from_local_store(save_name) None

Remove an ARPin from the local store

Parameters:

save_name (Name) –

classmethod remove_pin(pin_to_remove) None

Remove a pin such that it no longer updates the associated component.

Parameters:

pin_to_remove (ARPin) –

classmethod resize_xr_camera(size) IntPoint

Change screen size of Mixed Reality Capture camera.

Parameters:

size (IntPoint) –

Return type:

IntPoint

classmethod save_ar_pin_to_local_store(save_name, pin) bool

Save an ARPin to local store

Parameters:
  • save_name (Name) –

  • pin (ARPin) – The ARPin which will be saved to the local store.

Returns:

True if saved successfully.

Return type:

bool

classmethod set_alignment_transform(alignment_transform) None

Set a transform that will be applied to the tracking space. This effectively moves any camera possessed by the Augmented Reality system such that it is pointing at a different spot in Unreal’s World Space. This is often done to support AR scenarios that rely on static geometry and/or lighting.

Note: any movable components that are pinned will appear to stay in place, while anything not pinned or is not movable (static or stationary) will appear to move.

see PinComponent see PinComponentToTraceResult

Parameters:

alignment_transform (Transform) –

classmethod set_ar_world_origin_location_and_rotation(origin_location, origin_rotation, is_transform_in_world_space=True, maintain_up_direction=True) None

For a point P in the AR local space, whose location and rotation are “OriginLocation” and “OriginRotation” in the world space modify the alignment transform so that the same point P will be transformed to the origin in the world space. bIsTransformInWorldSpace:: whether “OriginLocation” and “OriginRotation” are specified in UE4’s world space or AR system’s local space. bMaintainUpDirection:: if set, only the yaw roation of the alignment transform will be modified, pitch and roll will be zeroed out.

Parameters:
  • origin_location (Vector) –

  • origin_rotation (Rotator) –

  • is_transform_in_world_space (bool) –

  • maintain_up_direction (bool) –

classmethod set_ar_world_scale(world_scale) None

Helper function that modifies the alignment transform scale so that virtual content in the world space appears to be “scaled”. Note that ultimately the scaling effect is achieved through modifying the translation of the camera: moving the camera further away from the origin makes objects appear to be smaller, and vice versa.

Parameters:

world_scale (float) –

classmethod set_enabled_xr_camera(on_off) None

Enable or disable Mixed Reality Capture camera.

Parameters:

on_off (bool) –

classmethod start_ar_session(session_config) None

Begin a new Augmented Reality session. Subsequently, use the c GetARSessionStatus() function to figure out the status of the session.

Parameters:

session_config (ARSessionConfig) – Describes the tracking method to use, what kind of geometry to detect in the world, etc.

classmethod stop_ar_session() None

Stop a running Augmented Reality session and clear any state.

classmethod toggle_ar_capture(on_off, capture_type) bool

Starts or stops a battery intensive service on device.

Parameters:
Return type:

bool

classmethod unpin_component(component_to_unpin) None

Given a pinned c ComponentToUnpin, remove its attachment to the real world.

Parameters:

component_to_unpin (SceneComponent) –