code: def equalize(
      tens: Tensor, mask: Tensor = None, by_channels: bool = True
  ) -> Tensor:
      r"""Equalize the image histogram.
  
      Args:
          tens (Tensor): RGB or grayscale image.
          mask (Tensor): An optional mask.  If given, only the pixels selected by the mask are included in the analysis. Maybe 1 channel or 3 channel array.
          by_channels (bool): If True, use equalization by channels separately, else convert image to YCbCr representation and use equalization by `Y` channel.
  
      Returns:
          Equalized image (Tensor)
  
  
      Examples::
  
          >> tens = caer.data.beverages()
          >> equalized = caer.equalize(tens, mask=None)
          >> equalized.shape
          (427,640,3)
  
      """
      if tens.dtype != np.uint8:
          raise TypeError("Image must have uint8 channel type")
  
      if mask is not None:
          if _is_rgb_image(mask) and _is_gray_image(tens):
              raise ValueError(
                  "Wrong mask shape. Image shape: {}. Mask shape: {}".format(
                      tens.shape, mask.shape
                  )
              )
  
          if not by_channels and not _is_gray_image(mask):
              raise ValueError(
                  "When `by_channels=False`, only 1-channel mask is supported. Mask shape: {}".format(
                      mask.shape
                  )
              )
  
      if mask is not None:
          mask = mask.astype(np.uint8)
  
      if _is_gray_image(tens):
          return to_tensor(
              _equalize_cv(tens, mask), override_checks=True
          )
  
      if not by_channels:
          result_tens = cv.cvtColor(tens, cv.COLOR_RGB2YCrCb)
          result_tens[..., 0] = _equalize_cv(result_tens[..., 0], mask)
          tens = cv.cvtColor(result_tens, cv.COLOR_YCrCb2RGB)
          return to_tensor(tens, override_checks=True)
  
      result_tens = np.empty_like(tens)
      for i in range(3):
          if mask is None:
              _mask = None
          elif _is_gray_image(mask):
              _mask = mask
          else:
              _mask = mask[..., i]
  
          result_tens[..., i] = _equalize_cv(tens[..., i], _mask)
  
      return to_tensor(result_tens, override_checks=True)
  
imports: import numpy
  import cv2
  import random
  import collections
  from ..coreten import Tensor, to_tensor
  from .._internal import _check_target_size
  from ..globals import INTER_AREA, INTER_CUBIC, INTER_NEAREST, INTER_LINEAR
  from ..annotations import Union, Tuple, Optional
label_desc: Use image node_id 22 for calling a global function with example usage: equalize(tens, mask, by_channels) and returns: to_tensor, to_tensor, to_tensor