Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added initial docs

Deinterlacing is almost working for fastpng (read)
Intentionally broke setup.py
Updated LICENSE.txt
Removed GIF for now (licensing issues)
  • Loading branch information...
commit cce14e617002455f40fc25a4a70e7c3b3ca05b4a 1 parent a708dac
@ojii authored
View
1  .gitignore
@@ -5,3 +5,4 @@
/dist/
/notpil.egg-info/
/build/
+/docs/_*
View
1  LICENSE.txt
@@ -5,7 +5,6 @@ to see their license.
Files with different licenses:
- pymaging/formats/gif_raw.py: GNU General Public License version 2
pymaging/formats/jpeg_raw.py: Custom license, held by Dr. Tony Lin and IJG
pymaging/formats/png_reader.py: MIT License, held by Johann C. Rocholl,
David Jones and Nicko van Someren.
View
130 docs/Makefile
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Pymaging.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Pymaging.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/Pymaging"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Pymaging"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
View
216 docs/conf.py
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# Pymaging documentation build configuration file, created by
+# sphinx-quickstart on Mon Mar 12 10:51:31 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Pymaging'
+copyright = u'2012, Jonas Obrist'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Pymagingdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'Pymaging.tex', u'Pymaging Documentation',
+ u'Jonas Obrist', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'pymaging', u'Pymaging Documentation',
+ [u'Jonas Obrist'], 1)
+]
View
143 docs/dev/contribute.rst
@@ -0,0 +1,143 @@
+########################
+Contributing to Pymaging
+########################
+
+Like every open-source project, Pymagin is always looking for motivated
+individuals to contribute to it's source code.
+However, to ensure the highest code quality and keep the repository nice and
+tidy, everyone is encouraged to follow a few simple guidelines to make it
+easier for everyone.
+
+
+*********
+Community
+*********
+
+People interested in developing for the Pymaging should join the #pymaging
+IRC channel on `freenode`_ for help and to discuss the development.
+
+
+*************
+In a nutshell
+*************
+
+Here's what the contribution process looks like, in a bullet-points fashion, and
+only for the stuff we host on GitHub:
+
+#. Pymaging is hosted on `GitHub`_, at https://github.com/ojii/pymaging
+#. The best method to contribute back is to create an account there, then fork
+ the project. You can use this fork as if it was your own project, and should
+ push your changes to it.
+#. When you feel your code is good enough for inclusion, "send us a `pull
+ request`_", using the nice GitHub web interface.
+
+
+
+*****************
+Contributing Code
+*****************
+
+
+General
+=======
+
+- Code *must* be tested. Untested patches will be declined.
+- If a patch affects the public facing API, it must document these changes.
+
+Since we're hosted on GitHub, pymagin uses `git`_ as a version control system.
+
+The `GitHub help`_ is very well written and will get you started on using git
+and GitHub in a jiffy. It is an invaluable resource for newbies and old timers
+alike.
+
+
+Syntax and conventions
+======================
+
+We try to conform to `PEP8`_ as much as possible. A few highlights:
+
+- Indentation should be exactly 4 spaces. Not 2, not 6, not 8. **4**. Also, tabs
+ are evil.
+- We try (loosely) to keep the line length at 79 characters. Generally the rule
+ is "it should look good in a terminal-base editor" (eg vim), but we try not be
+ [Godwin's law] about it.
+
+
+Process
+=======
+
+This is how you fix a bug or add a feature:
+
+#. `fork`_ us on GitHub.
+#. Checkout your fork.
+#. Hack hack hack, test test test, commit commit commit, test again.
+#. Push to your fork.
+#. Open a pull request.
+
+
+Tests
+=====
+
+Having a wide and comprehensive library of unit and integration tests is
+of exceeding importance. Contributing tests is widely regarded as a very
+prestigious contribution (you're making everybody's future work much easier by
+doing so). Good karma for you. Cookie points. Maybe even a beer if we meet in
+person :)
+
+If you're unsure how to write tests, feel free to ask for help on IRC.
+
+Running the tests
+-----------------
+
+To run the tests we recommend using ``nose``. If you have ``nose`` installed,
+just run ``nosetests`` in the root directory. If you don't, you can also use
+``python -m unittest discover``.
+
+
+**************************
+Contributing Documentation
+**************************
+
+Perhaps considered "boring" by hard-core coders, documentation is sometimes even
+more important than code! This is what brings fresh blood to a project, and
+serves as a reference for old timers. On top of this, documentation is the one
+area where less technical people can help most - you just need to write a
+semi-decent English. People need to understand you. We don't care about style or
+correctness.
+
+Documentation should be:
+
+- We use `Sphinx`_/`restructuredText`_. File extensions should be .rst.
+- Written in English. We can discuss how it would bring more people to the
+ project to have a Klingon translation or anything, but that's a problem we
+ will ask ourselves when we already have a good documentation in English.
+- Accessible. You should assume the reader to be moderately familiar with
+ Python, but not anything else.
+
+Also, contributing to the documentation will earn you great respect from the
+core developers. You get good karma just like a test contributor, but you get
+double cookie points. Seriously. You rock.
+
+Section style
+=============
+
+We use Python documentation conventions fo section marking:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=``, for sections
+* ``-``, for subsections
+* ``^``, for subsubsections
+* ``"``, for paragraphs
+
+
+.. _fork: http://github.com/ojii/pymaging
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+.. _GitHub : http://www.github.com
+.. _GitHub help : http://help.github.com
+.. _freenode : http://freenode.net/
+.. _pull request : http://help.github.com/send-pull-requests/
+.. _git : http://git-scm.com/
+.. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+
View
0  docs/dev/formats.rst
No changes.
View
0  docs/dev/image.rst
No changes.
View
0  docs/dev/incubator.rst
No changes.
View
22 docs/dev/index.rst
@@ -0,0 +1,22 @@
+#################################
+Pymaging Developers Documentation
+#################################
+
+
+This part of the documentation is about how to develop Pymaging. If you want to
+learn more about how to use it, please read :doc:`/usr/index`.
+
+
+********
+Contents
+********
+
+.. toctree::
+ :maxdepth: 2
+
+ /dev/setup
+ /dev/overview
+ /dev/image
+ /dev/incubator
+ /dev/formats
+ /dev/contribute
View
0  docs/dev/overview.rst
No changes.
View
0  docs/dev/setup.rst
No changes.
View
28 docs/index.rst
@@ -0,0 +1,28 @@
+.. Pymaging documentation master file, created by
+ sphinx-quickstart on Mon Mar 12 10:51:31 2012.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+
+########################################
+Welcome to the Pymaging's documentation!
+########################################
+
+
+********
+Contents
+********
+
+.. toctree::
+ :maxdepth: 2
+
+ usr/index
+ dev/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
View
170 docs/make.bat
@@ -0,0 +1,170 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Pymaging.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Pymaging.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
View
19 docs/usr/index.rst
@@ -0,0 +1,19 @@
+###########################
+Pymaging User Documentation
+###########################
+
+
+This part of the documentation is about how to **use** Pymaging. If you want to
+learn more about it's internals or how to develop for it, please refer to
+:doc:`/dev/index`.
+
+
+********
+Contents
+********
+
+.. toctree::
+ :maxdepth: 2
+
+ /usr/installation
+ /usr/quickstart
View
31 docs/usr/installation.rst
@@ -0,0 +1,31 @@
+############
+Installation
+############
+
+
+************
+Requirements
+************
+
+Python Compatiblity
+===================
+
+Any of the following:
+
+* Python 2.7
+* Python 3.2 or higher
+* PyPy 1.7 or higher
+* Any other Python 2.7/Python 3.2 compatible Python implenentation.
+
+
+Required Python packages
+========================
+
+* ``distribute``
+
+
+**********
+Installing
+**********
+
+Pymaging can not be installed yet.
View
16 docs/usr/quickstart.rst
@@ -0,0 +1,16 @@
+##########
+Quickstart
+##########
+
+
+*****************
+Resizing an image
+*****************
+
+Resizing ``myimage.png`` to 300x300 pixels and save it as ``resized.png``::
+
+ from pymaging import Image
+
+ img = Image.open_from_path('myimage.png')
+ img = img.resize(300, 300)
+ img.save('resized.png')
View
2  pymaging/incubator/formats/__init__.py
@@ -23,10 +23,8 @@
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-from pymaging.incubator.formats.gif import GIF
from pymaging.incubator.formats.png import PNG
INCUBATOR_FORMATS = {
- 'gif': GIF,
'png': PNG,
}
View
39 pymaging/incubator/formats/gif.py
@@ -1,39 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright (c) 2012, Jonas Obrist
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-# * Redistributions of source code must retain the above copyright
-# notice, this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright
-# notice, this list of conditions and the following disclaimer in the
-# documentation and/or other materials provided with the distribution.
-# * Neither the name of the Jonas Obrist nor the
-# names of its contributors may be used to endorse or promote products
-# derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL JONAS OBRIST BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-from pymaging.incubator.formats.gif_raw import ImageLoaderGIF
-
-
-class GIF:
- @staticmethod
- def open(fileobj):
- return None
- # need to make it return an array!
- return ImageLoaderGIF().load(fileobj)
-
- @staticmethod
- def save(image, fileobj):
- raise NotImplementedError()
View
532 pymaging/incubator/formats/gif_raw.py
@@ -1,532 +0,0 @@
-#-*- coding: utf-8 -*-
-#
-# this program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# this program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# if not, write to the Free Software
-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-#
-# The Graphics Interchange Format(c) is the Copyright property of
-# CompuServe Incorporated. GIF(sm) is a Service Mark property of
-# CompuServe Incorporated.
-#
-# The unisys/lzw patent has expired, yes. If anyone puts another patent
-# over this code, you must *burn* this file.
-from array import array
-from pymaging.colors import RGBA
-from pymaging.image import Image
-import struct
-
-'''pygif: gif implementation in python
-
-http://www.java2s.com/Open-Source/Python/Network/emesene/emesene-1.6.2/pygif/pygif.py.htm'''
-
-
-
-KNOWN_FORMATS = ('GIF87a', 'GIF89a')
-
-
-class ImageLoaderGIF(object):
- '''Image loader for gif'''
-
- @staticmethod
- def extensions():
- '''Return accepted extension for this loader'''
- return ('gif', )
-
- def load(self, fileobj):
- format = fileobj.read(6)
- fileobj.seek(0)
- if format not in KNOWN_FORMATS:
- return None
- im = GifDecoder(fileobj.read())
-
- img_data = []
- ls_width = im.ls_width
- ls_height = im.ls_height
- im_images = im.images
- im_palette = im.palette
- pixel_map = array('B', [0]*(ls_width*ls_height*4))
- for img in im_images:
- palette = img.palette if img.local_color_table_flag\
- else im_palette
- have_transparent_color = img.has_transparent_color
- transparent_color = img.transparent_color
- draw_method_replace = 1 \
- if ((img.draw_method == 'replace') or\
- (img.draw_method == 'restore background')) else 0
- pixels = img.pixels
- img_height = img.height
- img_width = img.width
- left = img.left
- top = img.top
- if img_height > ls_height or img_width > ls_width or\
- top > ls_height or left > ls_width:
- img_height = ls_height
- img_width = ls_width
- left = top = 0
- #reverse top to bottom and left to right
- tmp_top = (ls_height - (img_height + top))
- img_width_plus_left = (img_width + left)
- ls_width_multiply_4 = ls_width * 4
- left_multiply_4 = left * 4
- img_data_append = img_data.append
- while img_height > 0:
- i = left
- img_height -= 1
- x = (img_height * img_width) - left
- rgba_pos = (tmp_top * ls_width_multiply_4) + (left_multiply_4)
- tmp_top += 1
- while i < img_width_plus_left:
- #this should now display corrupted gif's
- #instead of crashing on gif's not decoded properly
- try:
- (r, g, b) = palette[pixels[x + i]]
- except:
- rgba_pos += 4
- i += 1
- continue
- # when not magic pink
- if (r, g, b) != (255,0,255):
- if have_transparent_color:
- if transparent_color == pixels[x + i] :
- if draw_method_replace:
- #transparent pixel draw method replace
- pixel_map[rgba_pos + 3] = 0
- rgba_pos += 4
- i += 1
- continue
- #transparent pixel draw method combine
- rgba_pos += 4
- i += 1
- continue
- # this pixel isn't transparent
- #doesn't have transparent color
- (pixel_map[rgba_pos], pixel_map[rgba_pos + 1],\
- pixel_map[rgba_pos + 2]) = (r, g, b)
- pixel_map[rgba_pos + 3] = 255
- # if magic pink move to next pixel
- rgba_pos += 4
- i += 1
-
- img_data_append((ls_width, ls_height, \
- RGBA, pixel_map.tostring()))
- if draw_method_replace:
- pixel_map = array('B', [0]*(ls_width*ls_height*4))
-
- width, height, format, rawpixels = img_data[0]
- return Image(width, height, flat_to_nested(read_raw_pixels(format, rawpixels), width), format)
-
-
-class Gif(object):
- '''Base class to decoder'''
-
- # struct format strings
-
- #17,18:
- FMT_HEADER = '<6sHHBBB'
- #20:
- FMT_IMGDESC = '<HHHHB'
-
- IMAGE_SEPARATOR = 0x2C
- EXTENSION_INTRODUCER = 0x21
- GIF_TRAILER = 0x3b
-
- LABEL_GRAPHIC_CONTROL = 0xF9
- LABEL_COMMENT = 0xFE
- LABEL_PLAINTEXT = 0x01
-
- FMT_EXT_GRAPHIC_CONTROL = '<BBHB' #89a
-
- def __init__( self, data, debug ):
- self.data = data
- self.pointer = 0
-
- # default data for an empty file
- self.header = 'GIF87a'
- self.ls_width = 0
- self.ls_height = 0
- self.flags = 0
- self.color_resolution = 0
- self.sort_flag = 0
- self.color_table_flag = 0
- self.global_color_table_size = 0
- self.background_color = 0
- self.aspect_ratio = 0
- # greyscale palette by default
- self.palette = [(x, x, x) for x in range(0, 256)]
- self.images = []
-
- self.debug_enabled = False
- return
-
- def pop( self, data, length=1 ):
- '''gets the next $len chars from the data stack import
- and increment the pointer'''
-
- start = self.pointer
- end = self.pointer + length
- self.pointer += length
-
- return data[start:end]
-
- def pops( self, format, data ):
- '''pop struct: get size, pop(), unpack()'''
- size = struct.calcsize(format)
- return struct.unpack( format, self.pop(data, size) )
-
- def new_image( self, header=None):
- '''adds a new image descriptor'''
- image = ImageDescriptor(self, header)
- self.images.append(image)
- return image
-
-
-class ImageDescriptor(object):
- '''A class that represents a single image'''
-
- def __init__( self, parent, header=None ):
-
- self.parent = parent
- # this will be set when needed
- self.codesize = 0
-
- # compressed output codes
- self.lzwcode = ''
-
- # uncompressed pixels (decoded)
- self.pixels = []
-
- # we assume a "fullscreen" image
- self.left = self.top = 0
- self.width = parent.ls_width
- self.height = parent.ls_height
-
- # yes, these default flags work...
- self.flags = [False for _ in range(8)]
- self.local_color_table_flag = False
- self.interlace_flag = False
- self.sort_flag = False
- self.local_color_table_size = 0
- self.draw_method = 'replace'
- self.transparent_color = -1
- self.has_transparent_color = 0
- self.palette = []
-
- if header:
- self.setup_header(header)
-
- def setup_header( self, header ):
- '''takes a header tuple and fills the attributes'''
-
- self.left = header[0]
- self.top = header[1]
- self.width = header[2]
- self.height = header[3]
-
- self.flags = get_bits( header[4] )
- self.local_color_table_flag = self.flags[7]
- self.interlace_flag = self.flags[6]
- self.sort_flag = self.flags[5]
- #-- flags 4 and 3 are reserved
- self.local_color_table_size = 2 ** (pack_bits(self.flags[:3]) + 1)
- if self.local_color_table_flag:
- self.palette = self.parent.get_color_table((self.local_color_table_size) * 3)
-
- def get_header(self):
- '''builds a header dynamically'''
- flags = [False for _ in range(8)]
- flags[7] = self.local_color_table_flag
- flags[6] = self.interlace_flag
- flags[5] = self.sort_flag
-
- # useless!
- flags[2], flags[1], flags[0] = get_bits(len(self.palette), bits=3)
-
- return (self.left, self.top, self.width, self.height, pack_bits(flags))
-
- header = property(fget=get_header)
-
-
-class GifDecoder( Gif ):
- '''decodes a gif file into.. something.. else..'''
- def __init__( self, data, debug=False ):
- Gif.__init__( self, data, debug )
- self.fill()
-
- def fill( self ):
- '''reads the data and fills each field of the file'''
-
- # start reading from the beggining of the file
- self.pointer = 0
-
- #17. Header.
- #18. Logical Screen Descriptor.
- data = self.pops( Gif.FMT_HEADER, self.data )
-
- self.header = data[0]
- self.ls_width = data[1]
- self.ls_height = data[2]
- self.background_color = data[4]
- self.aspect_ratio = data[5]
-
- # flags field
- self.flags = get_bits( data[3] )
- #1 bit
- self.color_table_flag = self.flags[7]
- self.sort_flag = self.flags[3]
- #3 bit
- self.color_resolution = pack_bits(self.flags[4:7]) # 7 not included
- #3 bit
- self.global_color_table_size = 2 ** (pack_bits(self.flags[:3]) + 1)
-
- #19. Global Color Table.
- if self.color_table_flag:
- size = (self.global_color_table_size) * 3
- self.palette = self.get_color_table(size)
- else:
- # generate a greyscale palette
- self.palette = [(x, x, x) for x in range(256)]
-
- # blocks
- image = None
- self_data = self.data
- self_pops = self.pops
- Gif_IMAGE_SEPARATOR = Gif.IMAGE_SEPARATOR
- Gif_FMT_IMGDESC = Gif.FMT_IMGDESC
- self_new_image = self.new_image
- self_pop = self.pop
- self_debug_enabled = self.debug_enabled
- self_lzw_decode = self.lzw_decode
- Gif_EXTENSION_INTRODUCER = Gif.EXTENSION_INTRODUCER
- Gif_GIF_TRAILER = Gif.GIF_TRAILER
- Gif_LABEL_GRAPHIC_CONTROL = Gif.LABEL_GRAPHIC_CONTROL
- trans_color = 0
- has_transparent_color = 0
- drw_method = 'replace'
- while True:
- try:
- nextbyte = self_pops('<B', self_data)[0]
- except:
- nextbyte = 0x3b # force end
-
- #20. Image Descriptor
- if nextbyte == Gif_IMAGE_SEPARATOR:
- descriptor = self_pops(Gif_FMT_IMGDESC, self_data)
- image = self_new_image(descriptor)
- image.transparent_color = trans_color
- image.has_transparent_color = has_transparent_color
- image.draw_method = drw_method
- image.codesize = self_pops('<B', self_data)[0]
- image.lzwcode = ''
- image_lzwcode = image.lzwcode
- ###TODO too many corner casses for gifs:(
- table_size = image.local_color_table_size\
- if image.local_color_table_flag and \
- self.global_color_table_size < image.local_color_table_size\
- else self.global_color_table_size
-
- while True:
- try:
- blocksize = self_pops('<B', self_data)[0]
- except:
- break
- if blocksize == 0:
- break # no more image data
- lzwdata = self_pop(self_data, blocksize)
- image_lzwcode = ''.join((image_lzwcode, lzwdata))
-
-
- image.lzwcode = image_lzwcode
- image.pixels = self_lzw_decode(image.lzwcode, image.codesize, \
- table_size)
-
- # Extensions
- elif nextbyte == Gif_EXTENSION_INTRODUCER:
- pass
- # Gif trailer
- elif nextbyte == Gif_GIF_TRAILER:
- return
- elif nextbyte == Gif_LABEL_GRAPHIC_CONTROL:
- #if self_debug_enabled: print 'LABEL_GRAPHIC_CONTROL'
- nextbyte = self_pops('<B', self_data)[0]
- #if self_debug_enabled: print 'block size:%d' %nextbyte
- drw_bits = (get_bits(self_pops('<B', self_data)[0]))
- has_transparent_color = drw_bits[0]
- if drw_bits[2:5] == array('B', [0,0,1]):
- drw_method = 'replace'
- elif (drw_bits[2:5]) == array('B', [0,1,0]):
- drw_method = 'restore background'
- else:
- drw_method = 'restore previous'
- #if self_debug_enabled:
- # print 'draw_method :'+ drw_method
- nextbyte = self_pops('<B', self_data)[0]
- #if self_debug_enabled: print 'fields:%d' %nextbyte
- nextbyte = self_pops('<B', self_data)[0]
- #if self_debug_enabled: print 'duration:%d' %nextbyte # delay?
- nextbyte = self_pops('<B', self_data)[0]
- trans_color = nextbyte
- #if Debug: print 'transparent color index :%d' %trans_color
- pass
- # "No Idea What Is This"
- else:
- pass
-
-
- def string_to_bits(self, string):
- '''high level string unpacker'''
- ordarray = array('B', string)
- bits = array('B')
- bits_append = bits.append
- _get_bits = get_bits
- for byte in ordarray:
- map (bits_append, _get_bits(byte))
- return bits
-
- def readable(self, bool_list):
- '''Converts a list of booleans to a readable list of ints
- Useful for debug only'''
- return [int(x) for x in bool_list]
-
- def bits_to_int(self, bits):
- '''high level bit list packer'''
- c = 1
- i = 0
- for bit in bits:
- if bit:
- i+= 2**(c-1)
- c +=1
- return i
-
- def get_color_table( self, size ):
- '''Returns a color table in the format [(r,g,b),(r,g,b), ...]'''
-
- raw_color_table = self.pops("<%dB" % size, self.data)
- pos = 0
- palette = []
- palette_append = palette.append
-
- while pos + 3 < (size+1):
- red = raw_color_table[pos]
- green = raw_color_table[pos+1]
- blue = raw_color_table[pos+2]
- palette_append((red, green, blue))
- pos += 3
- return palette
-
- def lzw_decode(self, input, initial_codesize, color_table_size):
- '''Decodes a lzw stream from input import
- Returns list of ints (pixel values)'''
- string_table = {}
- output = array('B')
- output_append = output.append
- output_extend = output.extend
- index = 0
-
- bits = self.string_to_bits(input)
- self.bitpointer = 0
-
- codesize = initial_codesize + 1
- clearcode, end_of_info = color_table_size, color_table_size + 1
-
- def pop(size, _bits ):
- ''' return bits '''
- start = self.bitpointer
- end = self.bitpointer = start + size
- return _bits[start: end]
-
- def clear():
- '''Called on clear code'''
- string_table.clear()
- for index in range(color_table_size):
- string_table[index] = chr(index)
- index = end_of_info + 1
- return index
-
- index = clear()
- # skip first (clear)code
- bits = bits[codesize:]
- # read first code, append to output
- self_bits_to_int = self.bits_to_int
-
- code = self_bits_to_int(pop(codesize, bits))
- if code in string_table:
- output_append(ord(string_table[code]))
- else:
- string_table[code] = string_table[0]
- output_append(ord(string_table[code]))
- old = string_table[code]
- bitlen = len(bits)
-
- while self.bitpointer < bitlen:
- # read next code
- code = self_bits_to_int(pop(codesize, bits))
-
- # special code?
- if code == clearcode:
- index = clear()
- codesize = initial_codesize + 1
- code = self_bits_to_int(pop(codesize, bits))
- if code in string_table:
- output_append(ord(string_table[code]))
- else:
- string_table[code] = string_table[0]
- output_append(ord(string_table[code]))
- old = string_table[code]
- continue
-
- elif code == end_of_info:
- break
-
- # code in stringtable?
- if code in string_table:
- c = string_table[code]
- string_table[index] = ''.join((old, c[0]))
- else:
- c = ''.join((old, old[0]))
- string_table[code] = c
-
- index += 1
- old = c
- output_extend(map(ord, c))
-
- if index == 2 ** codesize:
- codesize += 1
- if codesize == 13:
- codesize = 12
-
- return output
-
-
-def get_bits( flags, reverse=False, bits=8 ):
- '''return a list with $bits items, one for each enabled bit'''
-
- mybits = (1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048)[:bits]
-
- rev_num=1
- if reverse:
- rev_num = -1
- ret = array('B')
- ret_append = ret.append
- for bit in mybits[::rev_num]:
- ret_append(flags & bit != 0)
- return ret
-
-def pack_bits( bits ):
- '''convert a bit (bool or int) tuple into a int'''
- packed = 0
- level = 0
- for bit in bits:
- if bit:
- packed += 2 ** level
- level += 1
- return packed
View
10 pymaging/incubator/formats/png_reader.py
@@ -245,25 +245,19 @@ def __init__(self, reader):
def init(self):
if self.current_pass > self.LAST_PASS:
- print 'Done'
self.done = True
return
- print 'PASS', self.current_pass + 1
self.xstart, self.ystart, self.xstep, self.ystep = self.passes[self.current_pass]
- print 'xstart', self.xstart, 'ystart', self.ystart, 'xstep', self.xstep, 'ystep', self.ystep
self.pixels_per_row = int(math.ceil(fdiv(self.reader.width - self.xstart, self.xstep)))
self.row_bytes = int(math.ceil(self.reader.psize * self.pixels_per_row))
if self.ystart >= self.reader.height:
# empty pass
- print 'empty pass ystart', self.ystart, 'is outside the image height', self.reader.height
self.next_pass()
elif self.xstart >= self.reader.width:
- print 'empty pass xstart', self.xstart, 'is outside the image width', self.reader.width
# empty pass
self.next_pass()
else:
self.yiter = irange(self.ystart, self.reader.height, self.ystep)
- print 'yiter', list(irange(self.ystart, self.reader.height, self.ystep))
self.current_y = self.yiter.next()
def next_pass(self):
@@ -282,19 +276,15 @@ def get_scanline_length(self):
def process(self, filter_type, scanline):
if self.done:
raise Adam7Error("Received data after pass 7")
- print 'processing', scanline
data = FILTERS[filter_type](scanline, self.previous_scanline, self.reader.filter_unit)
self.previous_scanline = data
flat = self.serialtoflat(data, self.pixels_per_row)
- print 'current_y', self.current_y
psize = self.reader.psize
# fastpath for pass 7
if self.current_pass == self.LAST_PASS:
- print 'setting */', self.current_y, 'to', flat
self.reader.pixels[self.current_y] = flat
else:
for index, x in enumerate(range(self.xstart, self.reader.width, self.xstep)):
- print 'setting', x, '/', self.current_y, 'to', flat[index:index+psize]
xstart = x * psize
xend = xstart + psize
self.reader.pixels[self.current_y][xstart:xend] = flat[index:index+psize]
View
1  pymaging/incubator/formats/tests.py
@@ -54,7 +54,6 @@ def test_non_indexed(self):
def test_non_indexed_interlaced(self):
img = Image.open_from_path(_get_filepath('black-white-non-indexed-interlaced-adam7.png'))
- print img.pixels
self.assertEqual(img.get_color(0, 0), BLACK)
self.assertEqual(img.get_color(1, 1), BLACK)
self.assertEqual(img.get_color(0, 1), WHITE)
View
3  setup.py
@@ -1,5 +1,8 @@
# -*- coding: utf-8 -*-
from setuptools import setup, find_packages
+
+raise NotImplementedError
+
setup(
name = "pymaging",
version = "0.1",
Please sign in to comment.
Something went wrong with that request. Please try again.