---

name: core-xconv-and-operators description: "Build and adapt PointCNN X-Conv and X-DeConv graphs, pointfly operators, model heads, and legacy sampling diagnostics." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Core X-Conv and operators

Use this route when a task asks to inspect, adapt, or construct the PointCNN core graph: X-Conv/X-DeConv layers, pointfly geometry and sampling operators, classification or segmentation heads, setting tuples, or the FPS custom operator. This is a TensorFlow 1.x graph-mode contract. It is not a training, data-conversion, checkpoint, or evaluation workflow.

Runtime boundary

• The implementation requires the legacy TensorFlow 1.x graph APIs, including tf.contrib, tf.layers, placeholders, tf.py_func, and sessions. A TensorFlow 2.x import, even when tf.compat.v1 exists, is not by itself a compatible runtime for this contract.
• The FPS/probability/gather sampling kernels are registered for GPU only. There is no CPU fallback in the operator implementation. TensorFlow import, GPU discovery, graph construction, or shared-library loadability is not an FPS execution pass.
• Current runtime evidence is limited: TensorFlow 1.15 import and device discovery passed, while a minimal GPU/custom-op session timed out. Keep FPS status BLOCKED_REQUIRED_BACKEND; never report that the GPU operator passed.

Start safely

1. From the installed skill directory, run the API probe before importing model modules:

   python scripts/check_tensorflow_api.py --graph-smoke
   

   It performs an optional static graph build and fails clearly when TensorFlow or a required legacy API is unavailable. It does not create a session or enumerate devices.

2. Read the API reference for signatures and tensor contracts, then the architecture and settings guide before changing K, D, P, C, links, or decoder indices.

3. Validate every layer against the point count of its actual pts input. An X-Conv requests K * D neighbors and therefore needs K * D <= M; an inverse-density (ids) sampler also needs K <= M. For a newly selected query set, use 0 < P <= M; P == -1 means all current points, not a valid custom-op npoint.

4. For sampling == 'fps', inspect prerequisites before any build or load:

   python scripts/inspect_sampling_build.py --sampling-dir <sampling-dir>
   

   Add --check-load only for an intentional, existing tf_sampling_so.so load attempt. Add --show-build-command only to print a manual recipe for review. The diagnostic never compiles, downloads, trains, or runs a kernel.

Core graph contracts

• pointcnn.xconv consumes pts [N,M,3], optional fts [N,M,F], and query points qrs [N,P,3]; it returns [N,P,C], or [N,P,C + C//4] when the final layer enables global features. It selects K*D neighbors, retains every D-th neighbor, centers them at each query, optionally learns the [K,K] X transform, and applies a separable convolution over the neighbor axis.
• PointCNN(points, features, is_training, setting) stores point and feature tensors in layer_pts and layer_fts, then builds the configured X-Conv, optional X-DeConv, and pointwise FC stacks. Input features are split after the first three coordinate channels and projected before the first X-Conv.
• xconv_params entries are (K, D, P, C, links). K is retained-neighbor count, D is dilation stride, P is query count, C is output channels, and links concatenate earlier feature tensors after they are sliced to the current query count. Links are supported only with sampling == 'random' in this implementation and must resolve to existing, row-aligned layers.
• xdconv_params entries are (K, D, pts_layer_idx, qrs_layer_idx). The indexed coarse layer supplies source points/features and the indexed finer layer supplies query points/skip features. The query layer contributes its inherited P and C; the decoder X-Conv is fused with the skip tensor and projected back to C. Validate both layer indices and K*D against the coarse source point count.
• Sampling semantics are distinct: random takes the first P source points in this graph (it is not a random draw), ids uses inverse-density sampling through a Python/NumPy callback, and fps calls the CUDA custom operator. Do not use a random or ids graph smoke as evidence that an FPS graph or kernel works.
• pointcnn_cls.Net produces per-point training logits [N,P,num_class], then conditionally averages the final point axis for inference to [N,1,num_class]. pointcnn_seg.Net keeps the point axis and produces [N,P,num_class] in both training and inference. The outer workflows apply softmax, argmax, and losses; those are not part of either Net constructor.

Common routes

• Change an X-Conv graph: preserve coordinate rank [N,M,3] and feature rank [N,M,F]; choose queries with the setting sampler; account for the first-layer feature projection, link concatenation, optional global C//4 widening, and final channel count.
• Change a setting: use the tuple names and layer-index rules in the architecture reference. Check the actual point count entering each layer, not only the original input size. Keep P == -1 only where all current points are intended, and resolve a positive query count before calling FPS.
• Use pointfly directly: preserve the exact signatures and ranks in the API reference. In particular, knn_indices_general returns [N,P,K,2] gather indices, get_indices creates NumPy gather indices, and augment is a graph op. inverse_density_sampling and duplicate filtering use tf.py_func, so they require a local graph/session path and are not graph-free or remote-safe by implication.
• Diagnose sampling ABI/toolkit failures: inspect source markers, nvcc, C++ compiler, TensorFlow include/library paths, CUDA include/runtime paths, expected library name, and the legacy C++ ABI setting. A successful load only separates dynamic-link failures from later execution failures; it does not clear the required GPU gate.

Boundaries and handoff

Route training and checkpoint production to the classification or segmentation workflow sub-skills; route dataset layout/conversion to data preparation; and route metrics and prediction artifacts to evaluation. For symptoms and recovery rules, read troubleshooting.

Before handing off a graph adaptation, record:

• input and query shapes at every X-Conv/X-DeConv;
• K*D, K, P, link, decoder-index, and channel checks;
• selected sampler and whether it imports the custom-op wrapper;
• classification or segmentation head output shape for both is_training branches where applicable; and
• TensorFlow API result separately from GPU discovery, shared-library loading, and kernel execution.

A graph-only smoke can validate legacy API presence, static ranks, and some X-Conv tensor algebra. It cannot prove the GPU FPS kernels. Preserve BLOCKED_REQUIRED_BACKEND or a clearly partial status until a bounded GPU operator session completes.