Add --folder option to export without USDZ packaging for large PLY files

[j3soon]

Large PLY files (>4 GB) fail to convert to USDZ when using the threedgrut.export.scripts.ply_to_usd script due to the USDZ 4 GB size limit. The failure occurs silently during conversion and can only be detected using USD tooling such as usdview, usdtree -f, Omniverse Kit, or Isaac Sim.

This adds a --folder option to ply_to_usd.py that exports USD files (default.usda, gauss.usda, and .nurec) directly to a folder instead of packaging them in a USDZ archive. Exporting to a folder avoids the USDZ size limit and provides a simple workaround for large point cloud files.

Closes: #139

[j3soon]

Example steps:

First, clone the repo:

git clone -b feat/folder-option-for-large-ply https://github.com/j3soon/3dgrut.git
cd 3dgrut

Second, launch 3DGRUT container

xhost +local:root
docker run -v --rm -it --gpus=all --net=host --ipc=host -v $PWD:/workspace --runtime=nvidia -e DISPLAY j3soon/3dgrut:20260203

in the container run:

python -m threedgrut.export.scripts.ply_to_usd ./assets/example.ply --output_file ./assets/example --folder

wait for it to finish, and change permissions for later use:

chmod -R a+r ./assets/example

Third, launch Isaac Sim 5.1.0 (Kit 107.3.3) container:

mkdir -p ~/docker/isaac-sim/cache/main/ov
mkdir -p ~/docker/isaac-sim/cache/main/warp
mkdir -p ~/docker/isaac-sim/cache/computecache
mkdir -p ~/docker/isaac-sim/config
mkdir -p ~/docker/isaac-sim/data/documents
mkdir -p ~/docker/isaac-sim/data/Kit
mkdir -p ~/docker/isaac-sim/logs
mkdir -p ~/docker/isaac-sim/pkg
sudo chown -R 1234:1234 ~/docker/isaac-sim

docker pull nvcr.io/nvidia/isaac-sim:5.1.0
xhost +local:docker
docker run --name isaac-sim --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --rm --network=host \
  -e "PRIVACY_CONSENT=Y" \
  -v ~/docker/isaac-sim/cache/main:/isaac-sim/.cache:rw \
  -v ~/docker/isaac-sim/cache/computecache:/isaac-sim/.nv/ComputeCache:rw \
  -v ~/docker/isaac-sim/logs:/isaac-sim/.nvidia-omniverse/logs:rw \
  -v ~/docker/isaac-sim/config:/isaac-sim/.nvidia-omniverse/config:rw \
  -v ~/docker/isaac-sim/data:/isaac-sim/.local/share/ov/data:rw \
  -v ~/docker/isaac-sim/pkg:/isaac-sim/.local/share/ov/pkg:rw \
  -v $(pwd):/workspace \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $HOME/.Xauthority:/root/.Xauthority \
  -u 1234:1234 \
  nvcr.io/nvidia/isaac-sim:5.1.0

in the container run:

./runapp.sh

then drag /workspace/assets/example/default.usda into the scene. Wait for the rendering to appear.

[j3soon]

As a side note, the PLY should have SH degree 3 (i.e., should have f_rest_* all the way to f_rest_44), as assumed by 3DGRUT:

3dgrut/configs/base_gs.yaml

Line 69 in a03c594

max_n_features: 3 # sh: maximum sh deg | mlp: total num of dims finally unmasked

If following above with a PLY with SH degree 0, the error will occur:

[Error] [omni.hydra] Exception in NuRecVolume::postSync: [json.exception.parse_error.110] parse error at byte XXXXXXXXX: syntax error while parsing MessagePack binary: unexpected end of input