=====================
Google Image Grabber
=====================


It provides tools to grab images from a google search by extracting the links of
the images and downloading full resolution images.

This program written in Python is tested on windows 10 64-bit processor.
It uses Selenium to open a browser so as to scroll down to get more images than
possible otherwise. Thus it needs a browser to work correctly. This is on default
set to use chrome browser but if its not found it will use Firefox.
The package comes with chromedriver and geckodriver with it.

Installation
============

To install gImageGrabber do as follow:

.. code-block:: console

    $ pip install gImageGrabber

There are two python files *imgScrape* and *imgTools*.

*imgScrape* has all the utilities needed to run the script but if you want to have additional control functions
you could explore *imgTools*.

Importing
============

This how you can import this module to your script.

.. code-block:: python

    from gimagegrabber import imgScrape
    from gimagegrabber import imgTools


Functions
=========

Building URL
------------

:code:`imgScrape.build_url(search)`

This is to compose a google search URL for your search term.
It takes a :code:`search` argument which specifies your search term of which you
need pictures of.

**Usage** :

.. code-block:: python

    from gimagegrabber import imgScrape

    searchTerm = "kamikaze eminem"

    url = imgScrape.build_url(searchTerm)
    print(url) #FOR DEBUG PURPOSE


Getting Source Data
--------------------

:code:`imgScrape.browser(url, test=False)`

This to start a browser windows and scroll down the webpage
to let more pictures load.It returns a raw source code encoded *utf-8*.
It takes 2 arguments :code:`url` and :code:`test` .

1. :code:`url` is the url of the page it needs to open.

2. :code:`test` is to make the browser scroll down less thus taking less time
   to return the source code. This is useful when you are writing or
   debugging.


It uses Chrome or Firefox to work so make sure you have Google chrome or Firefox
installed at their default directory.

Sometimes you might need to click on **show more images** on webpage to load even more images

If you cant seem to open browser make sure you are on 64-bit OS and that you have chrome
or Firefox installed.

If you are on 32-bit processor you need to use Firefox and you also have to download 32 bit
driver from `here <https://github.com/mozilla/geckodriver/releases>`_ and replace it with the
already present **geckodriver.exe** saved in **driver folder** of the gImageGrabber Module folder.

**Usage** :

.. code-block:: python

    from gimagegrabber import imgScrape

    searchTerm = "Kamikaze"

    url = imgScrape.build_url(searchTerm)
    raw_data = imgScrape.browser(url)
    print(raw_data) #FOR DEBUG PURPOSE


Extracting Links
----------------

:code:`imgScrape.imageLink(html)`

This extracts the original link of the images from the :code:`html` provided.
:code:`html` is the source code of the google image search page.
It returns a dict with format **[ link : file extension ]** . If you want
it in **[file extension : link]** you can use **invDict()** function from imgTools

**Usage** :

.. code-block:: python

    from gimagegrabber import imgScrape
    from gimagegrabber import imgTools

    searchTerm = "Kamikaze"
    debug = False

    url = imgScrape.build_url(searchTerm)
    raw_data = imgScrape.browser(url,debug)
    links = imgScrape.imageLink(raw_data)
    print(links) #FOR DEBUG PURPOSE
    print(imgTools,invDict(links)) #FOR DEBUG PURPOSE

Saving Images
-------------

:code:`imgScrape.saveImages(data, name, onlyType)``

This saves all the images given to it in a list of format
*[link: file extension]*.

It has 3 arguments:

1. :code:`data`  This is to provide  dictionary containing links to images.

2. :code:`name`  This is to provide the name for the folder under which images will be saved.

3. :code:`onlyType`  If you want only a particular file extension then use this mention
   that. If don't want to specify anything pass it a empty string or just don't use that argument.

The format in which it saves images is
Search term

::

    Root folder
    |-- Search Term
        |-- file extension(eg 'jpg')
            |-- 000001.jpg
            |-- 000002.jpg

**Usage** :

.. code-block:: python

    from gimagegrabber import imgScrape

    searchTerm = "Kamikaze"
    extension = '' #save all types of images

    url = imgScrape.build_url(searchTerm)
    raw_data = imgScrape.browser(url)
    links = imgScrape.imageLink(raw_data)
    imgScrape.saveImages(links,searchTerm,extension)

Author
=======

Saksham Sharma
