STILL UNDER DEVELOPMENT - DO NOT USE IN PRODUCTION
Requires PHP 8.0+
For feedback, please contact me.
This package provides an elegant wrapper around Google Vision API and more.
It's an effort to make Google Vision API easy and fun to work with.
Contents
- Installation
- Creating Google Service Account
- Configuration
- Original Responses
- Integration with Laravel
- Face Detection
- Image Text Detection
- Detect Image Properties
- Landmark Detection
- Label Detection
- Logo Detection
- Object Localizer
- Web Detection
Installation
You may install the package via composer:
composer require ahmadmayahi/php-google-vision
Creating Google Service Account
First, you must create a Google service account and setup the configuration object.
Configuration
use AhmadMayahi\Vision\Config;
$config = (new Config())
// optional
->setRequestTimeout(50)
// optional: by default it uses the sys_get_temp_dir() function
->setTempDirPath('/path/to/temp')
// Required: path to your google service account;
->setCredentialsPathname('path/to/google-service-account.json');
Original Responses
All the features come with getOriginalResponse()
method which returns the original response that's generated by PHP Google Vision package.
You may get the original response for any feature as follows:
use AhmadMayahi\Vision\Vision;
$response = (new Vision($config))
->file('/path/to/input/file')
->faceDetection()
->getOriginalResponse();
Depending on the feature, the response type might vary, here is a list of all the response types:
Feature | Response Type |
---|---|
faceDetection |
Google\Protobuf\Internal\RepeatedField contains Google\Cloud\Vision\V1\FaceAnnotation |
imageTextDetection |
Google\Protobuf\Internal\RepeatedField |
imagePropertiesDetection |
Google\Cloud\Vision\V1\ImageProperties |
labelDetection |
Google\Protobuf\Internal\RepeatedField |
landmarkDetection |
Google\Protobuf\Internal\RepeatedField |
logoDetection |
Google\Protobuf\Internal\RepeatedField |
objectLocalizer |
Google\Protobuf\Internal\RepeatedField |
safeSearchDetection |
Google\Cloud\Vision\V1\SafeSearchAnnotation |
The file()
method accepts the following types:
- Local file path:
path/to/your/file
. - Google Storage path:
gs://path/to/file
. - File resource, such as
fopen()
. SplFileInfo
.SplFileObject
.
You may also use the static new
method to instanciate the Vision
object:
use AhmadMayahi\Vision\Vision;
$vision = Vision::new($config)
->file('/path/to/image.jpg')
->faceDetection()
->getOriginalResponse();
Integration with Laravel
Open up the AppServiceProvider
and add the following lines:
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Config;
public function register()
{
$this->app->singleton(Vision::class, function ($app) {
$config = (new Config())
->setCredentialsPathname(config('vision.service_account_path'));
return new Vision($config);
});
}
Using Dependency Injection:
use AhmadMayahi\Vision\Vision;
use Illuminate\Http\Request;
class FaceDetectionController
{
public function detect(Request $request, Vision $vision)
{
$vision = $vision
->file($request->face_file->path())
->faceDetection()
->detect();
// ...
}
}
You may also resolve the object using the app
helper as follows:
use AhmadMayahi\Vision\Vision;
/** @var Vision $vision */
$vision = app(Vision::class);
$result = $vision
->file('path/to/file')
->faceDetection()
->detect();
// ...
Face Detection
Face Detection detects multiple faces within an image along with the associated key facial attributes such as emotional state or wearing headwear
.
The detect
method returns a Generator
of AhmadMayahi\Vision\Data\FaceData
:
use AhmadMayahi\Vision\Vision;
$faces = (new Vision($config))
->file('/path/to/image.jpg')
->faceDetection()
->detect();
echo count($faces). ' faces found';
foreach ($faces as $faceData) {
// How angry the face is?
$faceData->getAnger();
// Surprise reaction?
$faceData->getSurprise();
// Is he/she happy?
$faceData->getJoy();
// Bounds
$faceData->getBounds();
}
getAnger
,getSurprise
andgetJoy
return Likelihoods ratings which are expressed as 6 different values:UNKNOWN
,VERY_UNLIKELY
,UNLIKELY
,POSSIBLE
,LIKELY
, orVERY_LIKELY
. See Likelihood.
Draw box around faces
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Enums\ColorEnum;
$analyzer = (new Vision($config))
->file('/path/to/input/image.jpg')
->faceDetection()
->drawBoxAroundFaces(ColorEnum::MAGENTA)
->toJpeg('faces.jpg'); // Alternatively, you may use "toPng", "toGif", "toBmp".
All the drawing methods return an object of type
AhmadMayahi\Vision\Utils\Image
.
This feature doesn't support Google Storage yet.
Image Text Detection
Get plain text
The getPlainText
returns an object of type AhmadMayahi\Vision\Data\ImageTextData
.
use AhmadMayahi\Vision\Vision;
$response = (new Vision($config))
->file('/path/to/input/image.jpg')
->imageTextDetection()
->getPlainText();
$response->getLocale(); // locale, for example "en" for English
$response->getText(); // Image text
You may also get the plain text using __toString()
:
echo $response;
Get Document
The getDocument
returns an object of type AhmadMayahi\Vision\Data\ImageTextData
.
use AhmadMayahi\Vision\Vision;
$response = (new Vision($config))
->file('/path/to/input/image.jpg')
->imageTextDetection()
->getDocument();
$response->getLocale(); // locale, for example "en" for English
$response->getText(); // Image text
The difference between
getPlainText()
andgetDocuemnt()
is that the first one only retrieves the plain text (no bullets, signs, etc...), whereas the latter one tries to retrieve the entire document (including bullets, symbols, etc...).
Image Properties Detection
The Image Properties feature detects general attributes of the image, such as dominant color.
The detect
method returns a Generator
of AhmadMayahi\Vision\Data\ImagePropertiesData
:
use AhmadMayahi\Vision\Vision;
$properties = (new Vision($config))
->file('/path/to/input/image.jpg')
->imagePropertiesDetection()
->detect();
foreach ($properties as $item) {
$item->getRed();
$item->getBlue();
$item->getGreen();
$item->getPixelFraction();
}
Landmark Detection
Landmark Detection detects popular natural and human-made structures within an image.
use AhmadMayahi\Vision\Vision;
$landmarks = (new Vision($config))
->file('/path/to/baghdad.jpg')
->landmarkDetection()
->detect();
foreach ($landmarks as $landmark) {
$landmark->getName();
// An array containing the detected locations in latitude/longitude format.
$landmark->getLocations();
}
Safe Search Detection
SafeSearch Detection detects explicit content such as adult content or violent content within an image.
The detect
method returns an object of type AhmadMayahi\Vision\Data\SafeSearchData
:
use AhmadMayahi\Vision\Vision;
$result = (new Vision($config))
->file('/path/to/input/image.jpg')
->safeSearchDetection()
->detect();
$result->getAdult();
$result->getMedical();
$result->getViolence();
$result->getRacy();
$result->getSpoof();
Label Detection
Detect and extract information about entities in an image, across a broad group of categories.
The detect
method returns an a Generator
of labels:
use AhmadMayahi\Vision\Vision;
$labels = (new Vision($config))
->file('/path/to/input/image.jpg')
->labelDetection()
->detect();
Logo Detection
Detect and extract information about entities in an image, across a broad group of categories.
The detect
method returns an Generator
of logos:
use AhmadMayahi\Vision\Vision;
$labels = (new Vision($config))
->file('/path/to/input/image.jpg')
->logoDetection()
->detect();
Object Localizer
Object Localizer detects and extract multiple objects in an image with Object Localization.
Detect Objects
The detect
method returns a Generator
of AhmadMayahi\Vision\Data\LocalizedObjectData
:
use AhmadMayahi\Vision\Vision;
$objects = (new Vision($config))
->file('/path/to/image.jpg')
->objectLocalizer()
->detect();
/** @var AhmadMayahi\Vision\Data\LocalizedObjectData $obj */
foreach ($objects as $obj) {
$obj->getName();
$obj->getLanguageCode();
$obj->getMid();
$obj->getNormalizedVertices();
$obj->getScore();
}
Draw Box Around Objects
You may draw box around objects using the drawBoxAroundObjects
method:
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Enums\ColorEnum;
$objects = (new Vision($config))
->file('/path/to/input/image.jpg')
->objectLocalizer()
->drawBoxAroundObjects(ColorEnum::GREEN)
->toJpeg('out.jpg');
The drawBoxAroundObjects()
takes an optionalcallback
as a second parameter:
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Enums\ColorEnum;
use AhmadMayahi\Vision\Support\Image;
use AhmadMayahi\Vision\Data\LocalizedObjectData;
$objects = (new Vision($config))
->file('/path/to/input/image.jpg')
->objectLocalizer()
->drawBoxAroundObjects(ColorEnum::GREEN, function(Image $outputImage, LocalizedObjectData $object) {
// Get GD Image
$outputImage->getImage();
// Get object info
$object->getName();
});
This feature doesn't support Google Storage yet.
Draw Box Around Objects With Text
You may want to draw box around objects and include the object's text as well:
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Enums\ColorEnum;
use AhmadMayahi\Vision\Enums\FontEnum;
use AhmadMayahi\Vision\Support\Image;
use AhmadMayahi\Vision\Data\LocalizedObjectData;
$objects = (new Vision($config))
->file('/path/to/input/image.jpg')
->objectLocalizer()
->drawBoxAroundObjectsWithText(
boxColor: ColorEnum::GREEN,
textColor: ColorEnum::RED,
fontSize: 15,
font: FontEnum::OPEN_SANS_BOLD_ITALIC,
)
->toJpeg('output.jpg');
This feature doesn't support Google Storage yet.
Web Detection
Web Detection detects Web references to an image.
use AhmadMayahi\Vision\Vision;
use AhmadMayahi\Vision\Enums\ColorEnum;
use AhmadMayahi\Vision\Enums\FontEnum;
use AhmadMayahi\Vision\Support\Image;
use AhmadMayahi\Vision\Data\LocalizedObjectData;
$response = (new Vision($config))
->file('/path/to/input/image.jpg')
->webDetection()
->detect();
$response->getFullMatchingImages();
$response->getBestGuessLabels();
$response->getPagesWithMatchingImages();
$response->getPartialMatchingImages();
$response->getVisuallySimilarImages();
$response->getWebEntities();
The detect
method returns either an object of tupe AhmadMayahi\Vision\Data\WebData
or null
value.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.