\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#166: Reading and Writing the Photo Image Alpha Channel}
\date{November 19, 2003}
\author{Donal K. Fellows, Simon Bachmann}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#166}&\textbf{Reading and Writing the Photo Image Alpha Channel}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\par
Simon Bachmann \tipmail{simonbachmann}{bluewin.ch}
\\
Created&Wednesday, \(\text{19}^{\text{th}}\) November 2003\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.12 $\\
Keywords&Tk, image get, image put\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP describes how to update the \textbf{image get} and \textbf{image put} subcommands so as to allow script-level access to the full alpha channel information that has been present in the photo image data model since Tk 8.3.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Alpha channels. We've had them in Tk's photo image data model (which is currently 8-bits-per-channel RGBA) for quite some time now. We can copy the alpha data around inside the image. We now display them correctly on deep-enough displays (many thanks to the people who have worked on that!) But can we write alpha data into an image? No. Not unless you have an image format handler that produces alpha data installed (e.g. the PNG from tkimg.) I think we should fix this so that people can read and write the full alpha data from scripts.

\section{Proposal}

I propose to update the \textit{photoImageInstance} \textbf{get} subcommand so that it takes an extra option \textbf{-withalpha} (to be placed after the coordinates). If that option is specified, the subcommand will return four values instead of three, with the fourth being the contents of the alpha channel for the pixel. Without this new option, the subcommand will return three values as before.

I also propose to update the \textit{photoImageInstance} \textbf{put} subcommand so that alpha channel information may be specified in the following ways when using the list-of-lists-of-pixel-data format (the image-format format will be up to the particular image format code, as always.)
\begin{itemize}
\item{}
If a pixel is specified as being the empty string, that pixel will be set to be completely transparent. This parallels the interpretation of the empty string as transparency elsewhere within the core (notably in [canvas] items.)
\item{}
Any standard Tk colour format (those accepted by \textbf{Tk\_GetColor()} --- e.g. \textit{bisque2} or \textit{\#abcdef}) may have the following suffix added --- \textbf{@A} --- where A is a fractional alpha value in the range 0.0 to 1.0 (which values correspond to fully transparent and fully opaque respectively.)
\item{}
Any standard Tk colour format which does not have a \textbf{@A} suffix may have a \textbf{\#XX} suffix, where XX is a pair of hex digits that specify an integer alpha value in the range 0 (fully transparent) to 255 (fully opaque).
\item{}
Any standard Tk colour format which does not have a \textbf{@A} suffix nor a \textbf{\#XX} suffix may have a \textbf{\#X} suffix, where X is a single hex digit that specifies an integer alpha value in the range 0 (fully transparent) to 255 (fully opaque). This is expanded in range from 4 bits wide to 8 bits wide by multiplication by 0x11.
\item{}
All pixel colours that have neither of the foregoing suffixes are to be interpreted as being fully opaque, which is the current situation anyway.
\item{}
An additional pixel format is to be supported, consisting of a Tcl list of three or four integers in the range 0 to 255, being the value of the red channel, green channel, blue channel and alpha channel respectively in that order. An absent alpha channel is to be interpreted as full opacity.
\item{}
Two additional pixel formats are to be supported, consisting of a \textbf{\#} followed by exactly four or eight hexadecimal digits. When four digits are present, they will be interpreted as containing data for the \textit{RGBA} channels (in that order), and each digit will be expanded internally to 8-bits wide by multiplication by 0x11. When eight digits are present, they will be interpreted as containing data for the \textit{RGBA} channels (in that order) with two digits for each channel.
\end{itemize}

It should also be possible to include alpha information in the data retrieved with the \textit{photoImageInstance} \textbf{data} subcommand. For this, I propose to make the list-of-lists-of-pixel-data format a regular photo image format (like PNG, GIF, PPM, etc.) with the name \textbf{default}. This format will have no file read/write capabilities. As before, the list-of-lists format will be the default choice for \textit{photoImageInstance} \textbf{data}, and the last one to be tried for \textit{photoImageInstance} \textbf{put}. The main benefit of this change is that it will be possible to request the \textbf{default} format explicitly with the \textbf{-format} option and --- most important --- to pass suboptions to the format handler. The \textbf{default} image data format shall accept the suboption \textbf{-colorformat} \textit{type} which specifies the format to be used to encode the color and alpha data for each pixel. Accepted values shall be \textbf{rgb} for the \#RRGGBB format (the current format and default for the suboption), \textbf{rgba} for the \#RRGGBBAA format, and \textbf{list} for the list format with four elements. This change will have two side effects:
\begin{itemize}
\item{}
The \textbf{-data} option to photo images will accept image data in the list-of-lists form as well. Currently only data in one of the registered file formats is accepted.
\item{}
The underlying implementation will become simpler and cleaner.
\end{itemize}

Finally, the \textit{photoImageInstance} \textbf{transparency} command's subcommands will be updated in the following way:
\begin{itemize}
\item{}
The \textbf{get} subcommand will be modified to take an extra option, \textbf{-alpha} (to be placed after the coordinates), that modifies the result to be the integral alpha value (in the range 0 to 255) for the specified pixel. Without the option, the result shall continue to be a boolean that is true exactly when the pixel is wholly transparent.
\item{}
The \textbf{set} subcommand will be modified to take an extra option, \textbf{-alpha} (to be placed after the new value), that modifies the interpretation of the new value so that it is the integral alpha value to be set for the pixel. Without the option, the value will be interpreted as a boolean as before.
\end{itemize}

\section{Examples}

Create a small image with a black border and a partially-transparent red area in the center.
\begingroup\small\begin{verbatim}
image create photo transExample
transExample put black -to 0 0 10 10
transExample put red@.5 -to 2 2 8 8
\end{verbatim}
\endgroup

Retrieve the alpha value of a pixel near the middle of the image created previously.
\begingroup\small\begin{verbatim}
set aVal [transExample transparency get 5 5 -alpha]
\end{verbatim}
\endgroup

Create a green box with a simple shadow effect
\begingroup\small\begin{verbatim}
image create photo foo
# Make a simple graduated fill varying in alpha for the shadow
for {set i 14} {$i>0} {incr i -1} {
   set i2 [expr {$i+30}]
   foo put [format black#%x [expr {15-$i}]] -to $i $i $i2 $i2
}
# Put a solid green rectangle on top
foo put #080 -to 0 0 30 30
\end{verbatim}
\endgroup

Retrieve image data with alpha information in the list-of-lists form and create a new image with it. 
\begingroup\small\begin{verbatim}
image create photo bar -file imageWithTransparency.png
set imageData [bar data -format {default -colorformat rgba}

# Inspect / modify / save data

image create photo baz -data $imageData
\end{verbatim}
\endgroup

\section{Reference Implementation}

Branch tip-166 on fossil.

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
