[Question] The sampling points generated by flat_patch_sampling are highly unevenly distributed

[DrPengZhe]

I am using flat_patch_sampling to collect obstacle-free points as initial positions for my robots. However, when visualizing these points in yellow, I found that their distribution across the map is extremely uneven—some areas contain a large number of points, while others have very few. This uneven distribution undermines my goal of having robots spawn randomly and uniformly across the terrain. Since I am using only a single sub-terrain, I am not sure what is causing the issue. Below is the code I used to generate the terrain:

        terrain_cfg = TerrainImporterCfg(
            num_envs=self.num_envs,
            prim_path="/World/defaultGroundPlane",
            terrain_type="generator",
            terrain_generator=TerrainGeneratorCfg(
                seed=0,
                curriculum=False,
                size=(75.0, 75.0),
                border_width=5.0,
                num_rows=1,
                num_cols=1,
                horizontal_scale=0.1,
                vertical_scale=0.1, 
                use_cache=False,
                sub_terrains={
                    "obstacles": HfDiscreteObstaclesTerrainCfg(
                        obstacle_height_mode="fixed",   # The mode to use for the obstacle height:   choice   fixed
                        size=(75.0, 75.0),
                        horizontal_scale=0.1,
                        vertical_scale=0.1,  # 1.0   0.1
                        border_width=0.0,
                        num_obstacles=50,
                        obstacle_width_range=(1.0, 2.0),
                        obstacle_height_range=(10.0, 10.0), 
                        platform_width=0.1, 
                        flat_patch_sampling={
                            "target": FlatPatchSamplingCfg(
                                num_patches=20000,
                                patch_radius=0.8,  
                                max_height_diff=0.)
                        },
                    )
                },
            ),
        )
        terrain: TerrainImporter = terrain_cfg.class_type(terrain_cfg)
        self.valid_positions: torch.Tensor = terrain.flat_patches['target']   # [num_rows, num_cols, num_patches, 3]

And I also set patch_radius = 0.8, but some sampled points still appear inside obstacles. From the visualization, you can clearly see yellow points located on top of obstacles. I tried adjusting this value to 0.9, 1.0, and so on, but none of these settings solved the issue. Unfortunately, I am unable to inspect the internal implementation of the flat_patch_sampling function to understand how its sampling logic works. This problem has been troubling me for quite a while. Any help or insight would be greatly appreciated!

[RandomOakForest]

Thank you for posting this. Here is a summary that may help, though still under review. I'll move this post to our Discussions section for follow up.

The uneven distribution and obstacle-overlap both come from how flat patches are computed on height fields, not from your sub-terrain layout. Flat patch sampling is local and constrained by the HF resolution and height thresholds, so you can easily over-sample “good” areas and still get points whose radius overlaps obstacles even if the center is nominally flat.¹²

Why distribution looks clustered

Flat patches are found by scanning the height field grid and checking local height differences within the patch radius; all valid “patch centers” are then subsampled to meet num_patches. This gives you:²

• Non-uniform available area: regions with more flat HF cells (e.g., large platforms, smooth regions between obstacles, or HF discretization artifacts) will naturally produce more valid patch centers, so the sampler pulls many points from there even if you only have one sub-terrain.¹²
• No global uniformity guarantee: there is no stratification or Poisson-disk process over (x, y); the sampler just picks among all valid cells, so clusters and voids are expected, especially with tall, discrete obstacles that carve the map into irregular free regions.²

If you want spatially more uniform coverage, you need an extra sampling layer on top of flat_patches:

• Build a 2D grid over your terrain and, for each cell, pick a random flat patch that falls into that cell, or
• Run Poisson-disk or blue-noise sampling over the valid_positions you already have, discarding points that are too close to each other.

For example, after getting self.valid_positions:

# valid_positions: [num_rows, num_cols, num_patches, 3]
flat_points = self.valid_positions.reshape(-1, 3)

# optional: restrict to the actual useful area (remove borders, etc.)
mask = (
    (flat_points[:, 0] > -35.0) & (flat_points[:, 0] < 35.0) &
    (flat_points[:, 1] > -35.0) & (flat_points[:, 1] < 35.0)
)
flat_points = flat_points[mask]

# simple stratified re-sampling example
num_bins = 20
x_bins = torch.linspace(flat_points[:, 0].min(), flat_points[:, 0].max(), num_bins + 1)
y_bins = torch.linspace(flat_points[:, 1].min(), flat_points[:, 1].max(), num_bins + 1)

indices = []
for i in range(num_bins):
    for j in range(num_bins):
        in_cell = (
            (flat_points[:, 0] >= x_bins[i]) & (flat_points[:, 0] < x_bins[i+1]) &
            (flat_points[:, 1] >= y_bins[j]) & (flat_points[:, 1] < y_bins[j+1])
        ).nonzero(as_tuple=True)[^0]
        if len(in_cell) > 0:
            idx = in_cell[torch.randint(len(in_cell), (1,))]
            indices.append(idx)

uniform_points = flat_points[torch.stack(indices)]

Then sample robot spawn locations from uniform_points instead of directly from the raw flat_patches tensor.

Why points appear “inside” obstacles

A few details of the HF obstacles setup are important here.²¹

• HF resolution and radius: horizontal_scale=0.1 means each HF cell is 0.1 m in x/y, while your patch_radius=0.8 spans only a small number of cells around the center.¹²
  • The flatness check is done on the height values of the cells within that radius; it does not explicitly check the semantic obstacle mask. If there is even a small flat plateau on top of an obstacle, or the HF transitions are smoothed, the sampler may mark cells near or on the obstacle as flat.
• Center vs. full footprint: the check ensures the patch cells inside the radius are within max_height_diff but does not enforce a margin beyond patch_radius. The yellow points you see “on” obstacles are often centers whose radius partly overlaps obstacle edges, especially when obstacles are narrow and tall.
• max_height_diff=0. is strict flatness, but it does not say where that flat surface lies—ground or obstacle top both pass as flat if the height is locally constant. That is exactly your configuration: fixed 10 m tall obstacles that are flat on top, so the sampler happily returns flat patches on the obstacle tops.²

To ensure robots do not spawn on obstacles, you need either geometric or semantic filtering:

1. Height range restriction

If your ground is at or near 0 and obstacles at 10, use z_range in FlatPatchSamplingCfg so flat patches are only accepted within a reasonable ground band.²

flat_patch_sampling={
    "target": FlatPatchSamplingCfg(
        num_patches=20000,
        patch_radius=0.8,
        max_height_diff=0.0,
        z_range=(-0.2, 0.5),  # adapt to your ground noise
    )
}

The z_range is applied during sampling and restricts candidate patches to that vertical interval. This alone usually eliminates patches on 10 m tall obstacles.²

2. XY range constraints

If the obstacle field only occupies part of the map, you can also add x_range and y_range to restrict sampling to regions that are known to be obstacle-free or to avoid borders and HF artifacts.²

FlatPatchSamplingCfg(
    num_patches=20000,
    patch_radius=0.8,
    max_height_diff=0.0,
    x_range=(-35.0, 35.0),
    y_range=(-35.0, 35.0),
    z_range=(-0.2, 0.5),
)

3. Post-filter based on distance to obstacles

If you know the obstacle geometry (e.g., you also have the HF or obstacle masks), compute the shortest distance from each candidate patch center to obstacle cells and discard any below a margin:

# flat_points: [N, 3]
# obs_mask: [Hx, Hy] boolean mask where True = obstacle cell
# obs_points: coordinates of obstacle cells
# then:
dists = torch.cdist(flat_points[:, :2], obs_points[:, :2])
min_dists, _ = dists.min(dim=1)
safe_mask = min_dists >= (patch_radius + safety_margin)
safe_points = flat_points[safe_mask]

This guarantees that your robots will not overlap obstacles even if the HF flatness checker allows some centers near edges.

Footnotes

1. https://isaac-sim.github.io/IsaacLab/main/source/api/lab/isaaclab.terrains.html ↩ ↩² ↩³ ↩⁴

2. https://isaac-sim.github.io/IsaacLab/main/source/api/lab/isaaclab.terrains.html#isaaclab.terrains.TerrainGenerator ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰