Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

fix(contrib): validate KMeans' num_clusters against its sign and the number of samples (#6443)

Saksham Sharma77d53cfbbe4e
diff --git a/changelog.d/6443.fixed.md b/changelog.d/6443.fixed.md
new file mode 100644
index 000000000..2bf293425
--- /dev/null
+++ b/changelog.d/6443.fixed.md
@@ -0,0 +1 @@
+`kornia.contrib.KMeans` now rejects a `num_clusters` that is not a positive integer when it is constructed, and `fit` rejects more clusters than samples when the starting centres are drawn from the data, each with an error that names `num_clusters`. A negative or `None` count used to pass the constructor and fail in `fit` inside `one_hot` ("Class values must be smaller than num_classes"), and more clusters than samples drew fewer centres and failed the first update with an unrelated tensor-size `RuntimeError`.
diff --git a/kornia/contrib/kmeans.py b/kornia/contrib/kmeans.py
index dd235a878..94beeebd0 100644
--- a/kornia/contrib/kmeans.py
+++ b/kornia/contrib/kmeans.py
@@ -19,6 +19,8 @@
from __future__ import annotations
+import operator
+
import torch
from kornia.core.check import KORNIA_CHECK, KORNIA_CHECK_SAME_SIZE, KORNIA_CHECK_SHAPE
@@ -43,7 +45,8 @@ class KMeans:
truncated toward zero.
Args:
- num_clusters: number of clusters the data has to be assigned to. Required, also with ``cluster_centers``.
+ num_clusters: number of clusters the data has to be assigned to, a positive integer. Required, also with
+ ``cluster_centers``; without them, :meth:`fit` needs at least ``num_clusters`` samples.
cluster_centers: the ``(num_clusters, D)`` starting centres, or ``None`` to sample them from the data in
each :meth:`fit`.
tolerance: the bound on the squared total centre shift that stops :meth:`fit`, or ``None`` to stop only after
@@ -66,7 +69,17 @@ class KMeans:
max_iterations: int = 0,
seed: int | None = None,
) -> None:
- KORNIA_CHECK(num_clusters != 0, "num_clusters can't be 0")
+ # Any integer count, such as a NumPy integer or a 0-d integer tensor, is accepted and stored as an int; a
+ # bool is not a count.
+ try:
+ count = operator.index(num_clusters)
+ except TypeError:
+ count = 0
+ is_bool = isinstance(num_clusters, bool) or (
+ isinstance(num_clusters, torch.Tensor) and num_clusters.dtype == torch.bool
+ )
+ KORNIA_CHECK(not is_bool and count > 0, f"num_clusters must be a positive int, got {num_clusters!r}")
+ num_clusters = count
KORNIA_CHECK(max_iterations >= 0, f"max_iterations must be >= 0, got {max_iterations}")
KORNIA_CHECK(tolerance is None or tolerance >= 0, f"tolerance must be None or >= 0, got {tolerance}")
KORNIA_CHECK(
@@ -202,6 +215,11 @@ class KMeans:
KORNIA_CHECK_SHAPE(X, ["N", "D"])
if self._initial_cluster_centers is None:
+ # The starting centres are distinct samples of X, so there must be at least num_clusters of them.
+ KORNIA_CHECK(
+ len(X) >= self.num_clusters,
+ lambda: f"num_clusters={self.num_clusters} needs at least as many samples, but X has {len(X)}",
+ )
current_centers = self._initialise_cluster_centers(X, self.num_clusters)
else:
# X and cluster_centers should have same number of columns
diff --git a/tests/contrib/test_kmeans.py b/tests/contrib/test_kmeans.py
index 0d9f070fd..0ea64edd3 100644
--- a/tests/contrib/test_kmeans.py
+++ b/tests/contrib/test_kmeans.py
@@ -109,16 +109,61 @@ class TestKMeans(BaseTester):
assert out1.shape == (N,)
assert out2.shape == (num_clusters, D)
+ @pytest.mark.parametrize("num_clusters", [-1, -2])
+ def test_negative_num_clusters_is_rejected_6442(self, num_clusters, device, dtype):
+ # A negative count used to pass __init__ and fail in fit inside one_hot ("Class values must be smaller than
+ # num_classes"), without naming num_clusters.
+ with pytest.raises(BaseError, match=f"num_clusters must be a positive int, got {num_clusters}"):
+ kornia.contrib.KMeans(num_clusters, None, 1e-3, 10, 0)
+
+ # None, which got past the old != 0 check, is rejected with the same message.
+ with pytest.raises(BaseError, match="num_clusters must be a positive int, got None"):
+ kornia.contrib.KMeans(None, None, 1e-3, 10, 0)
+
+ def test_integral_num_clusters_is_accepted_6442(self, device, dtype):
+ # Any integral count is accepted and stored as an int, as a NumPy integer was before the positivity check;
+ # a bool is not a count.
+ np = pytest.importorskip("numpy")
+ X = torch.tensor([[0.0, 0.0], [10.0, 10.0], [0.0, 1.0]], device=device, dtype=dtype)
+ kmeans = kornia.contrib.KMeans(np.int64(2), None, 1e-4, 10, seed=0)
+ assert type(kmeans.num_clusters) is int
+ kmeans.fit(X)
+ assert kmeans.cluster_centers.shape == (2, 2)
+ with pytest.raises(BaseError, match="num_clusters must be a positive int, got True"):
+ kornia.contrib.KMeans(True, None, 1e-3, 10, 0)
+
+ def test_zero_dim_integer_tensor_num_clusters_is_accepted_6442(self, device, dtype):
+ # A 0-d integer tensor fitted before the positivity check too; like a NumPy integer, it is a count.
+ X = torch.tensor([[0.0, 0.0], [10.0, 10.0], [0.0, 1.0]], device=device, dtype=dtype)
+ kmeans = kornia.contrib.KMeans(torch.tensor(2), None, 1e-4, 10, seed=0)
+ assert type(kmeans.num_clusters) is int
+ kmeans.fit(X)
+ assert kmeans.cluster_centers.shape == (2, 2)
+ with pytest.raises(BaseError, match=r"num_clusters must be a positive int, got tensor\(True\)"):
+ kornia.contrib.KMeans(torch.tensor(True), None, 1e-3, 10, 0)
+
+ def test_more_clusters_than_samples_is_rejected_6442(self, device, dtype):
+ # Starting centres sampled from X are distinct samples, so 5 clusters need 5 of them. With 3, the 3 drawn
+ # centres used to fail the first update with an unrelated "size of tensor a (5) must match" RuntimeError.
+ X = torch.tensor([[0.0, 0.0], [10.0, 10.0], [0.0, 1.0]], device=device, dtype=dtype)
+ kmeans = kornia.contrib.KMeans(5, None, 1e-4, 10, seed=0)
+ with pytest.raises(BaseError, match="num_clusters=5 needs at least as many samples, but X has 3"):
+ kmeans.fit(X)
+ # As many clusters as samples is fine, and explicit centres do not draw from X, so they are not limited.
+ kornia.contrib.KMeans(3, None, 1e-4, 10, seed=0).fit(X)
+ centres = torch.zeros(5, 2, device=device, dtype=dtype)
+ kornia.contrib.KMeans(5, centres, 1e-4, 10, seed=0).fit(X)
+
def test_exception(self, device, dtype):
# case: cluster_center = 0:
with pytest.raises(BaseError) as errinfo:
kornia.contrib.KMeans(0, None, 1e-3, 10, 0)
- assert "num_clusters can't be 0" in str(errinfo.value)
+ assert "num_clusters must be a positive int, got 0" in str(errinfo.value)
# case: cluster centers is not a 2D tensor
starting_centers = torch.rand((2, 3, 5), device=device, dtype=dtype)
with pytest.raises(ShapeError) as errinfo:
- kornia.contrib.KMeans(None, starting_centers, 1e-3, 100, 0)
+ kornia.contrib.KMeans(2, starting_centers, 1e-3, 100, 0)
assert "Shape dimension mismatch" in str(errinfo.value)
# case: input data is not a 2D tensor