.. CS116 documentation master file, created by
   sphinx-quickstart on Mon Mar  4 10:37:08 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Picture
=======

We represent pictures as a **list** of `Pixel <pixel.html>`_ objects.

You may construct a blank picture object with a given **width** and **height**.

You may also load a picture object from an image file.


Example Usage
-------------

.. code:: python
   
   # Create a 600x400 picture.
   p1 = Picture(600, 400)
   # Set all its pixels to the color alice_blue.
   p1.setToColor(alice_blue)
   # Show it on the screen.
   p1.show()

   # Load the picture media/beach.png.
   p2 = Picture('media/beach.png')
   # Open it in the interactive picture explorer.
   p2.explore()

Initialization
--------------

To initialize with a given width and height:

.. py:function:: Picture.Picture(self, width, height)

   :param int width: number of pixels wide the picture will be.
   :param int height: number of pixels tall the picture will be.

.. code:: python
   
   # Create a blank a 500x500 picture.
   p = Picture(500, 500)

-------------------------

To initialize from a file:

.. py:function:: Picture.Picture(self, filename)

   :param string filename: the filename of the image file.
   
.. code:: python
   
   # Load the picture 'beach.png' that lives in the 'media' folder.
   p = Picture('media/beach.png')


Methods
-------


This function displays the picture in a window.

.. py:function:: Picture.show(self)

.. code:: python

   picture.show()

This function displays the picture in an interactive window which
lets you click on and examine the pixels' color values.

.. py:function:: Picture.explore(self)

.. code:: python

   picture.explore()

This function will write your picture to a file.

.. py:function:: Picture.write(self, filename)

   :param string filename: desired filename of your saved picture.

.. code:: python

   picture.write('mypicture.png')
   

Getters
-------

This method returns the picture's width.

.. py:function:: Picture.getWidth(self)

.. code:: python

   width = picture.getWidth()
   
This method returns the picture's height.

.. py:function:: Picture.getHeight(self)

.. code:: python

   width = picture.getHeight()

This method returns the list of pixel objects in the picture.

.. py:function:: Picture.getPixels(self)

.. code:: python

   pixels = picture.getPixels()

This method returns the pixel at location x, y.

.. py:function:: Picture.getPixel(self, x, y)

   :param int x: x-location of desired pixel.
   :param int y: y-location of desired pixel.

.. code:: python

   # Get the pixel at location (x=50, y=100)
   pixel = picture.getPixel(50, 100)

.. toctree

