@jlafleche @pcallender can we get some kind of documentation for the new functional API, specifically for the Replicator components?
The methods seem to be similar to the ones from regular Replicator API but they do differ and right now its a guessing game to get them to work.
Examples can be found in Randomizing N cameras in mesh areas - #10 by jlafleche
We’re working on getting updated API documentation up. I apologies for the delay. rng in this case refers to the random number generator to use. That could be from numpy or from replicator. Here’s the function and docstring for scatter_2d and scatter_3d:
def scatter_2d(
prims: Union[pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]],
surface_prims: Union[pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]],
no_collision_prims: Union[pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]] = None,
extents: Tuple[Tuple[float, float, float], Tuple[float, float, float]] = None,
offset: float = 0.0,
check_for_collisions: bool = False,
rng: np.random.Generator = None,
) -> None:
"""Scatter the prims in 2D space.
Args:
prims: The prims to scatter.
surface_prims: The surface prims to sample points from.
no_collision_prims: Existing prim(s) to prevent collisions with - if any prims are passed they will be checked for
collisions which may slow down compute, regardless if ``check_for_collisions`` is ``True`` or ``False``.
extents: The 3D extents of the sampling volume.
offset: The distance the prims should be offset along the normal of the surface of the mesh.
check_for_collisions: Whether the scatter operation should ensure that objects are not intersecting
rng: The random number generator to use. If `None`, a new generator will be created using
`rep.rng.ReplicatorRNG().generator`.
Example:
>>> import omni.replicator.core.functional as F
>>> import omni.replicator.core as rep
>>> rng = rep.rng.ReplicatorRNG()
>>> surface_prim = F.create.plane(name="surface_prim", position=(0, 0, 0), scale=(10, 1, 10))
>>> prims = F.create_batch.cube(count=10, position=(0, 0, 0), scale=(1, 1, 1))
>>> F.randomizer.scatter_2d(prims, surface_prim, rng=rng)
"""
def scatter_3d(
prims: Union[pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]],
volume_prims: Union[
pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]
] = None,
no_collision_prims: Union[pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]] = None,
volume_excl_prims: Union[
pxr.Usd.Prim, usdrt.Usd.Prim, List[Union[pxr.Usd.Prim, usdrt.Usd.Prim]]
] = None,
extents: Tuple[Tuple[float, float, float], Tuple[float, float, float]] = None,
check_for_collisions: bool = False,
prevent_vol_overlap: bool = True,
viz_sampled_voxels: bool = False,
resolution_scaling: float = 1.0,
input_voxel_size: float = 0.0,
rng: np.random.Generator = None,
) -> None:
"""Scatter the prims in 3D space.
Args:
prims: The prims to scatter.
volume_prims: The volume prims to sample points from.
no_collision_prims: Existing prim(s) to prevent collisions with - if any prims are passed they will be checked for
collisions using rejection sampling. This may slow down compute, regardless if check_for_collisions is
True/False.
volume_excl_prims: Prim(s) from which to exclude from sampling. Must have watertight meshes. Similar effect to
``no_coll_prims``, but more efficient and less accurate. Rather than performing rejection sampling based on
collision with the provided volume (as ``no_coll_prims`` does), this prunes off the voxelized sampling space
enclosed by ``volume_excl_prims`` so the rejection rate is 0 because it never tires to sample in the
excluded space. However, some objects may get sampled very close to the edge of a mesh in
``volume_excl_prims``, where the sampled root point is outside ``volume_excl_prims`` but parts of the mesh
extend to overlap the space. To get the best of both worlds, you can pass the same volume prim to both
``no_coll_prims`` and to ``volume_excl_prims``, providing a high accuracy and a low rejection rate.
extents: The extents of the sampling volume.
check_for_collisions: Whether the scatter operation should ensure that sampled objects are not intersecting.
prevent_vol_overlap: If ``True``, prevents double sampling even when multiple enclosing volumes overlap, so that
the entire enclosed volume is sampled uniformly. If ``False``, it allows overlapped sampling with higher
density in overlapping areas.
viz_sampled_voxels: If ``True``, creates semi-transparent green cubes in all voxels in the scene that the input
prim positions are sampled from.
resolution_scaling: Amount the default voxel resolution used in sampling should be scaled. More complex meshes
may require higher resolution. Default voxel resolution is 30 for the longest side of the mean sized
volumePrim mesh provided. Higher values will ensure more fine-grained voxels, but will come at the cost of
performance.
input_voxel_size: Voxel size used to compute the resolution. If this is provided, then resolution_scaling is ignored,
otherwise (if it is ``0`` by default) resolution_scaling is used.
rng: The random number generator to use. If `None`, a new generator will be created using
`rep.rng.ReplicatorRNG().generator`.
Example:
>>> import omni.replicator.core.functional as F
>>> import omni.replicator.core as rep
>>> rng = rep.rng.ReplicatorRNG()
>>> volume_prim = F.create.torus(name="volume_prim", position=(0, 0, 0), scale=(10, 10, 10), visible=False)
>>> prims = F.create_batch.cube(count=500, position=(0, 0, 0), scale=(1, 1, 1))
>>> F.randomizer.scatter_3d(prims, volume_prim, rng=rng)
"""
Thanks!