GroupFraming

Moves the camera closer or farther to keep several targets in view.

Keeps every member on screen. It places the camera in line with the group's center, along the camera's current view direction, at the distance where every member fits. By default it never moves the camera closer than the Body placed it; with fitMode: 'rigid' it always sits at exactly that distance, so it also moves in as the group gets smaller.

With an orthographic camera, distance doesn't change what's in view, so it fits the group by orthographicSize instead. The camera keeps the distance the Body gave, and only backs away when a member would end up in front of the near plane. By default it never goes below the size from the lens, so give it one with Lens; with fitMode: 'rigid' it always uses exactly the size that fits.

It doesn't rotate the camera, so pair it with an Aim that already looks at the group. klipp.setSize keeps the viewport size in sync.

Settings

Setting	Description	Default
`members`	The targets to keep in view. See below.
`positionMode`	How the group's center, which the camera lines up with, is computed: `'groupCenter'` (center of the bounds) or `'groupAverage'` (weighted average of positions).	`'groupCenter'`
`padding`	Extra space around the members, in world units.	`0`
`fitMode`	`'ceiling'` never moves the camera closer than the Body placed it, or for an orthographic camera never goes below the size from the lens. `'rigid'` always fits the group exactly.	`'ceiling'`
`framingMode`	Which screen dimensions to fit: `'horizontal'`, `'vertical'` or `'horizontalAndVertical'`.	`'horizontalAndVertical'`
`minDistance`	Closest the camera may get to the group, for a perspective camera.	`0`
`maxDistance`	Farthest `GroupFraming` will move the camera away from the group, for a perspective camera.	`Infinity`
`minOrthographicSize`	Smallest `orthographicSize` it fits the group with, for an orthographic camera.	`0`
`maxOrthographicSize`	Largest `orthographicSize` it fits the group with, for an orthographic camera.	`Infinity`
`damping`	Seconds to catch up with the right distance or size. See Damping.	`0`
`maxSpeed`	Maximum catch-up speed, in units per second.	`Infinity`
`screenPosition`	Shifts the view without moving the camera, for example to leave room for UI. `[0, 0]` is centered.	`[0, 0]`
`debug`	React only. Draws the padding on screen. See Debugging.	`false`

Members

Field	Description	Default
`target`	three.js and React. The member. See Targets.
`position`, `extent`	Core only. The member's position and size, which you keep up to date.
`weight`	Influence on the center in `'groupAverage'` mode.	`1`
`radius`	three.js and React. The member's radius, so its edge stays in view instead of its center.	`0`
`size`	three.js and React. The member's box size, used instead of `radius`.	measured for meshes
`resolved`	Core only. Set to `false` to skip the member, for example while it isn't loaded yet.	`true`

Usage

Members are plain data you keep up to date:

import { vec3 } from 'math';
import { GroupFramingExtension, groupFraming } from '@pmndrs/klipp';

const a = groupFraming.createMember();
const b = groupFraming.createMember();
b.extent.radius = 2;
camera.addExtension(new GroupFramingExtension([a, b], { padding: 1, damping: 0.5 }));

// every frame, before klipp.update
vec3.copy(a.position, aPosition);
vec3.copy(b.position, bPosition);

Members are a TargetGroup:

import { GroupFramingExtensionThree, TargetGroup } from '@pmndrs/klipp/three';

const group = new TargetGroup([{ target: a }, { target: b, radius: 2 }], 'groupCenter');
camera.addExtension(new GroupFramingExtensionThree(group, { padding: 1, damping: 0.5 }));

For meshes, member sizes are measured from their geometry. If a member's shape changes, call recalculateSize() to measure it again.

<VirtualCamera name="party" priority={10}>
  <Body.Follow target={leaderRef} offset={[0, 4, 10]} />
  <Aim.HardLookAt target={leaderRef} />
  <Extension.GroupFraming
    members={[{ target: aRef }, { target: bRef, radius: 2 }]}
    padding={1}
    damping={0.5}
  />
</VirtualCamera>

For meshes, member sizes are measured from their geometry. ref gives you the GroupFramingExtensionThree: if a member's shape changes, call recalculateSize() to measure it again.

Edit this page