This is a description of a simple software technical documentation format and process. It is derived from the Unified Software Development Process, simplified towards eXtreme Programming compatibility, and arranged for realisation in a plain text file. (1600 words)
This article presents a documentation format and process made from a simple specialisation of the Unified Software Development Process. The specialisation is tailored toward eXtreme Programming compatibility. The presentation follows the purpose of the book ‘UML Distilled’ — a description of essentials for everyday use.
This documentation form was developed with small projects. Many (perhaps most) software projects are small, and their technical documentation is often an afterthought. Creating a simple pattern for a high-level view at this scale would be useful. And large projects, if well-designed, would have a significant modularisation that might fit this too.
The USDP was chosen as a source because it is one of the best thought-out elucidations of process, architecture, and development. And it is not per se proprietary. XP has an eminent practicality, and the two combine well because they share core principles of user-story motivation, architectural centrality, and iterative development.
The purpose of a distilled documentation is to communicate the high-level system structure in a simple, recognizable and repeatable pattern. The process fixes the making of it to a development project.
The format consists of a single document in plain text. Its content conforms to a minimal ‘syntax’ that has an automated conversion to HTML. UML diagrams are supplemental, if present.
The structure is built mostly of USDP model descriptions. Each is headed by a colloquial summary, and detailed by hierarchical lists.
The process divides production into two periods: Inception and Elaboration. The first develops an initial, partial, draft to express preparational thinking. The second refines the whole, encompassing the iterations to a stable architectural description.
The core notion of USDP documentation is to carry an abstracted ‘architecture description’ through phases. This is composed of views of each of the models, based on architecturally significant use cases — those having the most important functionality and risk.
In XP, the concept of the ‘metaphor’ parallels this, but, though lacking formality, it emphasises the illustrative summary. That must be the guiding intention for this documentation format.
Here is a brief summary of USDP structures used.
The ‘material’ division of the USDP is the model. The models are views of the system, and are a mixture of aspects and levels. They are, with their emphases:
Adapted from USDP section 1.5.1:
A system's external behaviour is described by a set of use cases. Each use case is a sequence of actions that provide the user with a result of value. With some supplementary requirements, this constitutes the requirements model.
This is an initial allocation of the behaviour of the system to a set of objects. The perspective is from the outside, leaving implementational considerations aside.
This defines the static structure of the system as subsystems, classes, and interfaces; and realizes the use-cases as collaborations among those elements.
How the executables etc. are packaged and arranged.
The code. Includes components (representing source code) and the mapping of the classes to components.
An outline of the overall integration tests, and important unit tests. (Not usually included in the USDP architecture description.)
The secondary ‘procedural’ division of the USDP is the phase. A phase is a grouping of iterations covering a major stage in a project's maturity. There are four:
This phase develops the vision of, and business case for, the product. It forms answers to the following questions, from USDP section 1.5.2 and 13.0:
Ultimately it is about gaining a fair amount of confidence that the system is both possible and desirable to develop.
This phase pushes development further by filling in more details of the architecture. The aim being to enable a plan of activities and estimate of resources needed.
In summary, it is about clarifying how and when all parts of the system can be built.
Since only the high-level description is of concern, only Inception and Elaboration are relevant. Thereafter the architecture would be expected to change minimally.
The USDP's divisions of work and role are left aside.
During the initial period of a project the first draft of the document is written.
Almost any development project includes preparational thinking and note-making. That can be channeled into the start of this more disciplined form. This will produce a proto architecture description.
First, the Proposition. This is the most important part — the seed of the whole, answering the most basic questions of the project: what is it, why do it, and can it be done.
Second, the Models. These capture the incipient structure of the software. At this early stage the activity is merely to identify and prioritise most expected elements of the system. Of foremost importance are the use cases, since they drive the next stage of development.
Third, the Plan. This points the way forward to Elaboration, and previews its work. Also, a provisional, but reasonable, estimate can be made of time and resources needed for the whole project.
Recalling the leitmotiv of XP metaphor, all these parts of the document are aimed at illustrative summary.
When is Inception finished? The answer is not a matter of software structure. It is as soon as the project appears possible and desirable, and a cursory survey has been made of the land ahead. For a more XP approach, when there are a set of use cases for the first iteration, that is a clear indication.
The document probably should now be less than 12K or 1500 words.
In this phase the documentation grows into its full form. The work is to inherit and refine from Inception, and expand it with further material.
With the Models, what is needed now is to describe and define the most important elements of the system. Although the detail will be closer to implementation, it needs to be kept above the flux of code.
When is elaboration finished? A more USDP approach would make this a second iteration of preliminary work. And it would continue until no visible risks obstruct any paths of construction. Or, a more XP way would be a gradual solidifying in parallel with construction, continuing until the architecture is stable (The first use cases having been chosen to lead across the whole system early).
The product is a full, light-weight, ‘architecture description’. The document probably should now be less than 32K or 4000 words.
The document is a plain text file, arranged in Markdown ‘syntax’. This is a set of simple conventions for expressing common textual microformats, derived from common email writing styles. Tools can convert this to HTML, although it is perfectly readable merely as text. Here is a brief introduction:
The following example section shows some usages. A complete guide to Markdown is available at http://daringfireball.net/projects/markdown/
The following CSS could be added to the HTML:
/* HXA7241 USDP-Distilled documentation stylesheet */
body
{
color: black;
background-color: white;
font-family: sans-serif;
font-size: 14px;
text-align: left;
text-indent: 0em;
width: 50em;
border: 0 none;
margin-top: 7em;
margin-bottom: 7em;
margin-left: auto;
margin-right: auto;
}
h1
{
font-size: 3em;
font-weight: normal;
margin-top: 0em;
margin-bottom: 1em;
}
h2
{
font-size: 1.75em;
font-weight: normal;
margin-top: 3em;
margin-bottom: 0.5em;
}
h3
{
font-size: 1.2em;
font-weight: bold;
margin-top: 1em;
margin-bottom: 0em;
}
h4
{
font-size: 1em;
font-weight: bold;
margin: 0.5em 0 0.5em 0;
}
h5
{
font-size: 1em;
font-weight: bold;
margin: 0 1.5em 0 0;
float: left;
}
h6
{
font-size: 1em;
font-weight: bold;
margin: 0 1.5em 0 0;
float: left;
}
p
{
text-indent: 0em;
margin-top: 0.5em;
margin-bottom: 0.5em;
}
pre
{
font-family: monospace;
font-size: 1em;
text-align: left;
white-space: pre;
margin-top: 1em;
margin-bottom: 1em;
}
ol, ul
{
margin: 0.5em 2em 0.5em 3em;
padding: 0;
}
dl
{
margin: 0.5em 2em 0.5em 2em;
}
table
{
font-size: 1em;
margin-top: 1em;
}
img
{
border: 1px solid black;
margin: 16px 0 16px 0;
}
code
{
font-family: monospace;
font-size: 1em;
}
li, dt, dd
{
margin-top: 0.25em;
margin-bottom: 0.25em;
}
dt
{
font-weight: bold;
}
a:link, a:visited
{
color: black;
background-color: white;
text-decoration: none;
}
a:hover
{
color: black;
background-color: white;
text-decoration: underline;
}
a:active
{
color: black;
background-color: rgb(208,208,208);
text-decoration: underline;
}
This is a small, less than 5000 line / 2 month, project for a component to be used in high-quality 3D graphics rendering. (Project here.)
The document is 8K and 1000 words. Work on the two phases, including producing the document, took 11 hours.
P3 Tonemapper Architecture Description
======================================
### Harrison Ainsworth ###
<http://www.hxa.name/tonemapper/>
artifex at computer dot org
2005-10-06
Contents
--------
* Proposition
* Requirements
* Analysis
* Design
* Deployment
* Implementation
* Test
* Technical Notes
* Plan
* References
Proposition
-----------
Develop a premium tone-mapper component available as source code and executable.
Implement Ward-Larson's 1997 paper:
> 'A Visibility Matching Tone Reproduction Operator for High Dynamic Range
> Scenes'
> Ward Larson, Rushmeier, Piatko;
> IEEE TVCG 1997.
>
> <http://radsite.lbl.gov/radiance/papers/lbnl39882/tonemap.pdf>
Tone mapping is a necessary stage of rendering, but it is usually an
after-thought. A good component could fill a gap in the open-source rendering
world. It can be well-separated and made reusable without architectural
ramifications. It is quite small and simple, so do-able in a month or two.
Aims:
* well-separated and reusable
* input common/usual/standard images
* output common/usual/standard images
* C++ code
* Windows executable
* Linux executable
* be the best open-source tone-mapper
Requirements
------------
Requirements are simple: there is only one use case, and a few supplementary
features. The use case follows basic command-line tool form: read a file,
process it, output a file. But this is augmented with an options file containing
switches and metadata.
### Use Case ###
(actor - user, or renderer)
1. input command file
2. input HDR image (XYZ, RGB (maybe with conversion))
3. (maybe read output error file, then repeat from first step)
4. receive RGB int (8,16bit) image file (PNG, simple)
### Use Case Features ###
* human or ideal viewer
* manual calibration of for input image
* tone, bloom, color, acuity
* color conversion
* output: RGB int
* output: PNG, simple
Analysis
--------
The primary division is to separate the core processing from everything else
more general. `format` and `image` may later move out to general external
packages.
### Packages ###
* tonemap
-- application specific classes
* format
-- image file formats classes for OpenEXR, PNG and simple
* image
-- image classes with color space awareness
reuse:
* hxa7241_graphics
-- general graphics code
* hxa7241_general
-- very generally useful cross-project code
### Package Dependencies ###
* image
* ImageRgbFloat
* ImageRgbInt
* ColorTransform
* format
* image
* libpng
* OpenEXR
* tonemap
* PerceptualMap
* image
* Foveal
* ImageRgbFloat
* Veil
* ImageRgbFloat
* Foveal
* AcuityFilter
* ImageRgbFloat
* ColorTransform
* ColorAdjustment
* ImageRgbFloat
* ColorTransform
* ToneAdjustment
* ImageRgbFloat
* ImageRgbInt
* Foveal
* all
* general
* graphics
* general
#### reused ####
* general
* Array<>
* Clamps
* FpToInt
* Interval
* Sheet<>
* graphics
* ColorConstants
* Vector3f
* Matrix3f
Design
------
The tonemap package classes fall into three groups: some specialised images,
some image operators, and one overall workflow-context.
### Components/Libraries Reused ###
image file format support:
* OpenEXR
* libpng
### Class Interfaces ###
* PerceptualMap
* construct with options, or defaults
* set options
* map image to image
* Foveal : ImageRgbFloat
* construct from original image
* Veil : ImageRgbFloat
* construct from foveal image
* mix into ImageRgbFloat
* ToneAdjustment
* construct with Foveal and output luminance range
* map ImageRgbFloat to ImageRgbInt
* AcuityFilter
* map ImageRgbFloat to ImageRgbFloat
* ColorAdjustment
* map ImageRgbFloat to ImageRgbFloat
* ImageRgbFloat : Sheet<Vector3f>
* access color conversion
* ImageRgbInt : Sheet<Vector3w>
* read pixels as word array
* ColorTransform
* construct with options
* set options
* convert a triple, forward or back
* format
* read RGB EXR into RGB float triples
* write RGB int triples into PNG, ...
### Sequences ###
1. read command file
2. read original image file
3. make PerceptualMap
4. map original image to final image
1. make foveal image
2. apply human viewer limitations
1. make veil image
2. mix veil into foveal image
3. mix veil into original image
4. adjust original image for color sensitivity
5. filter original image for acuity
3. make ToneAdjustment
1. make histogram
2. adjust histogram
3. make cumulative function from histogram
4. map original image with ToneAdjustment
5. write final image file
Deployment
----------
A simple, basic form eases portability, and the usage allows it, so: a
command-line program is best. This could also be packaged as a dynamic-link
library. Maybe the image format readers could be externalised as plugins.
* command-line program
* in: (commands, HDR image (standard format))
* out: (RGB (standard format), log)
* dynamic-link library
* alternative version of command-line program
* image format reader and writer plugins
* could find dynamic-link libraries, and give each a chance to read
Implementation
--------------
Just straightforward, portable C++.
* C++, with exceptions, minimal template use, no RTTI
* MSToolkit or MinGW compilers
* nothing platform specific
Test
----
Not decided yet...
Something precise and numerical is desirable.
There are some source and result images, using the same algorithm, at:
<http://www.anyhere.com/gward/hdrenc/pages/originals.html>
Technical Notes
---------------
1. input original image
* pixels: RGB float (maybe with color space)
2. make image of foveal values
* pixels: RGB float
* (box/cheap) filter to 1 degree/pixel size
* pixelcount = 2 * tan( viewangle / 2 ) / 0.01745
3. human viewer
* make image of veil, from foveal image
* pixels: RGB float
* same resolution as foveal image
* (color, not just luminance)
* (slowest part - big convolution ...)
* mix veil into foveal
* mix veil into original
* (with a bilinear interpolation)
* adjust original image for color sensitivity
* needs conversion to XYZ (to get foveal luminance)
* filter original image for acuity
* needs conversion to XYZ (to get foveal luminance)
* variable blur - mipmap?
4. make histogram, from foveal image
* needs conversion to XYZ
* elements: log10 of luminances
* 100 bins
* min = min val, clamped to min of 10^-4
* max = max val
* log10lum -> log10lum
* (linearly interpolatable)
5. adjust histogram
* clamp counts, using iterative convergence
* linear ceiling - ideal viewer
* varying ceiling - human viewer
6. map original image with histogram
7. output final image
* pixels: RGB int
command file:
* input image
* optional color space
* is human viewer
* is glare
* is color sense
* is acuity
* display
* black luminance
* white luminance
(luminance is cd/m^2, remember?)
Plan
----
### estimate ###
* total size: 2300 lines (discluding reuse)
* rate: 3 minutes per line
* time: 115 hours ~ 28 days ~ 6 weeks ~ 1.3 months
### elaboration order ###
1. image types
2. color conversion
3. tonemap
1. PerceptualMap
2. Foveal
3. Veil
4. ToneAdjustment
5. AcuityFilter
6. ColorAdjustment
4. formatting
### construction order ###
1. basic skeleton app
2. image types
3. color conversion
4. PerceptualMap
5. Foveal
6. Veil
7. ToneAdjustment
8. AcuityFilter
9. ColorAdjustment
10. basic in/out formatters
11. package app
12. other formatters
### version 2 prospectus ###
* accelerate
* C++ first
* CPU streaming instruction support
* assess graphics card use
* flare feature
-- the more localised eye scattering effects -- Cornell paper in Siggraph 1995
* white/color shift feature
-- simulating the human perception that white looks white even when
illumination is colored.
-- research needed
References
----------
* 'A Visibility Matching Tone Reproduction Operator for High Dynamic Range
Scenes'
Ward Larson, Rushmeier, Piatko;
IEEE TVCG 1997.
<http://radsite.lbl.gov/radiance/papers/lbnl39882/tonemap.pdf>
* 'A Model of Visual Adaptation for Realistic Image Synthesis'
Ferwerda, Pattanaik, Shirley, Greenberg;
Siggraph 1996.
<http://www.graphics.cornell.edu/pubs/1996/FPSG96.pdf>
* 'Physically-based Glare Effects for Digital Images'
Spencer, Shirley, Zimmerman, Greenberg;
Siggraph 1995.
<http://www.graphics.cornell.edu/pubs/1995/SSZG95.pdf>
* 'Illumination And Color In Computer Generated Imagery'
Hall;
Springer 1989.
0-387-96774-5.
* OpenEXR high dynamic range image format
<http://www.openexr.com/>
* PNG image format
<http://www.libpng.org/>
* sRGB color space
<http://www.w3.org/Graphics/Color/sRGB>