Skip to content

Commit 80db8b3

Browse files
vfdev-5vfdev-5
committed
Add sphynx docs
1 parent 58bd6b3 commit 80db8b3

10 files changed

+386
-96
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
## Linux backup files
44
*~
55

6+
## Docs
7+
docs/src
8+
69
## Arhives
710
*.zip
811

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Build Status](https://travis-ci.org/vfdev-5/ImageTilingUtils.svg?branch=master)](https://travis-ci.org/vfdev-5/ImageTilingUtils)
22
[![Coverage Status](https://coveralls.io/repos/github/vfdev-5/ImageTilingUtils/badge.svg?branch=master)](https://coveralls.io/github/vfdev-5/ImageTilingUtils?branch=master)
3+
[![Documentation Status](https://readthedocs.org/projects/imagetilingutils/badge/?version=latest)](http://imagetilingutils.readthedocs.io/en/latest/?badge=latest)
34

45
# Image Tiling Utils
56
Minimalistic set of image reader agnostic tools to easily iterate over large images

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = ImageTilingUtils
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx
2+
recommonmark
3+
-e git://github.com/snide/sphinx_rtd_theme.git#egg=sphinx_rtd_theme

‎docs/source/conf.py

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/stable/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
import os
16+
import sys
17+
sys.path.insert(0, os.path.abspath('../..'))
18+
import tiling
19+
import sphinx_rtd_theme
20+
from recommonmark.parser import CommonMarkParser
21+
22+
23+
# -- Project information -----------------------------------------------------
24+
25+
project = 'ImageTilingUtils'
26+
copyright = '2018, vfdev-5'
27+
author = 'vfdev-5'
28+
29+
# The short X.Y version
30+
version = 'master (' + tiling.__version__ + ' )'
31+
# The full version, including alpha/beta/rc tags
32+
release = 'master'
33+
34+
35+
# -- General configuration ---------------------------------------------------
36+
37+
# If your documentation needs a minimal Sphinx version, state it here.
38+
#
39+
# needs_sphinx = '1.0'
40+
41+
# Add any Sphinx extension module names here, as strings. They can be
42+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
43+
# ones.
44+
extensions = [
45+
'sphinx.ext.autodoc',
46+
'sphinx.ext.autosummary',
47+
'sphinx.ext.coverage',
48+
'sphinx.ext.mathjax',
49+
'sphinx.ext.napoleon',
50+
'sphinx.ext.viewcode',
51+
]
52+
53+
# Add any paths that contain templates here, relative to this directory.
54+
templates_path = ['_templates']
55+
56+
# The suffix(es) of source filenames.
57+
# You can specify multiple suffix as a list of string:
58+
source_parsers = {
59+
'.md': CommonMarkParser,
60+
}
61+
source_suffix = ['.rst', '.md']
62+
63+
# The master toctree document.
64+
master_doc = 'index'
65+
66+
# The language for content autogenerated by Sphinx. Refer to documentation
67+
# for a list of supported languages.
68+
#
69+
# This is also used if you do content translation via gettext catalogs.
70+
# Usually you set "language" from the command line for these cases.
71+
language = None
72+
73+
# List of patterns, relative to source directory, that match files and
74+
# directories to ignore when looking for source files.
75+
# This pattern also affects html_static_path and html_extra_path .
76+
exclude_patterns = []
77+
78+
# The name of the Pygments (syntax highlighting) style to use.
79+
pygments_style = 'sphinx'
80+
81+
82+
# -- Options for HTML output -------------------------------------------------
83+
84+
# The theme to use for HTML and HTML Help pages. See the documentation for
85+
# a list of builtin themes.
86+
#
87+
html_theme = 'sphinx_rtd_theme'
88+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
89+
90+
# Theme options are theme-specific and customize the look and feel of a theme
91+
# further. For a list of options available for each theme, see the
92+
# documentation.
93+
#
94+
html_theme_options = {
95+
'collapse_navigation': False,
96+
}
97+
98+
# Add any paths that contain custom static files (such as style sheets) here,
99+
# relative to this directory. They are copied after the builtin static files,
100+
# so a file named "default.css" will overwrite the builtin "default.css".
101+
html_static_path = ['_static']
102+
103+
# Custom sidebar templates, must be a dictionary that maps document names
104+
# to template names.
105+
#
106+
# The default sidebars (for documents that don't match any pattern) are
107+
# defined by theme itself. Builtin themes are using these templates by
108+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
109+
# 'searchbox.html']``.
110+
#
111+
# html_sidebars = {}
112+
113+
114+
# -- Options for HTMLHelp output ---------------------------------------------
115+
116+
# Output file base name for HTML help builder.
117+
htmlhelp_basename = 'ImageTilingUtilsdoc'
118+
119+
120+
# -- Options for LaTeX output ------------------------------------------------
121+
122+
latex_elements = {
123+
# The paper size ('letterpaper' or 'a4paper').
124+
#
125+
# 'papersize': 'letterpaper',
126+
127+
# The font size ('10pt', '11pt' or '12pt').
128+
#
129+
# 'pointsize': '10pt',
130+
131+
# Additional stuff for the LaTeX preamble.
132+
#
133+
# 'preamble': '',
134+
135+
# Latex figure (float) alignment
136+
#
137+
# 'figure_align': 'htbp',
138+
}
139+
140+
# Grouping the document tree into LaTeX files. List of tuples
141+
# (source start file, target name, title,
142+
# author, documentclass [howto, manual, or own class]).
143+
latex_documents = [
144+
(master_doc, 'ImageTilingUtils.tex', 'ImageTilingUtils Documentation',
145+
'vfdev-5', 'manual'),
146+
]
147+
148+
149+
# -- Options for manual page output ------------------------------------------
150+
151+
# One entry per manual page. List of tuples
152+
# (source start file, name, description, authors, manual section).
153+
man_pages = [
154+
(master_doc, 'imagetilingutils', 'ImageTilingUtils Documentation',
155+
[author], 1)
156+
]
157+
158+
159+
# -- Options for Texinfo output ----------------------------------------------
160+
161+
# Grouping the document tree into Texinfo files. List of tuples
162+
# (source start file, target name, title, author,
163+
# dir menu entry, description, category)
164+
texinfo_documents = [
165+
(master_doc, 'ImageTilingUtils', 'ImageTilingUtils Documentation',
166+
author, 'ImageTilingUtils', 'One line description of project.',
167+
'Miscellaneous'),
168+
]
169+
170+
# -- Extension configuration -------------------------------------------------

‎docs/source/const_stride.rst

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
tiling.const_stride
2+
===================
3+
4+
.. currentmodule:: tiling.const_stride
5+
6+
Class provides tile parameters (offset, extent) to extract data from image.
7+
8+
Generated tile extents starts from an origin, has constant stride and can optionally include nodata paddings.
9+
For example, tiling can look like this (origin is negative, include nodata)
10+
11+
.. code-block:: text
12+
13+
tile 0 tile 2 tile 4
14+
|<------->| |<------>| |<------>| etc
15+
tile 1 tile 3 tile 5 tile n-1
16+
^ |<------->| |<------>| |<------>| |<------>|
17+
| |<------------------------------------>|
18+
origin | IMAGE |
19+
| |
20+
21+
22+
Another example, tiling can look like this (origin is negative, no nodata, tile size is not constant at boundaries)
23+
24+
.. code-block:: text
25+
26+
tile 0 tile 2 tile 4
27+
|<->| |<------>| |<------>| etc
28+
tile 1 tile 3 tile 5 tile n-1
29+
^ |<------>| |<------>| |<------>| |<->|
30+
| |<------------------------------------>|
31+
origin | IMAGE |
32+
| |
33+
34+
35+
Another example, tiling can look like this (origin is postive, no nodata, tile size is not constant at boundaries)
36+
37+
.. code-block:: text
38+
39+
tile 0 tile 2
40+
|<------->| |<------>| etc
41+
tile 1 tile 3 tile n-1
42+
^ |<------->| |<------>| |<-->|
43+
|<-------------------------------------->|
44+
| | IMAGE |
45+
| origin |
46+
47+
48+
Basic usage:
49+
50+
.. code-block:: python
51+
52+
from tiling import ConstStrideTiles
53+
54+
tiles = ConstStrideTiles(image_size=(500, 500), tile_size=(256, 256), stride=(100, 100))
55+
56+
print("Number of tiles: %i" % len(tiles))
57+
for x, y, width, height, out_width, out_height in tiles:
58+
data = read_data(x, y, width, height, out_width, out_height)
59+
print("data.shape: {}".format(data.shape))
60+
61+
# Get a tile params at linear index:
62+
extent, out_size = tiles[len(tiles)//2]
63+
64+
65+
.. autoclass:: ConstStrideTiles
66+
:members:
67+
:undoc-members:

‎docs/source/index.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
Image Tiling Utils
2+
====================
3+
.. image:: https://travis-ci.org/vfdev-5/ImageTilingUtils.svg?branch=master
4+
:target: https://travis-ci.org/vfdev-5/ImageTilingUtils
5+
6+
.. image:: https://coveralls.io/repos/github/vfdev-5/ImageTilingUtils/badge.svg?branch=master
7+
:target: https://coveralls.io/github/vfdev-5/ImageTilingUtils?branch=master
8+
9+
10+
Minimalistic set of image reader agnostic tools to easily iterate over large images
11+
12+
13+
Installation
14+
------------
15+
16+
Package installation is very simple
17+
18+
.. code-block:: bash
19+
20+
pip install git+https://github.com/vfdev-5/ImageTilingUtils.git
21+
22+
23+
Examples
24+
--------
25+
26+
For more practical examples, see this `notebook <https://github.com/vfdev-5/ImageTilingUtils/blob/master/examples/example_const_stride_tiling.ipynb>`_.
27+
28+
29+
.. toctree::
30+
:maxdepth: 2
31+
:caption: Notes
32+
33+
quickstart
34+
35+
.. toctree::
36+
:maxdepth: 2
37+
:caption: Package Reference
38+
39+
const_stride

‎docs/source/quickstart.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
Quickstart
2+
==========
3+
4+
Let's iterate over a large image with overlapping and extracting always the
5+
same size tiles (in pixels). Let's assume the data access is provided with an example function
6+
7+
8+
.. code-block:: python
9+
10+
def read_data(x, y, width, height, out_width=None, out_height=None):
11+
out_width = width if out_width is None else out_width
12+
out_height = height if out_height is None else out_height
13+
img.read(x, y, width, height, out_width, out_height)
14+
15+
Thus, overlapping tiles can be extracted as
16+
17+
.. code-block:: python
18+
19+
from tiling import ConstStrideTiles
20+
21+
22+
tiles = ConstStrideTiles(image_size=(500, 500), tile_size=(256, 256),
23+
stride=(100, 100))
24+
25+
print("Number of tiles: %i" % len(tiles))
26+
for extent, out_size in tiles:
27+
x, y, width, height = extent
28+
data = read_data(x, y, width, height,
29+
out_width=out_size[0],
30+
out_height=out_size[1])
31+
print("data.shape: {}".format(data.shape))
32+
33+
# Access a tile:
34+
i = len(tiles) // 2
35+
extent, out_size = tiles[i]
36+
37+
38+
.. image:: https://github.com/vfdev-5/ImageTilingUtils/raw/master/examples/example_tiles.png
39+

0 commit comments

Comments
 (0)