resnet_model.py 22.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Copyright 2017 The TensorFlow Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ==============================================================================
15
"""Contains definitions for Residual Networks.
16

17
Residual networks ('v1' ResNets) were originally proposed in:
18
19
20
[1] Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun
    Deep Residual Learning for Image Recognition. arXiv:1512.03385

21
The full preactivation 'v2' ResNet variant was introduced by:
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
[2] Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun
    Identity Mappings in Deep Residual Networks. arXiv: 1603.05027

The key difference of the full preactivation 'v2' variant compared to the
'v1' variant in [1] is the use of batch normalization before every weight layer
rather than after.
"""

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

import tensorflow as tf

_BATCH_NORM_DECAY = 0.997
_BATCH_NORM_EPSILON = 1e-5
38
DEFAULT_VERSION = 2
39
40
41
DEFAULT_DTYPE = tf.float32
CASTABLE_TYPES = (tf.float16,)
ALLOWED_TYPES = (DEFAULT_DTYPE,) + CASTABLE_TYPES
42

43

Karmel Allison's avatar
Karmel Allison committed
44
################################################################################
45
# Convenience functions for building the ResNet model.
Karmel Allison's avatar
Karmel Allison committed
46
################################################################################
47
48
def batch_norm(inputs, training, data_format):
  """Performs a batch normalization using a standard set of parameters."""
49
50
  # We set fused=True for a significant performance boost. See
  # https://www.tensorflow.org/performance/performance_guide#common_fused_ops
51
  return tf.compat.v1.layers.batch_normalization(
52
53
      inputs=inputs, axis=1 if data_format == 'channels_first' else 3,
      momentum=_BATCH_NORM_DECAY, epsilon=_BATCH_NORM_EPSILON, center=True,
54
      scale=True, training=training, fused=True)
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


def fixed_padding(inputs, kernel_size, data_format):
  """Pads the input along the spatial dimensions independently of input size.

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
    kernel_size: The kernel to be used in the conv2d or max_pool2d operation.
                 Should be a positive integer.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
    A tensor with the same format as the input with the data either intact
    (if kernel_size == 1) or padded (if kernel_size > 1).
  """
  pad_total = kernel_size - 1
  pad_beg = pad_total // 2
  pad_end = pad_total - pad_beg

  if data_format == 'channels_first':
76
77
78
    padded_inputs = tf.pad(tensor=inputs,
                           paddings=[[0, 0], [0, 0], [pad_beg, pad_end],
                                     [pad_beg, pad_end]])
79
  else:
80
81
82
    padded_inputs = tf.pad(tensor=inputs,
                           paddings=[[0, 0], [pad_beg, pad_end],
                                     [pad_beg, pad_end], [0, 0]])
83
84
85
86
  return padded_inputs


def conv2d_fixed_padding(inputs, filters, kernel_size, strides, data_format):
87
88
89
  """Strided 2-D convolution with explicit padding."""
  # The padding is consistent and is based only on `kernel_size`, not on the
  # dimensions of `inputs` (as opposed to using `tf.layers.conv2d` alone).
90
91
92
  if strides > 1:
    inputs = fixed_padding(inputs, kernel_size, data_format)

93
  return tf.compat.v1.layers.conv2d(
94
95
      inputs=inputs, filters=filters, kernel_size=kernel_size, strides=strides,
      padding=('SAME' if strides == 1 else 'VALID'), use_bias=False,
96
      kernel_initializer=tf.compat.v1.variance_scaling_initializer(),
97
98
99
      data_format=data_format)


100
101
102
103
################################################################################
# ResNet block definitions.
################################################################################
def _building_block_v1(inputs, filters, training, projection_shortcut, strides,
104
                       data_format):
Karmel Allison's avatar
Karmel Allison committed
105
106
  """A single block for ResNet v1, without a bottleneck.

107
108
109
110
  Convolution then batch normalization then ReLU as described by:
    Deep Residual Learning for Image Recognition
    https://arxiv.org/pdf/1512.03385.pdf
    by Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun, Dec 2015.
111
112
113
114
115

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
    filters: The number of filters for the convolutions.
116
    training: A Boolean for whether the model is in training or inference
117
      mode. Needed for batch normalization.
118
119
    projection_shortcut: The function to use for projection shortcuts
      (typically a 1x1 convolution when downsampling the input).
120
121
122
123
124
    strides: The block's stride. If greater than 1, this block will ultimately
      downsample the input.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
Karmel Allison's avatar
Karmel Allison committed
125
    The output tensor of the block; shape should match inputs.
126
127
128
129
130
  """
  shortcut = inputs

  if projection_shortcut is not None:
    shortcut = projection_shortcut(inputs)
131
132
    shortcut = batch_norm(inputs=shortcut, training=training,
                          data_format=data_format)
133
134
135
136

  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=strides,
      data_format=data_format)
137
138
  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
139
140
141
142

  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=1,
      data_format=data_format)
143
144
145
  inputs = batch_norm(inputs, training, data_format)
  inputs += shortcut
  inputs = tf.nn.relu(inputs)
146

147
  return inputs
148
149


150
def _building_block_v2(inputs, filters, training, projection_shortcut, strides,
151
                       data_format):
Karmel Allison's avatar
Karmel Allison committed
152
153
  """A single block for ResNet v2, without a bottleneck.

154
155
156
157
  Batch normalization then ReLu then convolution as described by:
    Identity Mappings in Deep Residual Networks
    https://arxiv.org/pdf/1603.05027.pdf
    by Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun, Jul 2016.
158
159
160
161

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
162
    filters: The number of filters for the convolutions.
163
    training: A Boolean for whether the model is in training or inference
164
      mode. Needed for batch normalization.
165
166
    projection_shortcut: The function to use for projection shortcuts
      (typically a 1x1 convolution when downsampling the input).
167
168
169
170
171
    strides: The block's stride. If greater than 1, this block will ultimately
      downsample the input.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
Karmel Allison's avatar
Karmel Allison committed
172
    The output tensor of the block; shape should match inputs.
173
174
  """
  shortcut = inputs
175
176
  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
177
178
179
180
181
182

  # The projection shortcut should come after the first batch norm and ReLU
  # since it performs a 1x1 convolution.
  if projection_shortcut is not None:
    shortcut = projection_shortcut(inputs)

183
184
185
186
187
188
189
190
191
192
193
194
195
196
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=strides,
      data_format=data_format)

  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=1,
      data_format=data_format)

  return inputs + shortcut


def _bottleneck_block_v1(inputs, filters, training, projection_shortcut,
197
                         strides, data_format):
Karmel Allison's avatar
Karmel Allison committed
198
199
  """A single block for ResNet v1, with a bottleneck.

200
201
202
203
204
205
  Similar to _building_block_v1(), except using the "bottleneck" blocks
  described in:
    Convolution then batch normalization then ReLU as described by:
      Deep Residual Learning for Image Recognition
      https://arxiv.org/pdf/1512.03385.pdf
      by Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun, Dec 2015.
Karmel Allison's avatar
Karmel Allison committed
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
    filters: The number of filters for the convolutions.
    training: A Boolean for whether the model is in training or inference
      mode. Needed for batch normalization.
    projection_shortcut: The function to use for projection shortcuts
      (typically a 1x1 convolution when downsampling the input).
    strides: The block's stride. If greater than 1, this block will ultimately
      downsample the input.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
    The output tensor of the block; shape should match inputs.
221
222
223
224
225
226
227
228
  """
  shortcut = inputs

  if projection_shortcut is not None:
    shortcut = projection_shortcut(inputs)
    shortcut = batch_norm(inputs=shortcut, training=training,
                          data_format=data_format)

229
230
231
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=1, strides=1,
      data_format=data_format)
232
233
  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
234
235
236
237

  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=strides,
      data_format=data_format)
238
239
240
241
242
243
244
245
246
247
248
249
250
251
  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)

  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=4 * filters, kernel_size=1, strides=1,
      data_format=data_format)
  inputs = batch_norm(inputs, training, data_format)
  inputs += shortcut
  inputs = tf.nn.relu(inputs)

  return inputs


def _bottleneck_block_v2(inputs, filters, training, projection_shortcut,
252
                         strides, data_format):
kangtop729's avatar
kangtop729 committed
253
  """A single block for ResNet v2, with a bottleneck.
Karmel Allison's avatar
Karmel Allison committed
254

255
256
257
258
259
260
261
  Similar to _building_block_v2(), except using the "bottleneck" blocks
  described in:
    Convolution then batch normalization then ReLU as described by:
      Deep Residual Learning for Image Recognition
      https://arxiv.org/pdf/1512.03385.pdf
      by Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun, Dec 2015.

Karmel Allison's avatar
Karmel Allison committed
262
  Adapted to the ordering conventions of:
263
264
265
266
    Batch normalization then ReLu then convolution as described by:
      Identity Mappings in Deep Residual Networks
      https://arxiv.org/pdf/1603.05027.pdf
      by Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun, Jul 2016.
Karmel Allison's avatar
Karmel Allison committed
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
    filters: The number of filters for the convolutions.
    training: A Boolean for whether the model is in training or inference
      mode. Needed for batch normalization.
    projection_shortcut: The function to use for projection shortcuts
      (typically a 1x1 convolution when downsampling the input).
    strides: The block's stride. If greater than 1, this block will ultimately
      downsample the input.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
    The output tensor of the block; shape should match inputs.
282
283
284
285
286
287
288
289
290
  """
  shortcut = inputs
  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)

  # The projection shortcut should come after the first batch norm and ReLU
  # since it performs a 1x1 convolution.
  if projection_shortcut is not None:
    shortcut = projection_shortcut(inputs)
291

292
293
294
295
296
297
298
299
300
301
302
303
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=1, strides=1,
      data_format=data_format)

  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=filters, kernel_size=3, strides=strides,
      data_format=data_format)

  inputs = batch_norm(inputs, training, data_format)
  inputs = tf.nn.relu(inputs)
304
305
306
307
308
309
310
  inputs = conv2d_fixed_padding(
      inputs=inputs, filters=4 * filters, kernel_size=1, strides=1,
      data_format=data_format)

  return inputs + shortcut


311
312
def block_layer(inputs, filters, bottleneck, block_fn, blocks, strides,
                training, name, data_format):
313
314
315
316
317
318
  """Creates one layer of blocks for the ResNet model.

  Args:
    inputs: A tensor of size [batch, channels, height_in, width_in] or
      [batch, height_in, width_in, channels] depending on data_format.
    filters: The number of filters for the first convolution of the layer.
319
    bottleneck: Is the block created a bottleneck block.
320
321
322
323
324
    block_fn: The block to use within the model, either `building_block` or
      `bottleneck_block`.
    blocks: The number of blocks contained in the layer.
    strides: The stride to use for the first convolution of the layer. If
      greater than 1, this layer will ultimately downsample the input.
325
    training: Either True or False, whether we are currently training the
326
327
328
329
330
331
332
      model. Needed for batch norm.
    name: A string name for the tensor output of the block layer.
    data_format: The input format ('channels_last' or 'channels_first').

  Returns:
    The output tensor of the block layer.
  """
333

334
  # Bottleneck blocks end with 4x the number of filters as they start with
335
  filters_out = filters * 4 if bottleneck else filters
336
337
338
339
340
341
342

  def projection_shortcut(inputs):
    return conv2d_fixed_padding(
        inputs=inputs, filters=filters_out, kernel_size=1, strides=strides,
        data_format=data_format)

  # Only the first block per block_layer uses projection_shortcut and strides
343
  inputs = block_fn(inputs, filters, training, projection_shortcut, strides,
344
345
                    data_format)

346
  for _ in range(1, blocks):
347
    inputs = block_fn(inputs, filters, training, None, 1, data_format)
348
349
350
351

  return tf.identity(inputs, name)


352
class Model(object):
Karmel Allison's avatar
Karmel Allison committed
353
  """Base class for building the Resnet Model."""
354

355
356
  def __init__(self, resnet_size, bottleneck, num_classes, num_filters,
               kernel_size,
357
               conv_stride, first_pool_size, first_pool_stride,
358
               block_sizes, block_strides,
359
               resnet_version=DEFAULT_VERSION, data_format=None,
360
               dtype=DEFAULT_DTYPE):
361
362
363
364
    """Creates a model for classifying an image.

    Args:
      resnet_size: A single integer for the size of the ResNet model.
365
      bottleneck: Use regular blocks or bottleneck blocks.
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
      num_classes: The number of classes used as labels.
      num_filters: The number of filters to use for the first block layer
        of the model. This number is then doubled for each subsequent block
        layer.
      kernel_size: The kernel size to use for convolution.
      conv_stride: stride size for the initial convolutional layer
      first_pool_size: Pool size to be used for the first pooling layer.
        If none, the first pooling layer is skipped.
      first_pool_stride: stride size for the first pooling layer. Not used
        if first_pool_size is None.
      block_sizes: A list containing n values, where n is the number of sets of
        block layers desired. Each value should be the number of blocks in the
        i-th set.
      block_strides: List of integers representing the desired stride size for
        each of the sets of block layers. Should be same length as block_sizes.
381
382
      resnet_version: Integer representing which version of the ResNet network
        to use. See README for details. Valid values: [1, 2]
383
384
      data_format: Input format ('channels_last', 'channels_first', or None).
        If set to None, the format is dependent on whether a GPU is available.
385
386
      dtype: The TensorFlow dtype to use for calculations. If not specified
        tf.float32 is used.
Karmel Allison's avatar
Karmel Allison committed
387
388
389

    Raises:
      ValueError: if invalid version is selected.
390
391
392
393
394
395
396
    """
    self.resnet_size = resnet_size

    if not data_format:
      data_format = (
          'channels_first' if tf.test.is_built_with_cuda() else 'channels_last')

397
398
    self.resnet_version = resnet_version
    if resnet_version not in (1, 2):
399
      raise ValueError(
Karmel Allison's avatar
Karmel Allison committed
400
          'Resnet version should be 1 or 2. See README for citations.')
401
402
403

    self.bottleneck = bottleneck
    if bottleneck:
404
      if resnet_version == 1:
405
406
407
408
        self.block_fn = _bottleneck_block_v1
      else:
        self.block_fn = _bottleneck_block_v2
    else:
409
      if resnet_version == 1:
410
411
412
413
        self.block_fn = _building_block_v1
      else:
        self.block_fn = _building_block_v2

414
415
416
    if dtype not in ALLOWED_TYPES:
      raise ValueError('dtype must be one of: {}'.format(ALLOWED_TYPES))

417
418
419
420
421
422
423
424
425
    self.data_format = data_format
    self.num_classes = num_classes
    self.num_filters = num_filters
    self.kernel_size = kernel_size
    self.conv_stride = conv_stride
    self.first_pool_size = first_pool_size
    self.first_pool_stride = first_pool_stride
    self.block_sizes = block_sizes
    self.block_strides = block_strides
426
    self.dtype = dtype
427
    self.pre_activation = resnet_version == 2
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479

  def _custom_dtype_getter(self, getter, name, shape=None, dtype=DEFAULT_DTYPE,
                           *args, **kwargs):
    """Creates variables in fp32, then casts to fp16 if necessary.

    This function is a custom getter. A custom getter is a function with the
    same signature as tf.get_variable, except it has an additional getter
    parameter. Custom getters can be passed as the `custom_getter` parameter of
    tf.variable_scope. Then, tf.get_variable will call the custom getter,
    instead of directly getting a variable itself. This can be used to change
    the types of variables that are retrieved with tf.get_variable.
    The `getter` parameter is the underlying variable getter, that would have
    been called if no custom getter was used. Custom getters typically get a
    variable with `getter`, then modify it in some way.

    This custom getter will create an fp32 variable. If a low precision
    (e.g. float16) variable was requested it will then cast the variable to the
    requested dtype. The reason we do not directly create variables in low
    precision dtypes is that applying small gradients to such variables may
    cause the variable not to change.

    Args:
      getter: The underlying variable getter, that has the same signature as
        tf.get_variable and returns a variable.
      name: The name of the variable to get.
      shape: The shape of the variable to get.
      dtype: The dtype of the variable to get. Note that if this is a low
        precision dtype, the variable will be created as a tf.float32 variable,
        then cast to the appropriate dtype
      *args: Additional arguments to pass unmodified to getter.
      **kwargs: Additional keyword arguments to pass unmodified to getter.

    Returns:
      A variable which is cast to fp16 if necessary.
    """

    if dtype in CASTABLE_TYPES:
      var = getter(name, shape, tf.float32, *args, **kwargs)
      return tf.cast(var, dtype=dtype, name=name + '_cast')
    else:
      return getter(name, shape, dtype, *args, **kwargs)

  def _model_variable_scope(self):
    """Returns a variable scope that the model should be created under.

    If self.dtype is a castable type, model variable will be created in fp32
    then cast to self.dtype before being used.

    Returns:
      A variable scope for the model.
    """

480
481
    return tf.compat.v1.variable_scope('resnet_model',
                                       custom_getter=self._custom_dtype_getter)
482
483
484
485
486
487
488
489
490
491
492
493
494

  def __call__(self, inputs, training):
    """Add operations to classify a batch of input images.

    Args:
      inputs: A Tensor representing a batch of input images.
      training: A boolean. Set to True to add operations required only when
        training the classifier.

    Returns:
      A logits Tensor with shape [<batch_size>, self.num_classes].
    """

495
496
497
498
499
    with self._model_variable_scope():
      if self.data_format == 'channels_first':
        # Convert the inputs from channels_last (NHWC) to channels_first (NCHW).
        # This provides a large performance boost on GPU. See
        # https://www.tensorflow.org/performance/performance_guide#data_formats
500
        inputs = tf.transpose(a=inputs, perm=[0, 3, 1, 2])
501
502
503
504
505
506

      inputs = conv2d_fixed_padding(
          inputs=inputs, filters=self.num_filters, kernel_size=self.kernel_size,
          strides=self.conv_stride, data_format=self.data_format)
      inputs = tf.identity(inputs, 'initial_conv')

507
508
509
510
511
512
513
514
      # We do not include batch normalization or activation functions in V2
      # for the initial conv1 because the first ResNet unit will perform these
      # for both the shortcut and non-shortcut paths as part of the first
      # block's projection. Cf. Appendix of [2].
      if self.resnet_version == 1:
        inputs = batch_norm(inputs, training, self.data_format)
        inputs = tf.nn.relu(inputs)

515
      if self.first_pool_size:
516
        inputs = tf.compat.v1.layers.max_pooling2d(
517
518
519
520
521
522
523
524
525
526
527
528
529
            inputs=inputs, pool_size=self.first_pool_size,
            strides=self.first_pool_stride, padding='SAME',
            data_format=self.data_format)
        inputs = tf.identity(inputs, 'initial_max_pool')

      for i, num_blocks in enumerate(self.block_sizes):
        num_filters = self.num_filters * (2**i)
        inputs = block_layer(
            inputs=inputs, filters=num_filters, bottleneck=self.bottleneck,
            block_fn=self.block_fn, blocks=num_blocks,
            strides=self.block_strides[i], training=training,
            name='block_layer{}'.format(i + 1), data_format=self.data_format)

530
531
532
533
534
      # Only apply the BN and ReLU for model that does pre_activation in each
      # building/bottleneck block, eg resnet V2.
      if self.pre_activation:
        inputs = batch_norm(inputs, training, self.data_format)
        inputs = tf.nn.relu(inputs)
535
536
537
538
539
540
541

      # The current top layer has shape
      # `batch_size x pool_size x pool_size x final_size`.
      # ResNet does an Average Pooling layer over pool_size,
      # but that is the same as doing a reduce_mean. We do a reduce_mean
      # here because it performs better than AveragePooling2D.
      axes = [2, 3] if self.data_format == 'channels_first' else [1, 2]
542
      inputs = tf.reduce_mean(input_tensor=inputs, axis=axes, keepdims=True)
543
544
      inputs = tf.identity(inputs, 'final_reduce_mean')

545
      inputs = tf.squeeze(inputs, axes)
546
      inputs = tf.compat.v1.layers.dense(inputs=inputs, units=self.num_classes)
547
548
      inputs = tf.identity(inputs, 'final_dense')
      return inputs