[yunyv]

Reference issue

No matching open issue or competing fix found for the farthest-point sampler's count bounds.

What does this implement/fix?

farthest_point_sampling always chooses its initial row before considering n_points. With two input rows and n_points=3, all row indices eventually become selected and the loop never advances. Requesting zero points returns one row instead (or errors for an empty cloud).

Validate the integer count before selecting the initial row. Counts outside [0, M] raise ValueError, and a zero count returns an empty (0, N) array with the input dtype. The standard integer-index protocol also accepts NumPy integer scalars and rejects noninteger counts rather than silently sampling a rounded-up count. Document these boundaries in the function and existing official RST page.

The sampling loop, valid-input random seeds/order, defaults, and other sampling algorithms are unchanged. Duplicate coordinates remain separate input rows and can each be selected at most once.

Additional information

Validation on Linux / Python 3.14.8 using the repository-pinned environment:

• Real normal-import baseline reproduction with two input rows and count three exceeded a five-second subprocess timeout; the child was terminated and waited. This case was tested separately so the baseline pytest invocation could not hang indefinitely.
• Selected baseline boundary/control regressions: 4 failed, 5 passed, 4 deselected. Fixed complete sampler module: 13 passed with warnings as errors, including the unchanged example.
• 144 valid positive count/dimension/dtype/seed combinations match the original outputs exactly.
• Full bash runtests.sh: 168 passed in 326.43 seconds, including code style and all configured mypy checks, with BLAS/OMP threads limited to one.
• Scoped Ruff and git diff --check: passed; Ruff's existing configuration deprecation notice is unchanged.
• make -C docs html BUILDDIR=/tmp/pythonrobotics-fps-docs: passed with the existing -W setting. Generated HTML contains the new boundary and exception documentation and retains its mapping navigation link. The CircleCI documentation artifact was opened through its Mapping parent page and visually inspected in light theme. The new boundary paragraph, the Farthest Point Sampling illustration, and the API parameter, return-value, and exception sections rendered correctly. No hardware verification is claimed. This PR remains a draft; hosted CI approvals and completion are tracked separately.

No dependency changes, GPU tests, or macOS/Windows runs. AI assistance was used for implementation and test preparation; no human review is claimed.

CheckList

• Did you add an unittest for your new example or defect fix?
• Did you add documents for your new example? (Updated the existing official page.)
• All CIs are green? (CircleCI docs/artifact and AppVeyor passed; four GitHub Actions workflows await maintainer approval.)