Skip to content

Commit

Permalink
Vision: Harmonize / DRY 'README.rst' / 'docs/index.rst'. (#6003)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tseaver
tseaver authored Sep 21, 2018
1 parent a4cfe84 commit bc741d0
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 108 deletions.
116 changes: 78 additions & 38 deletions vision/README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,101 @@
Python Client for Google Cloud Vision
=====================================

Python idiomatic client for `Google Cloud Vision`_
|pypi| |versions|

.. _Google Cloud Vision: https://cloud.google.com/vision/
The `Google Cloud Vision`_ API enables developers to
understand the content of an image by encapsulating powerful machine
learning models in an easy to use REST API. It quickly classifies images
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
detects individual objects and faces within images, and finds and reads
printed words contained within images. You can build metadata on your
image catalog, moderate offensive content, or enable new marketing
scenarios through image sentiment analysis. Analyze images uploaded
in the request or integrate with your image storage on Google Cloud
Storage.

|pypi| |versions|
- `Client Library Documentation`_
- `Product Documentation`_

- `Documentation`_
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-vision.svg
:target: https://pypi.org/project/google-cloud-vision/
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-vision.svg
:target: https://pypi.org/project/google-cloud-vision/
.. _Vision: https://cloud.google.com/vision/

.. _Google Cloud Vision: https://cloud.google.com/vision/
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/vision/
.. _Product Documentation: https://cloud.google.com/vision/reference/rest/

.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/vision/

Quick Start
-----------

In order to use this library, you first need to go through the following steps:

1. `Select or create a Cloud Platform project.`_
2. `Enable billing for your project.`_
3. `Enable the Google Cloud Vision API.`_
4. `Setup Authentication.`_

.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
.. _Enable the Google Cloud Vision API.: https://cloud.google.com/vision
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html

Installation
~~~~~~~~~~~~

Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
create isolated Python environments. The basic problem it addresses is one of
dependencies and versions, and indirectly permissions.

With `virtualenv`_, it's possible to install this library without needing system
install permissions, and without clashing with the installed system
dependencies.

.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/


Mac/Linux
^^^^^^^^^

.. code-block:: console
$ pip install --upgrade google-cloud-vision
pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-cloud-vision
For more information on setting up your Python development environment,
such as installing ``pip`` and ``virtualenv`` on your system, please refer
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
Windows
^^^^^^^

Authentication
--------------
.. code-block:: console
With ``google-cloud-python`` we try to make authentication as painless as
possible. Check out the `Authentication section`_ in our documentation to
learn more. You may also find the `authentication document`_ shared by all
the ``google-cloud-*`` libraries to be helpful.
pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-cloud-vision
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
Using the API
-------------
Example Usage
~~~~~~~~~~~~~

The Google Cloud `Vision`_ (`Vision API docs`_) API enables developers to
understand the content of an image by encapsulating powerful machine
learning models in an easy to use REST API. It quickly classifies images
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
detects individual objects and faces within images, and finds and reads
printed words contained within images. You can build metadata on your
image catalog, moderate offensive content, or enable new marketing
scenarios through image sentiment analysis. Analyze images uploaded
in the request or integrate with your image storage on Google Cloud
Storage.
.. code-block:: python
.. _Vision: https://cloud.google.com/vision/
.. _Vision API docs: https://cloud.google.com/vision/reference/rest/
from google.cloud import vision
See the ``google-cloud-python`` API `Documentation`_ to learn
how to analyze images using this library.
client = vision.ImageAnnotatorClient()
response = client.annotate_image({
'image': {'source': {'image_uri': 'gs://my-test-bucket/image.jpg'}},
'features': [{'type': vision.enums.Feature.Type.FACE_DETECTION}],
})
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-vision.svg
:target: https://pypi.org/project/google-cloud-vision/
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-vision.svg
:target: https://pypi.org/project/google-cloud-vision/
Next Steps
~~~~~~~~~~

- Read the `Client Library Documentation`_ for Google Cloud Vision API
API to see other available methods on the client.
- Read the `Product documentation`_ to learn
more about the product and see How-to Guides.
78 changes: 8 additions & 70 deletions vision/docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,10 @@
######
Vision
######
.. include:: /../vision/README.rst

The Google Cloud `Vision`_ (`Vision API docs`_) API enables developers to
understand the content of an image by encapsulating powerful machine
learning models in an easy to use REST API. It quickly classifies images
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
detects individual objects and faces within images, and finds and reads
printed words contained within images. You can build metadata on your
image catalog, moderate offensive content, or enable new marketing
scenarios through image sentiment analysis. Analyze images uploaded
in the request or integrate with your image storage on Google Cloud
Storage.
Using the Library
-----------------

.. _Vision: https://cloud.google.com/vision/
.. _Vision API docs: https://cloud.google.com/vision/reference/rest/

************
Installation
************

Install the ``google-cloud-vision`` library using ``pip``:

.. code-block:: console
$ pip install google-cloud-vision
********************************
Authentication and Configuration
********************************

- For an overview of authentication in ``google-cloud-python``,
see :doc:`/core/auth`.

- In addition to any authentication configuration, you should also set the
:envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd
like to interact with. If the :envvar:`GOOGLE_CLOUD_PROJECT` environment
variable is not present, the project ID from JSON file credentials is used.

If you are using Google App Engine or Google Compute Engine
this will be detected automatically.

- After configuring your environment, create a
:class:`~google.cloud.vision_v1.ImageAnnotatorClient`.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.ImageAnnotatorClient()
or pass in ``credentials`` explicitly.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.ImageAnnotatorClient(
... credentials=creds,
... )
*****************
Annotate an Image
*****************
~~~~~~~~~~~~~~~~~

You can call the :meth:`annotate_image` method directly:

Expand All @@ -87,9 +29,8 @@ You can call the :meth:`annotate_image` method directly:
'github'
************************
Single-feature Shortcuts
************************
~~~~~~~~~~~~~~~~~~~~~~~~

If you are only requesting a single feature, you may find it easier to ask
for it using our direct methods:
Expand All @@ -110,9 +51,8 @@ for it using our direct methods:
Likelihood.VERY_LIKELY
****************
No results found
****************
~~~~~~~~~~~~~~~~

If no results for the detection performed can be extracted from the image, then
an empty list is returned. This behavior is similar with all detection types.
Expand All @@ -132,9 +72,8 @@ Example with :meth:`~google.cloud.vision.ImageAnnotatorClient.logo_detection`:
>>> len(response.annotations)
0
*************
API Reference
*************
-------------

This package includes clients for multiple versions of the Vision
API. By default, you will get ``v1``, the latest stable version.
Expand Down Expand Up @@ -169,9 +108,8 @@ An API and type reference is provided for this beta:
gapic/v1p2beta1/api
gapic/v1p2beta1/types

*********
Changelog
*********
---------

For a list of all ``google-cloud-vision`` releases:

Expand Down

0 comments on commit bc741d0

Please sign in to comment.