recreate project

vendor/mike42/gfx-php/docs/user/formats.rst

@@ -0,0 +1,159 @@
+File formats
+============
+
+.. contents::
+   :local:
+
+Input formats
+-------------
+
+Files are read from a file or URL by using the :meth:`Image::fromFile()` function:
+
+.. code-block:: php
+  
+  use Mike42\GfxPhp\Image;
+  $tux = Image::fromFile("tux.png")
+
+If the your image is not being read from a file, then :meth:`Image::fromBlob()` can load it from a binary string:
+
+.. code-block:: php
+
+  use Mike42\GfxPhp\Image;
+  $tuxStr = "...";
+  $tux = Image::fromBlob($tuxStr, "tux.png");
+
+In either case, the input format is determined using the file's `magic number`_.
+
+.. _magic number: https://en.wikipedia.org/wiki/Magic_number_(programming)
+
+PNG
+^^^
+
+The PNG codec is used where the input has the ``png`` file extension.
+
+All valid PNG files can be read, including:
+
+- RGB or RGBA images
+- Indexed images
+- Monochrome images, from 1 to 16 bits per pixel
+- Interlaced images
+
+This library currently has limited support for transparency, and will discard any alpha channel from a PNG file when it is loaded.
+
+GIF
+^^^
+
+The GIF codec is used where the input has the ``gif`` file extension. Any well-formed GIF file can be read, but there are some limitations:
+
+- If a GIF file contains multiple images, then only the first one will be loaded
+- If a transparent color is present, then this will be mixed to white
+
+A GIF image will always be loaded into an instance of :class:`IndexedRasterImage`, which makes palette information available.
+
+BMP
+^^^
+
+The BMP codec is used where the input has the ``bmp`` or ``dib`` file extensions. Most uncompressed or run-length encoded bitmap files can be read by this library.
+
+The returned object will be an instance of instance of :class:`IndexedRasterImage` if the color depth is 8 or lower.
+
+24-bit, 16-bit and 32-bit bitmap images are also supported, and will be loaded into an instance of :class:`RgbRasterImage`. If an alpha channel is used, then it will be mixed to white.
+
+Netpbm Formats
+^^^^^^^^^^^^^^
+
+The Netpbm formats are a series of uncompressed bitmap formats, which can represent most types of image. These formats can be read by ``gfx-php``:
+
+:PNM: This is a file extension only. Files carrying ``.pnm`` extension can carry any of the below formats.
+:PPM: This is a color raster format. A PPM file is identified by the P6 magic number, and will be loaded into an instance of :class:`RgbRasterImage`.
+:PGM: This is a monochrome raster format. A PGM file is identified by the P5 magic number, and will be loaded instance of :class:`GrayscaleRasterImage`.
+:PBM: This is a 1-bit bitmap format. A PBM file is identified by the P4 header, and loaded into an instance of :class:`BlackAndWhiteRasterImage`.
+
+Each of these formats has both a binary and text encoding. ``gfx-php`` only supports the binary encodings at this stage.
+
+WBMP
+^^^
+
+The WBMP codec is used where the input has the ``wbmp`` file extension. A WBMP image will always be loaded into a :class:`BlackAndWhiteRasterImage` object.
+
+Output formats
+--------------
+
+When you write a :class:`RasterImage` to a file, you need to specify a filename. The extension on this file is used to determine the desired output format.
+
+There is currently no mechanism to write a file directly to a string.
+
+PNG
+^^^
+
+The PNG format is selected by using the ``png`` file extension when you call :func:`RasterImage::write()`.
+
+.. code-block:: php
+
+  $tux -> write("tux.png");
+
+This library will currently output PNG files as RGB data. If you write to PNG from an instance of :class:`RgbRasterImage`, then no conversion has to be done, so the output is significantly faster.
+
+GIF
+^^^
+
+The GIF format is selected by using the ``gif`` file extension.
+
+.. code-block:: php
+
+  $tux -> write("tux.gif");
+
+This format is limited to using a 256-color palette.
+
+- If your image is not an `IndexedRasterImage`, then it is indexed when you write.
+- If the image uses more than 256 colors, then it will be converted to an 8-bit RGB representation (3 bits red, 3 bits green, 2 bits blue), which introduces some distortions.
+
+When you are creating GIF images, then you can avoid these conversions by using a :class:`IndexedRasterImage` with a palette of fewer than 256 colors.
+
+There is no encoder for multi-image GIF files at this stage.
+
+BMP
+^^^
+
+The BMP format is selected by using the ``bmp`` file extension.
+
+.. code-block:: php
+  
+  $tux -> write("tux.bmp");
+
+This library will currently output BMP files using an uncompressed 24-bit RGB representation of the image.
+
+WBMP
+^^^
+
+The WBMP format is selected by using the ``wbmp`` file extension.
+
+.. code-block:: php
+
+  $tux -> write("tux.wbmp");
+
+The image will be converted to a 1-bit monochrome representation, which is the only type of image supported by WBMP.
+
+Netpbm Formats
+^^^^^^^^^^^^^^
+
+The Netpbm formats can be used for output. Each format is identified by their respective file extension:
+
+.. code-block:: php
+
+  $tux -> write("tux.ppm");
+  $tux -> write("tux.pgm";
+  $tux -> write("tux.pbm");
+
+Since each of these formats has a different raster data representation, you should be aware that 
+
+:PPM: For this output format, the file is converted to a :class:`RgbRasterImage` and typically written with a 24 bit color depth. In some cases, a 48 bit color depth will be used.
+:PGM: The file is converted to a :class:`GrayscaleRasterImage` and written with a depth of 8 or 16 bits per pixel.
+:PPM: The file is converted to a :class:`BlackAndWhiteRasterImage` and written with 1 bit per pixel.
+
+If you want to avoid these conversions, then you should use the ``pnm`` extension to write your files. Since files with this extension can hold any of the above formats, the output encoder will avoid converting the raster data where possible.
+
+.. code-block:: php
+
+  $tux -> write("tux.pnm");
+

vendor/mike42/gfx-php/docs/user/imagetypes.rst

@@ -0,0 +1,61 @@
+Image types
+===========
+
+Every raster image in ``gfx-php`` implements the :class:`RasterImage` interface.
+
+There are several classes that implement this interface, which handle different representations of
+the image data.
+
+:class:`RgbRasterImage`
+  Holds RGB data.
+:class:`GrayscaleRasterImage`
+  Holds monochrome data.
+:class:`BlackAndWhiteRasterImage`
+  Holds 1-bit raster data.
+:class:`IndexedRasterImage`
+  Holds an image and associated palette.
+
+Creating an image
+^^^^^^^^^^^^^^^^^
+
+Each of these classes has a static method which can be used to create an image of that type.
+
+These only require a ``width`` and ``height``.
+
+.. code-block:: php
+
+   use Mike42\GfxPhp\BlackAndWhiteRasterImage;
+   $image = BlackAndWhiteRasterImage::create(50, 100);
+
+Converting between image types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can convert between image types. This is similar to performing a `color-space conversion` in an image editor.
+
+.. code-block:: php
+
+   use Mike42\GfxPhp\Image;
+   $image = Image::load("tux.ppm");
+   $image -> toBlackAndWhite();
+
+The methods to use are:
+
+- :meth:`RasterImage::toBlackAndWhite()`
+- :meth:`RasterImage::toGrayscale()`
+- :meth:`RasterImage::toIndexed()`
+- :meth:`RasterImage::toRgb()`
+
+Each of these returns an image of the requested type. They work by instantiating a new image, then copying across the data as accurately as possible. As a result, the original image is unmodified.
+
+Implicit conversions
+^^^^^^^^^^^^^^^^^^^^
+
+Some file formats only accept specific types of raster data, so the :meth:`RasterImage::write()` method will need to convert it. For example, this ``.pbm`` will be limited to 2 colors, which is achieved by using :meth:`RasterImage:toBlackAndWhite` in the background:
+
+.. code-block:: php
+
+   use Mike42\GfxPhp\Image;
+   $wheel = Image::load("colorwheel.ppm");
+   $wheel -> write("wheel.pbm");
+
+Since converting the color space creates a new image, the image stored in ``$wheel`` is unmodified.

vendor/mike42/gfx-php/docs/user/operations.rst

@@ -0,0 +1,12 @@
+Image operations
+================
+
+You can use this library to perform basic raster operations, such as:
+
+- Crop
+- Scale / resize
+- Color-space conversions
+
+See the ``example/`` sub-folder `on GitHub`_ for usage.
+
+.. _`on GitHub`: https://github.com/mike42/gfx-php/tree/master/example