SO101-Nexus

SO101-Nexus includes a subset of the YCB (Yale-Columbia-Berkeley) object dataset. Mesh assets are downloaded from the Hugging Face Hub on first use and cached locally.

Available objects

Model ID	Object
`009_gelatin_box`	Gelatin box
`011_banana`	Banana
`030_fork`	Fork
`031_spoon`	Spoon
`032_knife`	Knife
`033_spatula`	Spatula
`037_scissors`	Scissors
`040_large_marker`	Large marker
`043_phillips_screwdriver`	Phillips screwdriver
`058_golf_ball`	Golf ball

The full mapping is available in the YCB_OBJECTS dictionary exported from so101_nexus.

from so101_nexus import YCB_OBJECTS

for model_id, name in YCB_OBJECTS.items():
    print(f"{model_id}: {name}")

Automatic download

When you create a YCBObject and use it in an environment, the required mesh files are downloaded automatically via ensure_ycb_assets.

from so101_nexus import YCBObject

# Assets for "011_banana" are downloaded on first use
obj = YCBObject(model_id="011_banana")

You can also trigger the download explicitly:

from so101_nexus import ensure_ycb_assets

ensure_ycb_assets("011_banana")

Cache location

Assets are stored at:

~/.cache/so101_nexus/ycb/{model_id}/

Each model directory contains the collision and visual mesh files needed by the simulator. When available, it also contains texture.png, extracted from the source GLB base-color texture.

Public helpers

Four helper functions provide paths to cached assets:

Function	Returns
`get_ycb_mesh_dir(model_id)`	Path to the model's cache directory
`get_ycb_collision_mesh(model_id)`	Path to the collision mesh file
`get_ycb_visual_mesh(model_id)`	Path to the visual mesh file
`get_ycb_texture_file(model_id)`	Expected path to the optional texture image

from so101_nexus import (
    get_ycb_collision_mesh,
    get_ycb_mesh_dir,
    get_ycb_texture_file,
    get_ycb_visual_mesh,
)

mesh_dir = get_ycb_mesh_dir("011_banana")
collision = get_ycb_collision_mesh("011_banana")
visual = get_ycb_visual_mesh("011_banana")
texture = get_ycb_texture_file("011_banana")

These functions do not trigger a download. Call ensure_ycb_assets first if the assets may not be cached yet.

ensure_ycb_assets treats collision.obj and visual.obj as the required geometry cache. It also attempts to extract texture.png from meshes/{model_id}/google_16k/textured.glb. Texture extraction is best effort: if a model or local trimesh version does not expose a texture image, the environment still runs with the untextured visual mesh.

Custom Hugging Face repository

By default, assets are fetched from the ai-habitat/ycb Hugging Face dataset. You can override this by setting the SO101_YCB_HF_REPO environment variable:

export SO101_YCB_HF_REPO="your-org/your-ycb-repo"

This is useful for private mirrors or custom object sets that follow the same directory layout.

Troubleshooting

Download failures. If a download is interrupted, the cached directory may be incomplete. Delete the relevant subdirectory and retry:

rm -rf ~/.cache/so101_nexus/ycb/011_banana

Invalid model ID. Passing a model_id not in the supported set will raise an error. Check YCB_OBJECTS for the full list of valid IDs.

Firewall or proxy issues. Asset downloads use the Hugging Face Hub client. If you are behind a proxy, configure the standard HF_HUB_DISABLE_TELEMETRY, HTTPS_PROXY, or HF_ENDPOINT environment variables as needed.

YCB Assets