open3d.ml.tf.layers.SparseConv

class open3d.ml.tf.layers.SparseConv(*args, **kwargs)

Sparse Convolution.

This layer computes a convolution which is only evaluated at the specified output positions. The layer assumes that input and output points lie on a regular grid.

Example

This shows a minimal example of how to use the layer:

import tensorflow as tf
import open3d.ml.tf as ml3d

# +0.5 to move the points to the voxel center
inp_positions = tf.cast(tf.random.uniform([20,3], 0, 10, dtype=tf.int32), tf.float32)+0.5
inp_features = tf.random.normal([20,8])
out_positions = tf.cast(tf.random.uniform([20,3], 0, 10, dtype=tf.int32), tf.float32)+0.5

conv = ml3d.layers.SparseConv(filters=16, kernel_size=[3,3,3])
out_features = conv(inp_features, inp_positions, out_positions, voxel_size=1.0)
Parameters

  • filters – The number of filters/output channels.

  • kernel_size – The spatial resolution of the filter, e.g. [3,3,3].

  • activation – The activation function to use. None means no activation.

  • use_bias – If True adds an additive bias vector.

  • kernel_initializer – Initializer for the kernel weights.

  • bias_initializer – Initializer for the bias vector.

  • kernel_regularizer – Regularizer for the kernel weights.

  • bias_regularizer – Regularizer for the bias vector.

  • normalize – If true then the result is normalized by the number of input points.

  • offset – A single 3D vector used in the filter coordinate computation. The shape is [3]. This can be used to control how the filters are centered. It will be set automatically for kernels with even sizes.

  • in_channels – This keyword argument is for compatibility with PyTorch. It is not used and in_channels will be inferred at the first execution of the layer.

__init__(filters, kernel_size, activation=None, use_bias=True, kernel_initializer='uniform', bias_initializer='zeros', kernel_regularizer=None, bias_regularizer=None, normalize=False, offset=None, in_channels=None, **kwargs)
build(inp_features_shape)

Creates the variables of the layer (optional, for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(inp_features, inp_positions, out_positions, voxel_size, inp_importance=None, fixed_radius_search_hash_table=None)

This function computes the output features.

Parameters

  • inp_features – A 2D tensor which stores a feature vector for each input point. This argument must be given as a positional argument!

  • inp_positions – A 2D tensor with the 3D point positions of each input point. The coordinates for each point is a vector with format [x,y,z].

  • out_positions – A 2D tensor with the 3D point positions of each output point. The coordinates for each point is a vector with format [x,y,z].

  • voxel_size – A scalar float that defines the edge length of a voxel.

  • inp_importance – Optional scalar importance value for each input point.

  • fixed_radius_search_hash_table – A precomputed hash table generated with build_spatial_hash_table(). This input can be used to explicitly force the reuse of a hash table in special cases and is usually not needed. Note that the hash table must have been generated with the same ‘points’ array. Note that this parameter is only used if ‘extents’ is a scalar.

Returns: A tensor of shape [num output points, filters] with the output

features.

compute_output_shape(inp_features_shape)

Computes the output shape of the layer.

This method will cause the layer’s state to be built, if that has not happened before. This requires that the layer will later be used with inputs that match the input shape provided here.

Parameters

input_shape – Shape tuple (tuple of integers) or list of shape tuples (one per output tensor of the layer). Shape tuples can include None for free dimensions, instead of an integer.

Returns

An input shape tuple.