Classification Workflows

---
name: classification-workflows
description: "Build, validate, and troubleshoot PointNet2 ModelNet40
  classification training and evaluation workflows."
disable-model-invocation: true
metadata:
  disco-role: operating
license: NOASSERTION
---

# classification-workflows

Use this sub-skill when the user asks for ModelNet40 classification with this PointNet2 repository: single-GPU training, multi-GPU training, checkpoint evaluation, voting, ModelNet data layout checks, or command construction.

## What this sub-skill owns

- ModelNet40 classification workflows driven by `train.py`, `train_multi_gpu.py`, and `evaluate.py`.
- Dataset routing between default HDF5 ModelNet40 data and normal-resampled ModelNet40 text files.
- Model routing between `pointnet2_cls_ssg`, `pointnet2_cls_msg`, and the CPU-friendly baseline `pointnet_cls_basic`.
- Checkpoint path, `--num_votes`, `--num_point`, `--normal`, `--batch_size`, and multi-GPU command details.

Do not use this sub-skill for ShapeNetPart, ScanNet, visualization, or custom-op compilation. If the user is debugging TensorFlow custom operators, shared PointNet APIs, or a CPU-only baseline graph smoke, route to the sibling `model-apis-and-custom-ops` sub-skill; this sub-skill only explains how that backend choice affects classification commands.

## Fast route

1. **Choose the dataset mode.**
   - Default HDF5 mode uses `data/modelnet40_ply_hdf5_2048/`, XYZ only, and `--num_point <= 2048`.
   - Normal-resampled mode uses `data/modelnet40_normal_resampled/`, XYZ+normal text files, and `--num_point <= 10000`. The stock source loaders return 6 channels when `--normal` is set; the stock model files observed here declare `BxNx3` placeholders, so normal-channel experiments require a model adaptation before a real run.
2. **Choose the model.**
   - `pointnet2_cls_ssg`: default PointNet++ single-scale grouping classifier; requires the shared custom-op backend.
   - `pointnet2_cls_msg`: PointNet++ multi-scale grouping classifier; also requires the shared custom-op backend.
   - `pointnet_cls_basic`: PointNet v1 baseline; best for CPU smoke/baseline work when PointNet++ custom ops are unavailable.
3. **Validate the data layout before importing repo loaders.** The HDF5 loader has a top-level auto-download side effect when its folder is missing. Prefer the bundled validator:

   ```bash
   python sub-skills/classification-workflows/scripts/validate_modelnet_layout.py --mode h5 --repo-root . --num-point 1024
   python sub-skills/classification-workflows/scripts/validate_modelnet_layout.py --mode normal --repo-root . --num-point 5000
   ```

4. **Build a command instead of editing legacy scripts by hand.**

   ```bash
   python sub-skills/classification-workflows/scripts/build_classification_command.py --action train --dataset-mode h5 --model pointnet2_cls_ssg --num-point 1024 --log-dir log_cls_ssg
   python sub-skills/classification-workflows/scripts/build_classification_command.py --action train-multi-gpu --dataset-mode h5 --model pointnet2_cls_msg --num-gpus 2 --cuda-visible-devices 0,1 --batch-size 32 --log-dir log_cls_msg_2gpu
   python sub-skills/classification-workflows/scripts/build_classification_command.py --action evaluate --dataset-mode h5 --model pointnet2_cls_ssg --model-path log_cls_ssg/model.ckpt --dump-dir dump_cls_ssg --num-votes 12
   ```

5. **Run the generated command from a compatible PointNet2 checkout.** For PointNet++ models, verify the shared TensorFlow custom-op backend first. For a CPU-only sanity path, generate the command with `--model pointnet_cls_basic` and keep `--num_votes 1` for evaluation.

## Bundled references and scripts

- [references/workflows.md](references/workflows.md): command workflows, model selection, checkpoints, voting, and multi-GPU behavior.
- [references/data-formats.md](references/data-formats.md): ModelNet40 HDF5 and normal-resampled layouts, loader behavior, and custom-data rules.
- [references/troubleshooting.md](references/troubleshooting.md): common classification failures and recovery steps.
- [scripts/build_classification_command.py](scripts/build_classification_command.py): safe command builder for training, multi-GPU training, and evaluation.
- [scripts/validate_modelnet_layout.py](scripts/validate_modelnet_layout.py): offline layout validator that avoids the HDF5 loader's auto-download side effect.
- [scripts/smoke_modelnet_loader.py](scripts/smoke_modelnet_loader.py): tiny CPU data-loader smoke independent of the repo's TensorFlow code.

## Minimum handoff for a classification task

When handing a command to the user, include:

- Dataset mode and validated layout path.
- Model name and whether PointNet++ custom ops are required.
- Exact command, generated by the bundled builder when possible.
- For evaluation: checkpoint prefix, dump directory, and `--num_votes` rationale.
- Any unresolved backend or normal-channel shape risk.