Gradient histogram🔗

Calculates a magnitude-weighted gradient orientation histogram.

Each bin in a gradient orientation histogram stores the sum of the magnitudes of the gradient vectors that point to the direction the bin represents. For example, if each bin represents 10 degrees (angleBins is 36), bin 0 collects magnitudes of gradient vectors whose angle is between -5 and 5 degrees, bin 1 collects angles between 5 and 15 and so on. The last bin (35) collects angles between 345 and 355 (-5) degrees.

Gradient magnitudes are distributed to histogram bins using linear interpolation. In the example above, the magnitude of a vector whose direction is 5 degrees would be split equally between bins 0 and 1.


  • image: Input image.

  • frame: A :ref:coordinate frame <engine/world-coordinates:coordinate-frames> for the rectangle in the world coordinate system.

  • size: The size of the rectangle in which the histogram is calculated. If size is undefined (either width or height is NAN), the histogram is computed from the whole image. Otherwise the region of interest is determined by size and frame.

  • angleBins: The number of quantization bins for gradient angle. 360 means one-degree resolution.

  • unidirectional: If true, gradients with opposing directions contribute to the same histogram bin, producing a histogram with angleBins / 2 entries. This is useful if the presence of an edge is important irrespective of the direction of the transition (dark to bright vs. bright to dark). If false, a full gradient orientation histogram with angleBins entries will be calculated.

  • rotationInvariant: If true, the histogram will be rotated so that its center of mass is at zero. This ensures that the output remains approximately constant even if the input image is rotated. This property is useful if the gradient orientation histogram is used as a feature descriptor in rotation invariant object detection.

  • normalize: If true, each value in the histogram will be divided by the number of pixels that have contributed to the histogram. This makes the histogram insensitive to the size of the image.


  • histogram: Gradient orientation histogram as a vector. The length of the vector depends on angleBins and unidirectional.

  • mainOrientation: The angle corresponding to the center of mass of the histogram. If rotationInvariant is true, this is the location of the center of mass before rotation.