Skip to content

Commit 196e229

Browse files
daspecsterdaspecster
committed
Update usage examples to batch.
1 parent bf38cf3 commit 196e229

File tree

1 file changed

+140
-97
lines changed

1 file changed

+140
-97
lines changed

‎docs/vision-usage.rst‎

Lines changed: 140 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,23 @@ Authentication and Configuration
99

1010
- In addition to any authentication configuration, you should also set the
1111
:envvar:`GCLOUD_PROJECT` environment variable for the project you'd like
12-
to interact with. If you are Google App Engine or Google Compute Engine
12+
to interact with. If the GCLOUD_PROJECT environment variable is not present,
13+
the project ID from JSON file credentials is used.
14+
15+
If you are using Google App Engine or Google Compute Engine
1316
this will be detected automatically.
1417

1518
- After configuring your environment, create a
1619
:class:`Client <gcloud.vision.client.Client>`
1720

18-
.. doctest::
21+
.. code-block:: python
1922
2023
>>> from gcloud import vision
2124
>>> client = vision.Client()
2225
23-
or pass in ``credentials`` and ``project`` explicitly
26+
or pass in ``credentials`` and ``project`` explicitly
2427

25-
.. doctest::
28+
.. code-block:: python
2629
2730
>>> from gcloud import vision
2831
>>> client = vision.Client(project='my-project', credentials=creds)
@@ -33,158 +36,198 @@ Annotating an Image
3336
Annotate a single image
3437
~~~~~~~~~~~~~~~~~~~~~~~
3538

36-
.. doctest::
39+
.. code-block:: python
3740
3841
>>> from gcloud import vision
39-
>>> client = vision.Client(project="my-project-name")
40-
>>> with open('/tmp/car.jpg', 'r') as f:
41-
... client.annotate(f.read(), vision.FeatureTypes.LABEL_DETECTION, 3)
42+
>>> client = vision.Client()
43+
>>> image = client.image('./image.png')
44+
>>> faces = image.detect_faces(limit=10)
4245
4346
Annotate multiple images
4447
~~~~~~~~~~~~~~~~~~~~~~~~
4548

46-
.. doctest::
47-
48-
>>> images = (
49-
... ('./image.jpg', [
50-
... vision.FeatureTypes.LABEL_DETECTION,
51-
... vision.FeatureTypes.LANDMARK_DETECTION]),
52-
... ('./image2.jpg', [
53-
... vision.FeatureTypes.FACE_DETECTION,
54-
... vision.FeatureTypes.TEXT_DETECTION]),)
55-
>>> annotated_images = []
56-
>>> for image, feature_types in images:
57-
... annotated_images.append(
58-
... vision_client.annotate(
59-
... image,
60-
... feature_types))
49+
.. code-block:: python
50+
51+
>>> first_image = client.image('./image.jpg')
52+
>>> second_image = client.image('gs://my-storage-bucket/image2.jpg')
53+
>>> with client.batch():
54+
... labels = first_image.detect_labels()
55+
... faces = second_image.detect_faces(limit=10)
56+
57+
or
58+
59+
.. code-block:: python
60+
61+
>>> images = []
62+
>>> images.append(client.image('./image.jpg'))
63+
>>> images.append(client.image('gs://my-storage-bucket/image2.jpg'))
64+
>>> faces = client.detect_faces_multi(images, limit=10)
65+
66+
No results returned
67+
~~~~~~~~~~~~~~~~~~~
6168

6269
Failing annotations return no results for the feature type requested.
6370

64-
.. doctest::
71+
.. code-block:: python
6572
6673
>>> from gcloud import vision
67-
>>> client = vision.Client(project="my-project-name")
68-
>>> with open('/tmp/car.jpg', 'r') as f:
69-
... results = client.annotate(f.read(),
70-
... vision.FeatureTypes.LOGO_DETECTION, 3)
71-
>>> len(results.logos) # 0
74+
>>> client = vision.Client()
75+
>>> image = client.image('./image.jpg')
76+
>>> logos = image.detect_logos(limit=10)
77+
>>> logos
78+
[]
79+
80+
81+
Manual Detection
82+
~~~~~~~~~~~~~~~~
83+
84+
You can call the detection method manually.
85+
86+
.. code-block:: python
87+
88+
>>> from gcloud import vision
89+
>>> client = vision.Client()
90+
>>> image = client.image('gs://my-test-bucket/image.jpg')
91+
>>> faces = image.detect(type=vision.FACE_DETECTION, limit=10)
7292
7393
Face Detection
7494
~~~~~~~~~~~~~~
7595

76-
Annotating using the ``FACE_DETECTION`` feature type.
96+
Detecting a face or faces in an image.
97+
For a list of the possible facial landmarks
98+
see: https://cloud.google.com/vision/reference/rest/v1/images/annotate#type_1
7799

78100

79-
.. doctest::
101+
.. code-block:: python
80102
81103
>>> from gcloud import vision
82-
>>> client = vision.Client(project="my-project-name")
83-
>>> with open('/tmp/car.jpg', 'r') as f:
84-
... results = client.annotate(f.read(),
85-
... vision.FeatureTypes.FACE_DETECTION, 3)
86-
>>> results.faces[0].landmarks[0].type # LEFT_EYE
87-
>>> results.faces[0].landmarks[0].position.x # 1301.2404
88-
>>> results.faces[0].detection_confidence # 0.9863683
89-
>>> results.faces[0].joy_likelihood # 0.54453093
104+
>>> client = vision.Client()
105+
>>> image = client.image('./image.jpg')
106+
>>> faces = image.detect_faces(limit=10)
107+
>>> faces[0].landmarks[0].type
108+
'LEFT_EYE'
109+
>>> faces[0].landmarks[0].position.x
110+
1301.2404
111+
>>> faces[0].detection_confidence
112+
0.9863683
113+
>>> faces[0].joy_likelihood
114+
0.54453093
115+
>>> faces[0].anger_likelihood
116+
0.02545464
117+
90118
91119
92120
Label Detection
93121
~~~~~~~~~~~~~~~
94122

95-
Annotating using the ``LABEL_DETECTION`` feature type.
123+
Image labels are a way to help categorize the contents of an image.
124+
If you have an image with a car, person and a dog it, label detection will
125+
attempt to identify those objects.
96126

97-
.. doctest::
127+
.. code-block:: python
98128
99129
>>> from gcloud import vision
100-
>>> client = vision.Client(project="my-project-name")
101-
>>> with open('/tmp/car.jpg', 'r') as f:
102-
... results = client.annotate(f.read(),
103-
... vision.FeatureTypes.LABEL_DETECTION, 3)
104-
>>> results.labels[0].description # automobile
105-
>>> results.labels[0].score # 0.9794637
106-
>>> results.labels[1].description # vehicle
107-
>>> results.labels[1].score # 0.9494648
108-
>>> results.labels[2].description # sports car
109-
>>> results.labels[2].score # 0.8258028
130+
>>> client = vision.Client()
131+
>>> image = client.image('./image.jpg')
132+
>>> labels = image.detect_labels(limit=3)
133+
>>> labels[0].description
134+
'automobile'
135+
>>> labels[0].score
136+
0.9863683
137+
110138
111139
Landmark Detection
112140
~~~~~~~~~~~~~~~~~~
113141

114-
Annotating using the ``LANDMARK_DETECTION`` feature type.
142+
The API will attemtp to detect landmarks such as Mount Rushmore and
143+
the Sydney Opera House. The API will also provide their known geographical
144+
locations if available.
115145

116-
.. doctest::
146+
.. code-block:: python
117147
118148
>>> from gcloud import vision
119-
>>> client = vision.Client(project="my-project-name")
120-
>>> with open('/tmp/landmark.jpg', 'r') as f:
121-
... results = client.annotate(f.read(),
122-
... vision.FeatureTypes.LANDMARK_DETECTION, 3)
123-
>>> results.landmarks[0].description # Sydney Opera House
124-
>>> results.landmarks[0].locations[0].latitude # -33.857123
125-
>>> results.landmarks[0].locations[0].longitude # 151.213921
126-
>>> results.landmarks[0].bounding_poly.vertices[0].x = 78
127-
>>> results.landmarks[0].bounding_poly.vertices[0].y = 162
149+
>>> client = vision.Client()
150+
>>> image = client.image('./image.jpg')
151+
>>> landmarks = image.detect_landmarks()
152+
>>> landmarks[0].description
153+
'Sydney Opera House'
154+
>>> landmarks[0].locations[0].latitude
155+
-33.857123
156+
>>> landmarks[0].locations[0].longitude
157+
151.213921
158+
>>> landmarks[0].bounding_poly.vertices[0].x
159+
78
160+
>>> landmarks[0].bounding_poly.vertices[0].y
161+
162
128162
129163
Logo Detection
130164
~~~~~~~~~~~~~~
131165

132-
Annotating using the ``LOGO_DETECTION`` feature type.
166+
Google Vision can also attempt to detect company and brand logos in images.
133167

134-
.. doctest::
168+
.. code-block:: python
135169
136170
>>> from gcloud import vision
137-
>>> client = vision.Client(project="my-project-name")
138-
>>> with open('/tmp/logo.jpg', 'r') as f:
139-
... results = client.annotate(f.read(),
140-
... vision.FeatureTypes.LOGO_DETECTION, 3)
141-
>>> results.logos[0].description # Google
142-
>>> results.logos[0].score # 0.9795432
143-
>>> results.logos[0].bounding_poly.vertices[0].x = 78
144-
>>> results.logos[0].bounding_poly.vertices[0].y = 162
171+
>>> client = vision.Client()
172+
>>> image = client.image('./image.jpg')
173+
>>> logos = image.detect_logos(limit=1)
174+
>>> results.logos[0].description
175+
'Google'
176+
>>> logos[0].score
177+
0.9795432
178+
>>> logos[0].bounding_poly.vertices[0].x
179+
78
180+
>>> logos[0].bounding_poly.vertices[0].y
181+
62
145182
146183
Safe Search Detection
147184
~~~~~~~~~~~~~~~~~~~~~
148185

149-
Annotating using the ``SAFE_SEARCH_DETECTION`` feature type.
186+
Detecting safe search properties of an image.
150187

151-
.. doctest::
188+
.. code-block:: python
152189
153190
>>> from gcloud import vision
154-
>>> client = vision.Client(project="my-project-name")
155-
>>> with open('/tmp/logo.jpg', 'r') as f:
156-
... results = client.annotate(f.read(),
157-
... vision.FeatureTypes.SAFE_SEARCH_DETECTION)
158-
>>> results[0].safe.adult # VERY_UNLIKELY
159-
>>> results[0].safe.medical # UNLIKELY
191+
>>> client = vision.Client()
192+
>>> image = client.image('./image.jpg')
193+
>>> safe_search = image.detect_safe_search()
194+
>>> safe_search.adult
195+
'VERY_UNLIKELY'
196+
>>> safe_search.medical
197+
'UNLIKELY'
160198
161199
Text Detection
162200
~~~~~~~~~~~~~~
163201

164-
Annotating using the ``TEXT_DETECTION`` feature type.
202+
Detecting text with ORC from an image.
165203

166-
.. doctest::
204+
.. code-block:: python
167205
168206
>>> from gcloud import vision
169-
>>> client = vision.Client(project="my-project-name")
170-
>>> with open('/tmp/logo.jpg', 'r') as f:
171-
... results = client.annotate(f.read(),
172-
... vision.FeatureTypes.TEXT_DETECTION)
173-
>>> results[0].locale # en
174-
>>> results[0].description # the full text of the image.
207+
>>> client = vision.Client()
208+
>>> image = client.image('./image.jpg')
209+
>>> text = image.detect_text()
210+
>>> text.locale
211+
'en'
212+
>>> text.description
213+
'the full text of the image.'
175214
176215
Image Properties
177216
~~~~~~~~~~~~~~~~
178217

179-
Annotating using the ``IMAGE_PROPERTIES`` feature type.
218+
Detecting image color properties.
180219

181-
.. doctest::
220+
.. code-block:: python
182221
183222
>>> from gcloud import vision
184-
>>> client = vision.Client(project="my-project-name")
185-
>>> with open('/tmp/logo.jpg', 'r') as f:
186-
... results = client.annotate(f.read(),
187-
... vision.FeatureTypes.IMAGE_PROPERTIES)
188-
>>> results[0].dominant_colors.colors[0].color.red # 244
189-
>>> results[0].dominant_colors.colors[0].score # 0.65519291
190-
>>> results[0].dominant_colors.colors[0].pixel_fraction # 0.758658
223+
>>> client = vision.Client()
224+
>>> image = client.image('./image.jpg')
225+
>>> colors = image.detect_properties()
226+
>>> colors[0].red
227+
244
228+
>>> colors[0].blue
229+
134
230+
>>> colors[0].score
231+
0.65519291
232+
>>> colors[0].pixel_fraction
233+
0.758658

0 commit comments

Comments
 (0)