Docs :: Hawk Vision

1 Hawk Vision

1.1 hawkvision_get_crophint (array $options)

Load the Crop Hint for the image.

Request

	type	default	description
post_id ^*	int	null	Set the `post ID` of an image uploaded to the media library.
type	string	null	Set the type of Crop Hint. `'auto'` or `'manual'` If not specified, `'manual'` will be selected, followed by `'auto'`.
force_analyze	boolean	false	Set whether the image should be analyzed immediately if Auto Crop Hint does not exist in the image. Parsing images requires access to the API, which takes more time than reading stored data.
unit	string	'px'	The unit of the crop hint data in return value. `'px'` or `'%'`

$crophint = hawkvision_get_crophint(array(
	'post_id' => 123
));

Return

(array) The crop hint data.

	type	description
id	int	Crop Hint `ID`
post_id	int	`post ID` of the source image
parent_width	int	Width of the source image (anytime in 'px')
parent_height	int	Height of the source image (anytime in 'px')
width	int	Width of Crop Hint
height	int	Height of Crop Hint
vertices	array	Coordinates for each vertex of Crop Hint
center	array	Central coordinates for Crop Hint
focus	array	Coordinates of the Focus set in Crop Hint
load	string	Data loading source The value takes `'analyzed'` when Crop Hint was immediately analyzed by the method execution, and `'cache'` if has already been cached.
type	string	Type of Crop Hint
unit	string	Unit of the data

SUCCESS

Array
(
    [id] => 202
    [post_id] => 123
    [status] => 'success'
    [parent_width] => 2560
    [parent_height] => 1707
    [width] => 955
    [height] => 1706
    [vertices] => Array
        (
            [0] => Array
                (
                    [x] => 1024
                    [y] => 0
                )

            [1] => Array
                (
                    [x] => 1979
                    [y] => 0
                )

            [2] => Array
                (
                    [x] => 1979
                    [y] => 1706
                )

            [3] => Array
                (
                    [x] => 1024
                    [y] => 1706
                )

        )

    [center] => Array
        (
            [x] => 1501.5
            [y] => 853
		)

    [focus] => Array
        (
            [x] => 1722
            [y] => 648
        )

    [load] => 'cache'
    [type] => 'auto'
    [unit] => 'px'
)

ERROR

Array
(
    [status] => 'error'
    [message] => 'Error message'
)

1.2 hawkvision_get_hintimage (array $options)

Get the metadata of the Hint Image (= cropped image with the Crop Hint).

Request

	type	default	description
post_id ^*	int	null	Set `post ID` of an image uploaded to the media library.
type	string	null	Set the type of Crop Hint. `'auto'` or `'manual'` If not specified, `'manual'` will be selected, followed by `'auto'`.
force_generate	boolean	false	Set whether to immediately generate a Hint Image when it is not yet generated. Because of the image generation process, it may take some time to generate the template page. If a large number of images are generated continuously, the server may be overloaded. If the Hint Image has already been generated, it will load faster.

$hint_image = hawkvision_get_hintimage(array(
	'post_id' => $post_id
));

Return

(array) The metadata of Hint Image.

	type	description
id	int	Crop Hint `ID`
post_id	int	`post ID` of the source image
type	string	Type of Crop Hint
filepath	string	Path of Hint Image
url	string	URL of Hint Image
width	int	Width of Hint Image
height	int	Height of Hint Image
load	int	Data loading source The value takes `'generated'` when Hint Image was immediately generated by the method execution, and `'cache'` if it has already been cached.

SUCCESS

Array
(
    [id] => 202
    [post_id] => 123
    [type] => 'auto'
    [filepath] => 'htdocs/wp/wp-content/uploads/hawkvision/2020/04/image123_ch-auto.jpg'
    [url] => 'https://hawkvision.onotakehiko.com/wp/wp-content/uploads/hawkvision/2020/04/image123_ch-auto.jpg'
    [width] => 955
    [height] => 1706
    [load] => 'cache'
    [status] => 'success'
)

ERROR

Array
(
    [status] => 'error'
    [message] => 'Error message'
)

2 Smart Cropped Images

Smart Cropped Images takes into account the Crop Hint extracted by Cloud Vision AI and smartly crops the image in any aspect ratio.

2.1 hawkvision_get_smartcrop (array $options)

hawkvision_get_smartcrop method retrieves the metadata of the crop area (= Smart Crop) where the Smart Cropped Image is to be trimmed.

Request

	type	default	description
post_id ^*	int	null	Set the `post ID` of an image uploaded to the media library.
type	string	null	Set the type of Crop Hint. `'auto'` or `'manual'` If not specified, `'manual'` will be selected, followed by `'auto'`.
aspect	float	1.0	Set the aspect ratio.
unit	string	'px'	It is possible to specify the unit of the crop hint data of the return value. `'px'` OR `'%'`

$smartcrop = hawkvision_get_smartcrop(array(
	'post_id' => 245,
	'aspect' => .666
));

Return

(array) The metadata of Smart Crop.

	type	description
parent_width	int	Width of the source image (always in 'px')
parent_height	int	Height of the source image (always in 'px')
x	float	X-coordinate of Smart Crop
y	float	Y-coordinate of Smart Crop
width	float	Width of Smart Crop
height	float	Height of Smart Crop
type	string	Type of Crop Hint used as the source of Smart Crop calculation.
unit	int	Unit of the data

SUCCESS

Array
(
    [parent_width] => 2560
    [parent_height] => 1707
    [x] => 1250.12083636
    [y] => 16
    [width] => 1126.206
    [height] => 1691
    [type] => 'manual'
    [unit] => 'px'
)

ERROR

Array
(
    [status] => 'error'
    [message] => 'Error message'
)

2.2 hawkvision_get_sci (array $options)

Reads the image metadata of the Smart Cropped Image culled from the image with the specified post_id.

If Smart Cropped Image is not generated, it returns the data corresponding to the wp_get_attachment_image_src() function runtime.

Request

	type	default	description
post_id ^*	int	null	Set the `post ID` of an image uploaded to the media library.
type	string	null	Set the type of Crop Hint. `'auto'` or `'manual'` If not specified, `'manual'` will be selected, followed by `'auto'`.
size	string	null	Set intermediate image size names in WordPress. You can get the list of WordPress sizes by using `get_intermediate_image_sizes()` function.
aspect	float	1.0	Set the aspect ratio of Smart Cropped Image.
force_generate	boolean	false	Set whether to generate Smart Cropped Image immediately when there was not the image of the specified condition. The process of generating images generally tends to place a high load on the server. We do not recommend an implementation that generates too many Smart Cropped Images at once in a template. Please use the auto-generated presets on the settings page to set the aspect ratio you often use.

$smart_cropped_image = hawkvision_get_sci(array(
	'post_id' => 123,
	'size' => 'w640',
	'aspect' => .666
));

Return

(array) The metadata of Smart Cropped Image.

	type	description
src	array	The image metadata The array structure is equivalent to the return value of `wp_get_attachment_image_src` method.
size	string	The size of the image
aspect	float	Aspect ratio
crophint	int	Type of Crop Hint used as the source of Smart Crop calculation.
is_sci	boolean	Whether the image metadata is Smart Cropped Image or not.
load	int	Data loading source The value takes `'generated'` when Smart Cropped Image has been immediately generated by the method execution, and `'cache'` if it was already been cached.

/* Smart Cropped Image with the specified criteria exists. */
SUCCESS

Array
(
    [status] => 'success'
    [src] => Array
        (
            [0] => 'https://hawkvision.onotakehiko.com/wp/wp-content/uploads/hawkvision/2020/04/image123_ch-manual_sci-666_w640.jpg'
            [1] => 639
            [2] => 960
            [3] => 1
        )

    [size] => 'w640'
    [aspect] => 0.666
    [crophint] => 'manual'
    [is_sci] => 1
    [load] => 'cache'
)

/* Smart Cropped Image with the specified criteria doesn't exists. */
SUCCESS_ERROR

Array
(
    [status] => 'success'
    [src] => Array
        (
            [0] => 'https://hawkvision.onotakehiko.com/wp/wp-content/uploads/hawkvision/2020/04/image123-640x427.jpg'
            [1] => 640
            [2] => 427
            [3] => 1
        )

    [size] => 'w640'
    [aspect] => 1.499
    [is_sci] => 0
)

ERROR

Array
(
    [status] => 'error'
    [message] => 'Error message'
)

3 Dominant Colors

3.1 hawkvision_get_dominant_colors (array $options)

Load the dominant colors of the image.

#e31e1c

#a51f21

#c6c4c6

#ee7272

#67191e

#ae5755

#4e2a33

#ee120a

#a09c9d

#fc1513

Request

	type	default	description
post_id ^*	int	null	Set `post ID` of the image uploaded to the media library.
force_extract	boolean	false	Set whether extraction should be performed immediately if dominant colors data of the image does not exist. Extraction of dominant colors requires access to the API. If a large amount of extraction processing is done continuously in a template, it may take a lot of time to generate pages.

$dominant_colors = hawkvision_get_dominant_colors(array(
	'post_id' => 123
));

Return

(array) Dominant Colors of the image.

	type	description
id	int	Dominant color `ID`
post_id	int	`post ID` of the source image
color_r color_g color_b	int	Value of each RGB component. Each value in range `(0 – 255)`.
hex	int	HEX value
pixel_fraction	int	Image-specific score for this color. Value in range `(0 – 1)`.
score	int	The fraction of pixels the color occupies in the image. Value in range `(0 – 1)`.
percent	int	Percentage of this color in the extracted dominant color. Value in range `(0 – 100)`.

SUCCESS

Array
(
    [status] => success
    [dominant_colors] => Array
        (
            [0] => Array
                (
                    [id] => 776
                    [post_id] => 252
                    [color_r] => 227
                    [color_g] => 30
                    [color_b] => 28
                    [hex] => e31e1c
                    [pixel_fraction] => 0.00673333
                    [score] => 0.236978
                    [percent] => 43.8721
                )

            [1] => Array
                (
                    [id] => 777
                    [post_id] => 252
                    [color_r] => 165
                    [color_g] => 31
                    [color_b] => 33
                    [hex] => a51f21
                    [pixel_fraction] => 0.00406667
                    [score] => 0.0592024
                    [percent] => 10.9603
                )

            [2] => Array
                (
                    [id] => 778
                    [post_id] => 252
                    [color_r] => 198
                    [color_g] => 196
                    [color_b] => 198
                    [hex] => c6c4c6
                    [pixel_fraction] => 0.0618
                    [score] => 0.0549452
                    [percent] => 10.1721
                )

            …
        )
)

ERROR

Array
(
    [status] => 'error'
    [message] => 'Error message'
)