class_docstr: Implementation of the DPatch attack.
  
  | Paper link: https://arxiv.org/abs/1806.02299v4
class_docstr_tok: ["Implementation","of","the","DPatch","attack",".","|","Paper","link",":","https",":","\/\/arxiv.org\/abs\/1806.02299v4"]
docstr: Augment images with patch.
  
  :param x: Sample images.
  :param patch: The patch to be applied.
  :param random_location: If True apply patch at randomly shifted locations, otherwise place patch at origin
                          (top-left corner).
  :param channels_first: Set channels first or last.
  :param mask: An boolean array of shape equal to the shape of a single samples (1, H, W) or the shape of `x`
               (N, H, W) without their channel dimensions. Any features for which the mask is True can be the
               center location of the patch during sampling.
  :param transforms: Patch transforms, requires `random_location=False`, and `mask=None`.
  :type mask: `np.ndarray`
docstr_tok: ["Augment","images","with","patch",".",":","param","x",":","Sample","images",".",":","param","patch",":","The","patch","to","be","applied",".",":","param","random_location",":","If","True","apply","patch","at","randomly","shifted","locations",",","otherwise","place","patch","at","origin","(","top-left","corner",")",".",":","param","channels_first",":","Set","channels","first","or","last",".",":","param","mask",":","An","boolean","array","of","shape","equal","to","the","shape","of","a","single","samples","(","1",",","H",",","W",")","or","the","shape","of","`","x","`","(","N",",","H",",","W",")","without","their","channel","dimensions",".","Any","features","for","which","the","mask","is","True","can","be","the","center","location","of","the","patch","during","sampling",".",":","param","transforms",":","Patch","transforms",",","requires","`","random_location=False","`",",","and","`","mask=None","`",".",":","type","mask",":","`","np.ndarray","`"]
code: def _augment_images_with_patch(
      x: np.ndarray,
      patch: np.ndarray,
      random_location: bool,
      channels_first: bool,
      mask: Optional[np.ndarray] = None,
      transforms: Optional[List[Dict[str, int]]] = None,
  ) -> Tuple[np.ndarray, List[Dict[str, int]]]:
      """
      Augment images with patch.
  
      :param x: Sample images.
      :param patch: The patch to be applied.
      :param random_location: If True apply patch at randomly shifted locations, otherwise place patch at origin
                              (top-left corner).
      :param channels_first: Set channels first or last.
      :param mask: An boolean array of shape equal to the shape of a single samples (1, H, W) or the shape of `x`
                   (N, H, W) without their channel dimensions. Any features for which the mask is True can be the
                   center location of the patch during sampling.
      :param transforms: Patch transforms, requires `random_location=False`, and `mask=None`.
      :type mask: `np.ndarray`
      """
      if transforms is not None:
          if random_location or mask is not None:
              raise ValueError(
                  "Definition of patch locations in `locations` requires `random_location=False`, and `mask=None`."
              )
  
      random_transformations = []
      x_copy = x.copy()
      patch_copy = patch.copy()
  
      if channels_first:
          x_copy = np.transpose(x_copy, (0, 2, 3, 1))
          patch_copy = np.transpose(patch_copy, (1, 2, 0))
  
      for i_image in range(x.shape[0]):
          if transforms is None:
              if random_location:
                  if mask is None:
                      i_x_1 = random.randint(
                          0, x_copy.shape[1] - 1 - patch_copy.shape[0]
                      )
                      i_y_1 = random.randint(
                          0, x_copy.shape[2] - 1 - patch_copy.shape[1]
                      )
                  else:
                      if mask.shape[0] == 1:
                          mask_2d = mask[0, :, :]
                      else:
                          mask_2d = mask[i_image, :, :]
  
                      edge_x_0 = patch_copy.shape[0] // 2
                      edge_x_1 = patch_copy.shape[0] - edge_x_0
                      edge_y_0 = patch_copy.shape[1] // 2
                      edge_y_1 = patch_copy.shape[1] - edge_y_0
  
                      mask_2d[0:edge_x_0, :] = False
                      mask_2d[-edge_x_1:, :] = False
                      mask_2d[:, 0:edge_y_0] = False
                      mask_2d[:, -edge_y_1:] = False
  
                      num_pos = np.argwhere(mask_2d).shape[0]
                      pos_id = np.random.choice(num_pos, size=1)
                      pos = np.argwhere(mask_2d > 0)[pos_id[0]]
                      i_x_1 = pos[0] - edge_x_0
                      i_y_1 = pos[1] - edge_y_0
  
              else:
                  i_x_1 = 0
                  i_y_1 = 0
  
              i_x_2 = i_x_1 + patch_copy.shape[0]
              i_y_2 = i_y_1 + patch_copy.shape[1]
  
              random_transformations.append(
                  {
                      "i_x_1": i_x_1,
                      "i_y_1": i_y_1,
                      "i_x_2": i_x_2,
                      "i_y_2": i_y_2,
                  }
              )
  
          else:
              i_x_1 = transforms[i_image]["i_x_1"]
              i_x_2 = transforms[i_image]["i_x_2"]
              i_y_1 = transforms[i_image]["i_y_1"]
              i_y_2 = transforms[i_image]["i_y_2"]
  
          x_copy[i_image, i_x_1:i_x_2, i_y_1:i_y_2, :] = patch_copy
  
      if channels_first:
          x_copy = np.transpose(x_copy, (0, 3, 1, 2))
  
      return x_copy, random_transformations
  
file_path: adversarial-robustness-toolbox/art/attacks/evasion/dpatch.py
imports: import logging
  import math
  import random
  from typing import Dict, List, Optional, Tuple, Union, TYPE_CHECKING
  import numpy
  from tqdm.auto import trange
  from art.attacks.attack import EvasionAttack
  from art.estimators.estimator import BaseEstimator, LossGradientsMixin
  from art.estimators.object_detection.object_detector import ObjectDetectorMixin
  from art import config
label_desc: Use image node_id 3 for calling the DPatch obj's underlying member method code with example usage: obj._augment_images_with_patch(x, patch, random_location, channels_first, mask, transforms) and returns: x_copy,  random_transformations