[sane-devel] SANE2 proposal

[Henning Meier-Geinitz]

--8t9RHnE3ZwKMSgU+
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hi,

On Sun, Apr 14, 2002 at 10:45:21PM +0200, Oliver Rauch wrote:
> Henning Meier-Geinitz wrote:
> 
> > Some questions and comments that came to my mind while reading the
> > standard the first time (so I may have missed something):
> > 
> > * 3.2 Image data format and 3.2.1 Image transmission:
> >   The radical change in frame types and frame transmission should be
> >   mentioned earlier in the text.
> 
> Suggestions are welcome.

Ok. I append a LaTeX code for a revised chapter "Image data format". I
mostly moved paragraphs around. I removed the exact descriptions for
the old frame types. Added references to sane_get_parameters. Added
definition of the order of bits in 1-bit modes.

What do you think about it?

> >   We don't know if all the information
> >   about 1, 8, 16 bits per sample are true for some MIME format, do we?
> 
> May be correct. Possibly the value depth makes no sense in MIME format.

I moved this part to SANE_FRAME_RAW.

> >   I'm not sure if we should even mention the old SANE1 frame types.
> >   If someone really wants to use them, he should looak at the SANE1
> >   standard. Or is tehre a special reason for this?
> 
> Once is to tell why values 5 and 6 are used for SANE2 frames,
> onther thing is the idea that a frontend may decide to support
> SANE1 and SANE2 backends.

That's ok. But I don't think we should describe all the old data
structures in detail in SANE 2. The frontend implementor has to read
the old standard anyway (e.g. for the changed sane_open() call).

> It also would be possible to start from 0 and remove the SANE1
> frame types. But this way it would be harder to write a
> SANE1+SANE2 frontend.
> This is one of the points that have to be discussed. May be
> it makes more sense to remove all SANE1 things.

Mention that the types were used by version 1 and add a "don't use
flag". Not more. 

> > 
> >   Add a reference to the chapter about sane_get_parameters fort the exact
> >   meaning of formatdesc.
> 
> There is a describing point formatdesc in sane_get_parameters. What
> do you think about?

That's ok. I just wanted a link to that desription (\ref{some_section}).

> > * SANE_Device.email_backend_author: I'm not sure, if this really
> >   belongs into the structure (and not into the man page and HTML page).
> >   If it's in the code, I would prefer to also have the name of the
> >   author in this entry. This makes it easier to find him when the
> >   email address doesn't exist any longer.
> 
> The email address should look like this:
> 
> Oliver Rauch <Oliver.Rauch@XSane.org>

Ok, better explicitely talk about the name.

> it makes sense to put the email address into the backend because
> if someone uses a backend via network he may not have the manpage
> of the backend.

Ok. Maybe also a URL to the backend homepage?

> > * SANE_Device.device_location: I don't understand this one. Which
> >   location? My device is on the table 1.5m to the right of me :-)
> >   Do you mean the backend? A URL to the vendor? Or a path name?
> >   And why should it be read from the config file (the backend doesn't
> >   even need one and I'm not sure if we should mention this).
> 
> No, I think about a real physical location.
> Imagine you are at work or in the university and 200 computers have
> access to a scanner via network, then it is necessary that a user
> can find out where he finds the scanner, so the entry could look like
> this:
>
> building 93, 2nd plane, room 2113

Ah, ok. Then my first guess wasn't that wrong. Maybe just add your
example to the descriptions, that makes it pretty clear.

> > * SANE_Device.backend_capability_flags: Can you give an example for
> >   such a flag and what the frontend should do with it?
> 
> This is planned for future extensions.
> Let?s say we add a new feature that is not defined in the sane-2.0.0
> standard (e.g. audio support for a camera) then it is necessary that
> the backend can tell te frontend if special features are supported or
> not.

But the features must be supported by some addition function or frame
type in this case, needn't it?

> > * 4.2.10 InternationAlization (missing "a").
> >   Be clear. "Should" is should. There is no "preferrable" necessary.
> >   Maybe we should cite the RFCs' meaning of "MUST" and "SHOULD"
> >   somewhere in the standard?
> 
> We can write "must" but I do not want to force this here, it also does
> work when the backend is written in chineese and we have a chineese
> to english translation

Ok, then just use "should". I didn't like the "preferrable".

> > As an addition, we should make clear what can be changed in a
> > SANE_Option_Descriptor and when. Currently it must only be "vaild" and
> > the address stay the same. E.g. is the backend allowed to change the
> > type of option? Or only capabilities?
> 
> I think it is allowed to change all in sane_control_option when
> SANE_INFO_RELOAD_OPTIONS is set - or am I wrong?

Be carefull. You can change the value and (at least I think so)
SANE_CAP_INACTIVE. You don't know if SANE_INFO_RELOAD_OPTIONS means
that the options are reloaded immediately. info can even be 0.
Even when sane_get_option_descriptor is actually called, it's
currently not allowed to change the returned address until sane_close().
The net backend had this bug until recently.

From the words of the current standard you are not allowed to change
Status: O

the option descriptor (at least that's my interpretation).
E.g. you can't change a constraint or string list.

Bye,
  Henning

--8t9RHnE3ZwKMSgU+
Content-Type: application/x-tex
Content-Disposition: attachment; filename="sane2-image-data-format.tex"
Content-Transfer-Encoding: quoted-printable

\section{Image Data Format}\label{sec:imageformat}\index{image data format}=
=0A=0AArguably the most important aspect of an image acquisition system is =
how=0Aimages are represented. The SANE approach is to define a simple yet p=
owerful=0Arepresentation that is sufficient for vast majority of applicatio=
ns and=0Adevices. While the representation is simple, the interface has bee=
n defined=0Acarefully to allow extending it in the future without breaking =
backwards=0Acompatibility. Thus, it will be possible to accommodate future =
applications or=0Adevices that were not anticipated at the time this standa=
rd was created.=0A=0AA SANE image is a rectangular area.  The rectangular a=
rea is subdivided into a=0Anumber of rows and columns.  At the intersection=
 of each row and column is a=0A(preferable quadratic) pixel. A pixel consis=
ts of one or more sample values.=0A\begin{changebar}=0A  Each sample value =
represents one channel (e.g., the red channel).=0A\end{changebar}=0A=0AThe =
SANE API transmits an image as a sequence of frames.  Each frame covers=0At=
he same rectangular area as the entire image, but may contain only a subset=
=0Aof the channels in the final image.  For example, a red/green/blue image=
 could=0Aeither be transmitted as a single frame that contains the sample v=
alues for=0Aall three channels or it could be transmitted as a sequence of =
three frames:=0Athe first frame containing the red channel, the second the =
green channel, and=0Athe third the blue channel.=0A=0A\begin{changebar}=0A =
 When transmitting an image frame by frame, the frontend needs to know what=
=0A  part of the image a frame represents (and how many frames it should ex=
pect).=0A  For that purpose, the SANE API tags every frame with a type and =
a format=0A  descriptor.=0A\end{changebar}=0A=0A\begin{changebar}=0A  There=
 are two different types of frames: pixel oriented frames=0A  \code{\defn{S=
ANE\_FRAME\_RAW}} and arbitrary data frames=0A  \code{\defn{SANE\_FRAME\_MI=
ME}}. These types are discussed in detail in the=0A  following sections. Th=
e frame types used by version~1 of this standard=0A  (\code{\defn{SANE\_FRA=
ME\_GRAY}}, \code{\defn{SANE\_FRAME\_RGB}},=0A  \code{\defn{SANE\_FRAME\_RE=
D}}, \code{\defn{SANE\_FRAME\_GREEN}}, and=0A  \code{\defn{SANE\_FRAME\_BLU=
E}}) are obsolete and superseded by=0A  \code{\defn{SANE\_FRAME\_RAW}}.=0A\=
end{changebar}=0A=0A\begin{changebar}=0A  \subsection{Pixel oriented frames=
}=0A\end{changebar}=0A=0A\begin{changebar}=0A  The type of pixel oriented f=
rames is \code{\defn{SANE\_FRAME\_RAW}}. The=0A  frame contains one or more=
 channels of data in a channel-interleaved format,=0A  that represents samp=
le values from a property of the individual pixels that=0A  is subject to f=
urther description in the \code{format\_desc} member of the=0A  \code{SANE\=
_Parameters} structured type. See section~\ref{sec:sanegetparams}=0A  on pa=
ge~\pageref{sec:sanegetparams} for details about the format=0A  description=
s.=0A\end{changebar}=0A=0A\begin{changebar}=0A  Each sample value has a cer=
tain bit depth.  The bit depth is fixed for the=0A  entire image and can be=
 as small as one bit. Valid bit depths are 1, 8, or=0A  16 bits per sample.=
 If a device's natural bit depth is something else, it is=0A  up to the dri=
ver to scale the sample values appropriately (e.g., a 4 bit=0A  sample coul=
d be scaled by a factor of four to represent a sample value of=0A  depth 8)=
.=0A\end{changebar}=0A=0A\begin{changebar}=0A  The complete image may consi=
st of several channels, the number of channels=0A  is defined by member \co=
de{channels\_per\_image} of \code{SANE\_Parameters}.=0A  The image may be t=
ransmitted in an arbitary number of frames which can be=0A  determined by w=
atching the \code{last\_frame} flag in said type (or by=0A  counting the ch=
annels).  Note: This frame type replaces all frame types of=0A  the SANE st=
andard version 1.=0A\end{changebar}=0A=0AConceptually, each pixel oriented =
frame is transmitted=0Aa byte at a time.  Each byte may contain 8 sample va=
lues (for an image=0Abit depth of 1), one full sample value (for an image b=
it depth of 8),=0Aor a partial sample value (for an image bit depth of 16 o=
r bigger).=0AIn the latter case, the bytes of each sample value are transmi=
tted in=0Athe machine's native byte order.=0A\begin{quote}=0A  \begin{cente=
r}=0A    {\bf Backend Implementation Note}=0A  \end{center}=0A  A network-b=
ased meta backend will have to ensure that the byte order=0A  in image data=
 is adjusted appropriately if necessary.  For example,=0A  when the meta ba=
ckend attaches to the server proxy, the proxy may=0A  inform the backend of=
 the server's byte order.  The backend can then=0A  apply the adjustment if=
 necessary.  In essence, this implements a=0A  ``receiver-makes-right'' app=
roach.=0A\end{quote}=0A=0A\begin{figure}[htbp]=0A  \begin{center}=0A    \le=
avevmode=0A    \psfig{file=3Dfigs/xfer.eps,width=3D0.5\textwidth}=0A    \ca=
ption{Transfer order of image data bytes}=0A    \label{fig:xfer}=0A  \end{c=
enter}=0A\end{figure}=0A=0AThe order in which the sample values in a frame =
are transmitted is illustrated=0Ain Figure~\ref{fig:xfer}.  As can be seen,=
 the values are transmitted row by=0Arow and each row is transmitted from l=
eft-most to right-most column.  The=0Aleft-to-right, top-to-bottom transmis=
sion order applies when the image is=0Aviewed in its normal orientation (as=
 it would be displayed on a screen, for=0Aexample).=0A=0AIf a frame contain=
s multiple channels, then the channels are transmitted in an=0Ainterleaved =
fashion.  Figure~\ref{fig:pixels} illustrates this for the case=0Awhere a f=
rame contains a complete red/green/blue image with a bit-depth of 8.=0A=0A\=
begin{figure}[htbp]=0A  \begin{center}=0A    \leavevmode=0A    \psfig{file=
=3Dfigs/image-data.eps,width=3D0.8\textwidth}=0A    \caption{Bit and byte o=
rder of image data}=0A    \label{fig:pixels}=0A  \end{center}=0A\end{figure=
}=0A=0AFor a bit depth of 1, each byte contains 8 sample values of a {\em s=
ingle\/}=0Achannel. In other words, a bit depth 1 frame is transmitted in a=
 byte=0Ainterleaved fashion. =0A\begin{changebar}=0A  The first sample of e=
ach byte is represented by the most significant bit.=0A\end{changebar}=0A=
=0AWhen the bit depth is 1 there are only two sample values possible, 1=0Ar=
epresents minimum intensity (black) and 0 represents maximum intensity=0A(w=
hite). For all other bit depths a sample value of 0 represents minimum=0Ain=
tensity and larger values represent increasing intensity.=0A=0A\begin{chang=
ebar}=0A  \subsection{Arbitrary data frames}=0A\end{changebar}=0A=0A\begin{=
changebar}=0A  It also is possible to transmit arbitary (not necessaryly pi=
xel oriented)=0A  data. This allows transmission of compressed images like =
jpeg, tiff, etc.=0A\end{changebar}=0A=0A\begin{changebar}=0AThe type of arb=
itrary data frames is \code{\defn{SANE\_FRAME\_MIME}}.=0A\end{changebar}=0A=
The frame contains arbitrary data of the MIME (see RFC 1521/1522) type that=
 is=0Agiven in the \code{format\_desc} member of the \code{SANE\_Parameters=
}=0Astructured type (see See section~\ref{sec:sanegetparams} on=0Apage~\pag=
eref{sec:sanegetparams}).  As such, it is assumed to be=0Aincomprehensible =
to the frontend, except for selected types the frontend is=0Aspecifically c=
apable of handling internally.  The frontend is free to ignore=0Athose fram=
es, or employ any appropriate means to otherwise handle this data=0A(like s=
aving them to disk or spawning an external viewer).=0A=0A\chapter{The SANE =
Application Programmer Interface (API)}\label{chap:api}=0A
--8t9RHnE3ZwKMSgU+--