Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/keras/src/layers/convolutional/conv3d.py: 93%

14 statements  

« prev     ^ index     » next       coverage.py v7.4.0, created at 2024-01-03 07:57 +0000

1# Copyright 2015 The TensorFlow Authors. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================== 

15"""Keras 3D convolution layer.""" 

16 

17 

18from keras.src import activations 

19from keras.src import constraints 

20from keras.src import initializers 

21from keras.src import regularizers 

22from keras.src.dtensor import utils 

23from keras.src.layers.convolutional.base_conv import Conv 

24 

25# isort: off 

26from tensorflow.python.util.tf_export import keras_export 

27 

28 

29@keras_export("keras.layers.Conv3D", "keras.layers.Convolution3D") 

30class Conv3D(Conv): 

31 """3D convolution layer (e.g. spatial convolution over volumes). 

32 

33 This layer creates a convolution kernel that is convolved 

34 with the layer input to produce a tensor of 

35 outputs. If `use_bias` is True, 

36 a bias vector is created and added to the outputs. Finally, if 

37 `activation` is not `None`, it is applied to the outputs as well. 

38 

39 When using this layer as the first layer in a model, 

40 provide the keyword argument `input_shape` 

41 (tuple of integers or `None`, does not include the sample axis), 

42 e.g. `input_shape=(128, 128, 128, 1)` for 128x128x128 volumes 

43 with a single channel, 

44 in `data_format="channels_last"`. 

45 

46 Examples: 

47 

48 >>> # The inputs are 28x28x28 volumes with a single channel, and the 

49 >>> # batch size is 4 

50 >>> input_shape =(4, 28, 28, 28, 1) 

51 >>> x = tf.random.normal(input_shape) 

52 >>> y = tf.keras.layers.Conv3D( 

53 ... 2, 3, activation='relu', input_shape=input_shape[1:])(x) 

54 >>> print(y.shape) 

55 (4, 26, 26, 26, 2) 

56 

57 >>> # With extended batch shape [4, 7], e.g. a batch of 4 videos of 

58 >>> # 3D frames, with 7 frames per video. 

59 >>> input_shape = (4, 7, 28, 28, 28, 1) 

60 >>> x = tf.random.normal(input_shape) 

61 >>> y = tf.keras.layers.Conv3D( 

62 ... 2, 3, activation='relu', input_shape=input_shape[2:])(x) 

63 >>> print(y.shape) 

64 (4, 7, 26, 26, 26, 2) 

65 

66 Args: 

67 filters: Integer, the dimensionality of the output space (i.e. the number 

68 of output filters in the convolution). 

69 kernel_size: An integer or tuple/list of 3 integers, specifying the depth, 

70 height and width of the 3D convolution window. Can be a single integer 

71 to specify the same value for all spatial dimensions. 

72 strides: An integer or tuple/list of 3 integers, specifying the strides of 

73 the convolution along each spatial dimension. Can be a single integer to 

74 specify the same value for all spatial dimensions. Specifying any stride 

75 value != 1 is incompatible with specifying any `dilation_rate` value != 

76 1. 

77 padding: one of `"valid"` or `"same"` (case-insensitive). 

78 `"valid"` means no padding. `"same"` results in padding with zeros 

79 evenly to the left/right or up/down of the input such that output has 

80 the same height/width dimension as the input. 

81 data_format: A string, one of `channels_last` (default) or 

82 `channels_first`. The ordering of the dimensions in the inputs. 

83 `channels_last` corresponds to inputs with shape `batch_shape + 

84 (spatial_dim1, spatial_dim2, spatial_dim3, channels)` while 

85 `channels_first` corresponds to inputs with shape `batch_shape + 

86 (channels, spatial_dim1, spatial_dim2, spatial_dim3)`. When unspecified, 

87 uses `image_data_format` value found in your Keras config file at 

88 `~/.keras/keras.json` (if exists) else 'channels_last'. Note that the 

89 `channels_first` format is currently not supported by TensorFlow on CPU. 

90 Defaults to 'channels_last'. 

91 dilation_rate: an integer or tuple/list of 3 integers, specifying the 

92 dilation rate to use for dilated convolution. Can be a single integer to 

93 specify the same value for all spatial dimensions. Currently, specifying 

94 any `dilation_rate` value != 1 is incompatible with specifying any 

95 stride value != 1. 

96 groups: A positive integer specifying the number of groups in which the 

97 input is split along the channel axis. Each group is convolved 

98 separately with `filters / groups` filters. The output is the 

99 concatenation of all the `groups` results along the channel axis. Input 

100 channels and `filters` must both be divisible by `groups`. 

101 activation: Activation function to use. If you don't specify anything, no 

102 activation is applied (see `keras.activations`). 

103 use_bias: Boolean, whether the layer uses a bias vector. 

104 kernel_initializer: Initializer for the `kernel` weights matrix (see 

105 `keras.initializers`). Defaults to 'glorot_uniform'. 

106 bias_initializer: Initializer for the bias vector (see 

107 `keras.initializers`). Defaults to 'zeros'. 

108 kernel_regularizer: Regularizer function applied to the `kernel` weights 

109 matrix (see `keras.regularizers`). 

110 bias_regularizer: Regularizer function applied to the bias vector (see 

111 `keras.regularizers`). 

112 activity_regularizer: Regularizer function applied to the output of the 

113 layer (its "activation") (see `keras.regularizers`). 

114 kernel_constraint: Constraint function applied to the kernel matrix (see 

115 `keras.constraints`). 

116 bias_constraint: Constraint function applied to the bias vector (see 

117 `keras.constraints`). 

118 

119 Input shape: 

120 5+D tensor with shape: `batch_shape + (channels, conv_dim1, conv_dim2, 

121 conv_dim3)` if data_format='channels_first' 

122 or 5+D tensor with shape: `batch_shape + (conv_dim1, conv_dim2, conv_dim3, 

123 channels)` if data_format='channels_last'. 

124 

125 Output shape: 

126 5+D tensor with shape: `batch_shape + (filters, new_conv_dim1, 

127 new_conv_dim2, new_conv_dim3)` if data_format='channels_first' 

128 or 5+D tensor with shape: `batch_shape + (new_conv_dim1, new_conv_dim2, 

129 new_conv_dim3, filters)` if data_format='channels_last'. 

130 `new_conv_dim1`, `new_conv_dim2` and `new_conv_dim3` values might have 

131 changed due to padding. 

132 

133 Returns: 

134 A tensor of rank 5+ representing 

135 `activation(conv3d(inputs, kernel) + bias)`. 

136 

137 Raises: 

138 ValueError: if `padding` is "causal". 

139 ValueError: when both `strides > 1` and `dilation_rate > 1`. 

140 """ 

141 

142 @utils.allow_initializer_layout 

143 def __init__( 

144 self, 

145 filters, 

146 kernel_size, 

147 strides=(1, 1, 1), 

148 padding="valid", 

149 data_format=None, 

150 dilation_rate=(1, 1, 1), 

151 groups=1, 

152 activation=None, 

153 use_bias=True, 

154 kernel_initializer="glorot_uniform", 

155 bias_initializer="zeros", 

156 kernel_regularizer=None, 

157 bias_regularizer=None, 

158 activity_regularizer=None, 

159 kernel_constraint=None, 

160 bias_constraint=None, 

161 **kwargs 

162 ): 

163 super().__init__( 

164 rank=3, 

165 filters=filters, 

166 kernel_size=kernel_size, 

167 strides=strides, 

168 padding=padding, 

169 data_format=data_format, 

170 dilation_rate=dilation_rate, 

171 groups=groups, 

172 activation=activations.get(activation), 

173 use_bias=use_bias, 

174 kernel_initializer=initializers.get(kernel_initializer), 

175 bias_initializer=initializers.get(bias_initializer), 

176 kernel_regularizer=regularizers.get(kernel_regularizer), 

177 bias_regularizer=regularizers.get(bias_regularizer), 

178 activity_regularizer=regularizers.get(activity_regularizer), 

179 kernel_constraint=constraints.get(kernel_constraint), 

180 bias_constraint=constraints.get(bias_constraint), 

181 **kwargs 

182 ) 

183 

184 

185# Alias 

186 

187Convolution3D = Conv3D 

188