Direct method APIs and cluster4d

The package keeps cluster4d(), typed cluster4d_*() wrappers, and older method-native functions. The current cluster4d() documentation classifies supervoxels(), snic(), slic4d_supervoxels(), slice_msf(), and supervoxels_flash3d() as legacy/deprecated entry points. They remain exported for compatibility, but new code should use the unified interface or its typed wrappers. Equivalence should never be assumed unless mapped parameters are identical.

slice_msf() and cluster4d_slice_msf() are additionally experimental. The typed wrapper standardizes the result and requests exact K, but neither entry point is currently recommended automatically or for production use. See the Slice-MSF evaluation contract before evaluating either one.

What does the unified interface map?

Unified method	Legacy entry point	Preferred typed wrapper	Important mapping
`"supervoxels"`	`supervoxels()`	`cluster4d_supervoxels()`	`alpha = 1 - spatial_weight`
`"snic"`	`snic()`	`cluster4d_snic()`	`compactness = 10 * spatial_weight`
`"slic"`	`slic4d_supervoxels()`	`cluster4d_slic()`	`compactness = 20 * spatial_weight`
`"slice_msf"` (experimental)	`slice_msf()`	`cluster4d_slice_msf()`	natural versus exact K, connectivity, and FH scale are translated; positive `gamma` is rejected
`"flash3d"`	`supervoxels_flash3d()`	`cluster4d_flash3d()`	`lambda_s = spatial_weight`; temporal weight is complementary unless supplied
`"g3s"`	none (`g3s()` does not exist)	`cluster4d_g3s()`	`alpha = 1 - spatial_weight`

Those statements describe the current wrappers. Defaults and method-specific arguments can still differ, so record the actual cluster4d() or typed-wrapper call—not an informal translation.

Can a mapping be checked rather than trusted?

This small compatibility example checks the exact legacy SNIC mapping on one generated volume. It explains an existing script; it is not a recommendation to start new code with snic().

unified <- cluster4d(
  syn$vec, syn$mask, n_clusters = 4, method = "snic",
  spatial_weight = 0.4
)
direct <- snic(syn$vec, syn$mask, K = 4, compactness = 4)

For this input and package version, the labels are identical. That is a check of this mapping—not a blanket promise that every unified/direct pair is bit-identical.

Which interface should you publish?

Use cluster4d() when methods are compared under a shared contract. Use a typed cluster4d_*() wrapper when the protocol depends on a native parameter. Treat the legacy functions as compatibility surfaces. In every case, save the result’s parameters and provenance, validate it against the original vec and mask, and report the actual rather than merely requested cluster count. See Read clustering results.