Sceneform markers

These options belong to LocationMarker and LocationScene in the arcore-location-sceneform module, which is for apps that already use Sceneform. For a new app, start with Getting started.

How a marker is built

Scene
 └── AnchorNode    (one ARCore anchor, moved when the marker needs re-placing)
      └── layout node   (stacking offset, rotation to face the camera, scaling, visibility)
           └── your node

The scene only changes the anchor and layout nodes. You can position, rotate and scale your own node relative to its parent, for example to make a label a sensible size.

Height

setHeight(metres) raises or lowers the marker. It is measured from:

• the coordinate's altitude, if the coordinate has one and the tracker knows the scene's altitude (normally only with the Geospatial API), or
• the camera, otherwise.

So with GPS and compass, setHeight(0) puts a marker at eye level, and setHeight(-1.5f) puts it roughly at ground level for someone holding a phone.

Scaling

Mode	Effect
FIXED_SIZE_ON_SCREEN (default)	The marker stays the same size on screen at any distance.
NO_SCALING	The marker shrinks with distance like a real object.
GRADUAL_FIXED_SIZE	Like FIXED_SIZE_ON_SCREEN, but nearer markers are drawn slightly larger.
GRADUAL_TO_MAX_RENDER_DISTANCE	The marker's scale grows with its drawn distance, from the maximum gradual scale up close to the minimum at the render distance.

setGradualScalingMinScale and setGradualScalingMaxScale (defaults 0.8 and 1.4) control the gradual modes, and setScaleModifier multiplies the result.

Overlapping markers

When several markers lie in nearly the same direction, they can be drawn on top of each other. LocationScene.setOverlapMode controls this:

• NONE (default) draws them all.
• HIDE shows only the nearest of each group.
• STACK raises each further marker by setStackSpacingMetres (default 1.2 m) so they form a column.

Markers count as overlapping when they are within setOverlapAngleDegrees (default 6 degrees) of each other as seen from the camera.

Limiting what's shown

• marker.setOnlyRenderWhenWithinMetres(metres) hides a marker when it's further away than this. The marker reappears when you come back within range; there's a 5% margin so it doesn't flicker at the edge.
• locationScene.setMaxVisibleMarkers(count) shows at most this many markers, nearest first.

Hidden markers have their anchors detached, so a large number of distant markers costs little.

Render distance

setMaxRenderDistanceMetres (default 25) is how far away markers are drawn. Sceneform's camera clips at 30 metres, so keep it below that. Further markers are drawn at this distance in the right direction.

Updating labels

setOnRenderListener runs every frame while the marker is visible:

marker.setOnRenderListener(m -> {
    String text = Math.round(m.getDistanceMetres()) + " m";
    if (!text.contentEquals(distanceView.getText())) {
        distanceView.setText(text);
    }
});

Only update views when the text changes; setting text every frame makes Sceneform re-render the view each time.

Moving and removing markers

marker.setCoordinate(...) moves a marker; it's repositioned on the next frame. locationScene.removeMarker(marker) and clearMarkers() detach anchors and remove nodes from the scene.