Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorboard/plugins/image/summary_v2.py: 23%

1# Copyright 2018 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"""Image summaries and TensorFlow operations to create them, V2 versions. 

16 

17An image summary stores the width, height, and PNG-encoded data for zero 

18or more images in a rank-1 string array: `[w, h, png0, png1, ...]`. 

19""" 

20 

21 

22from tensorboard.compat import tf2 as tf 

23from tensorboard.plugins.image import metadata 

24from tensorboard.util import lazy_tensor_creator 

25 

26 

27def image(name, data, step=None, max_outputs=3, description=None): 

28 """Write an image summary. 

29 

30 See also `tf.summary.scalar`, `tf.summary.SummaryWriter`. 

31 

32 Writes a collection of images to the current default summary writer. Data 

33 appears in TensorBoard's 'Images' dashboard. Like `tf.summary.scalar` points, 

34 each collection of images is associated with a `step` and a `name`. All the 

35 image collections with the same `name` constitute a time series of image 

36 collections. 

37 

38 This example writes 2 random grayscale images: 

39 

40 ```python 

41 w = tf.summary.create_file_writer('test/logs') 

42 with w.as_default(): 

43 image1 = tf.random.uniform(shape=[8, 8, 1]) 

44 image2 = tf.random.uniform(shape=[8, 8, 1]) 

45 tf.summary.image("grayscale_noise", [image1, image2], step=0) 

46 ``` 

47 

48 To avoid clipping, data should be converted to one of the following: 

49 

50 - floating point values in the range [0,1], or 

51 - uint8 values in the range [0,255] 

52 

53 ```python 

54 # Convert the original dtype=int32 `Tensor` into `dtype=float64`. 

55 rgb_image_float = tf.constant([ 

56 [[1000, 0, 0], [0, 500, 1000]], 

57 ]) / 1000 

58 tf.summary.image("picture", [rgb_image_float], step=0) 

59 

60 # Convert original dtype=uint8 `Tensor` into proper range. 

61 rgb_image_uint8 = tf.constant([ 

62 [[1, 1, 0], [0, 0, 1]], 

63 ], dtype=tf.uint8) * 255 

64 tf.summary.image("picture", [rgb_image_uint8], step=1) 

65 ``` 

66 

67 Arguments: 

68 name: A name for this summary. The summary tag used for TensorBoard will 

69 be this name prefixed by any active name scopes. 

70 data: A `Tensor` representing pixel data with shape `[k, h, w, c]`, 

71 where `k` is the number of images, `h` and `w` are the height and 

72 width of the images, and `c` is the number of channels, which 

73 should be 1, 2, 3, or 4 (grayscale, grayscale with alpha, RGB, RGBA). 

74 Any of the dimensions may be statically unknown (i.e., `None`). 

75 Floating point data will be clipped to the range [0,1]. Other data types 

76 will be clipped into an allowed range for safe casting to uint8, using 

77 `tf.image.convert_image_dtype`. 

78 step: Explicit `int64`-castable monotonic step value for this summary. If 

79 omitted, this defaults to `tf.summary.experimental.get_step()`, which must 

80 not be None. 

81 max_outputs: Optional `int` or rank-0 integer `Tensor`. At most this 

82 many images will be emitted at each step. When more than 

83 `max_outputs` many images are provided, the first `max_outputs` many 

84 images will be used and the rest silently discarded. 

85 description: Optional long-form description for this summary, as a 

86 constant `str`. Markdown is supported. Defaults to empty. 

87 

88 Returns: 

89 True on success, or false if no summary was emitted because no default 

90 summary writer was available. 

91 

92 Raises: 

93 ValueError: if a default writer exists, but no step was provided and 

94 `tf.summary.experimental.get_step()` is None. 

95 """ 

96 summary_metadata = metadata.create_summary_metadata( 

97 display_name=None, description=description 

98 ) 

99 # TODO(https://github.com/tensorflow/tensorboard/issues/2109): remove fallback 

100 summary_scope = ( 

101 getattr(tf.summary.experimental, "summary_scope", None) 

102 or tf.summary.summary_scope 

103 ) 

104 with summary_scope( 

105 name, "image_summary", values=[data, max_outputs, step] 

106 ) as (tag, _): 

107 # Defer image encoding preprocessing by passing it as a callable to write(), 

108 # wrapped in a LazyTensorCreator for backwards compatibility, so that we 

109 # only do this work when summaries are actually written. 

110 @lazy_tensor_creator.LazyTensorCreator 

111 def lazy_tensor(): 

112 tf.debugging.assert_rank(data, 4) 

113 tf.debugging.assert_non_negative(max_outputs) 

114 images = tf.image.convert_image_dtype(data, tf.uint8, saturate=True) 

115 limited_images = images[:max_outputs] 

116 if tf.compat.forward_compatible(2023, 5, 1): 

117 encoded_images = tf.image.encode_png(limited_images) 

118 else: 

119 # TODO(b/276803093): The kernel was updated around 2023/04/15. 

120 # After 90 days (2023/07/15), please remove the False branch. 

121 encoded_images = tf.map_fn( 

122 tf.image.encode_png, 

123 limited_images, 

124 dtype=tf.string, 

125 name="encode_each_image", 

126 ) 

127 # Workaround for map_fn returning float dtype for an empty 

128 # elems input. 

129 encoded_images = tf.cond( 

130 tf.shape(input=encoded_images)[0] > 0, 

131 lambda: encoded_images, 

132 lambda: tf.constant([], tf.string), 

133 ) 

134 image_shape = tf.shape(input=images) 

135 dimensions = tf.stack( 

136 [ 

137 tf.as_string(image_shape[2], name="width"), 

138 tf.as_string(image_shape[1], name="height"), 

139 ], 

140 name="dimensions", 

141 ) 

142 return tf.concat([dimensions, encoded_images], axis=0) 

143 

144 # To ensure that image encoding logic is only executed when summaries 

145 # are written, we pass callable to `tensor` parameter. 

146 return tf.summary.write( 

147 tag=tag, tensor=lazy_tensor, step=step, metadata=summary_metadata 

148 )