diff --git a/conf.py b/conf.py index fc32200..bda1251 100644 --- a/conf.py +++ b/conf.py @@ -46,6 +46,12 @@ templates_path = ['_templates'] primary_domain = 'c' +numfig = True +numfig_format = { + 'figure': 'Figure %s', + 'table': 'Table %s' +} + today_fmt = '%Y-%m-%d' highlight_language = 'c' diff --git a/figs/area.pdf b/figs/area.pdf new file mode 100644 index 0000000..9e5931a Binary files /dev/null and b/figs/area.pdf differ diff --git a/figs/area.svg b/figs/area.svg new file mode 100644 index 0000000..1944f71 --- /dev/null +++ b/figs/area.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +scan area + +bottom-right + +top-left + +scan surface + +y + +x + +0 + + + + + + + + + + + + diff --git a/figs/flow.pdf b/figs/flow.pdf new file mode 100644 index 0000000..b160ca5 Binary files /dev/null and b/figs/flow.pdf differ diff --git a/figs/flow.svg b/figs/flow.svg new file mode 100644 index 0000000..5cf5011 --- /dev/null +++ b/figs/flow.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + + + + +image acquisition + +device setup + +- go back to + +sane_start() + +if more frames desired + +- use: + +- sane_start() + +repeatedly to configure device as desired + +sane_control_option() + +sane_get_option_descriptor() + +- use: + +repeatedly until read returns EOF + +sane_get_parameters() + +sane_read() + +- sane_cancel() + +- sane_init() + +- sane_exit() + +- pick desired device, possibly by using + +- sane_open() + +- sane_close() + +sane_get_devices() + + diff --git a/figs/hierarchy.pdf b/figs/hierarchy.pdf new file mode 100644 index 0000000..9f1e867 Binary files /dev/null and b/figs/hierarchy.pdf differ diff --git a/figs/hierarchy.svg b/figs/hierarchy.svg new file mode 100644 index 0000000..a3a7781 --- /dev/null +++ b/figs/hierarchy.svg @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +qcam + +hp + +pnm + +mustek + +pnm files + +scanner + +scanner 1 + +scanner 2 + +video camera + +machine A + +machine B + +network connection + +dll + +net + +saned + +dll + +autolum + + diff --git a/figs/image-data.pdf b/figs/image-data.pdf new file mode 100644 index 0000000..f488d49 Binary files /dev/null and b/figs/image-data.pdf differ diff --git a/figs/image-data.svg b/figs/image-data.svg new file mode 100644 index 0000000..579e1f5 --- /dev/null +++ b/figs/image-data.svg @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +7 6 5 4 3 2 1 0 + +7 6 5 4 3 2 1 0 + +7 6 5 4 3 2 1 0 + +r + +g + +b + +pixel 0 + +7 6 5 4 3 2 1 0 + +7 6 5 4 3 2 1 0 + +7 6 5 4 3 2 1 0 + +r + +g + +b + +pixel 1 + +byte 5 + +byte 4 + +byte 3 + +byte 2 + +byte1 + +byte0 + +.... + +bit: + + diff --git a/figs/xfer.pdf b/figs/xfer.pdf new file mode 100644 index 0000000..06279e7 --- /dev/null +++ b/figs/xfer.pdf @@ -0,0 +1,83 @@ +%PDF-1.7 +%쏢 +5 0 obj +<> +stream +xMN0 9E,B8?>k`0  Xp}&i3IU>wm hz<뻨_>ջ.ՐI9 >no` W8 !L#q]A=\7Koǒ V/ĉݞ\4|9G 8NR4ItM6{U!',j.I,{d.Y4RBX2^.nY:fU G9 UĦ +X|Q6 +J=:2%1[9";Pq9g_ `0Aw m N:TaMu:ucrXfkvqW~ @a3a8zW91T7P` 9G# H0=f$P;((Ijeݢ{Zwr; 5l"UOq:3'*.%k%ﯓV;lW܂endstream +endobj +6 0 obj +469 +endobj +4 0 obj +<> +/Contents 5 0 R +>> +endobj +3 0 obj +<< /Type /Pages /Kids [ +4 0 R +] /Count 1 +>> +endobj +1 0 obj +<> +endobj +7 0 obj +<>endobj +8 0 obj +<> +endobj +9 0 obj +<>stream + + + + + +2019-11-18T13:15:15Z +2019-11-18T13:15:15Z +fig2dev Version 3.2.6a + +figs/xfer.fig + + + + + +endstream +endobj +2 0 obj +<>endobj +xref +0 10 +0000000000 65535 f +0000000763 00000 n +0000002316 00000 n +0000000704 00000 n +0000000573 00000 n +0000000015 00000 n +0000000554 00000 n +0000000827 00000 n +0000000868 00000 n +0000000897 00000 n +trailer +<< /Size 10 /Root 1 0 R /Info 2 0 R +/ID [] +>> +startxref +2494 +%%EOF diff --git a/figs/xfer.svg b/figs/xfer.svg new file mode 100644 index 0000000..630dc62 --- /dev/null +++ b/figs/xfer.svg @@ -0,0 +1,98 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/sane.rst b/sane.rst index 1190090..8bf258c 100644 --- a/sane.rst +++ b/sane.rst @@ -161,13 +161,17 @@ platform dependent. Several possibilities exist: universe, as long as there is a network connection to that host and provided the user is permitted to access that scanner. -:raw-latex:`\leavevmode` -:raw-latex:`\psfig{file=figs/hierarchy.eps,angle=270,width=\textwidth}` +.. figure:: figs/hierarchy.* + :name: fig:hierarchy + :scale: 100% + :align: center + + Example SANE Hiearchy The above discussion lists just a few ways for frontends to attach to a backend. It is of course possible to combine these solutions to provide an entire hierarchy of SANE backends. Such a hierarchy is depicted in -Figure :raw-latex:`\ref{fig:hierarchy}`. The figure shows that machine A +:numref:`fig:hierarchy`. The figure shows that machine A uses a dynamic-linking based meta backend called ``dll`` to access the backends called ``pnm``, ``mustek``, and ``net``. The first two @@ -240,25 +244,33 @@ sample value are transmitted in the machine’s native byte order. apply the adjustment if necessary. In essence, this implements a “receiver-makes-right” approach. -:raw-latex:`\leavevmode` -:raw-latex:`\psfig{file=figs/xfer.eps,width=0.5\textwidth}` +.. figure:: figs/xfer.* + :name: fig:xfer + :scale: 50% + :align: center + + Transfer order of image data bytes The order in which the sample values in a frame are transmitted is -illustrated in Figure :raw-latex:`\ref{fig:xfer}`. As can be seen, the +illustrated in :numref:`fig:xfer`. As can be seen, the values are transmitted row by row and each row is transmitted from left-most to right-most column. The left-to-right, top-to-bottom transmission order applies when the image is viewed in its normal orientation (as it would be displayed on a screen, for example). If a frame contains multiple channels, then the channels are transmitted -in an interleaved fashion. Figure :raw-latex:`\ref{fig:pixels}` +in an interleaved fashion. :numref:`fig:pixels` illustrates this for the case where a frame contains a complete red/green/blue image with a bit-depth of 8. For a bit depth of 1, each byte contains 8 sample values of a *single* channel. In other words, a bit depth 1 frame is transmitted in a byte interleaved fashion. -:raw-latex:`\leavevmode` -:raw-latex:`\psfig{file=figs/image-data.eps,width=0.8\textwidth}` +.. figure:: figs/image-data.* + :name: fig:pixels + :scale: 80% + :align: center + + Bit and byte order or image data When transmitting an image frame by frame, the frontend needs to know what part of the image a frame represents (and how many frames it should @@ -585,8 +597,8 @@ Most SANE operations return a value of type completion status of the operation. If an operation completes successfully, :macro:`SANE_STATUS_GOOD` is returned. In case of an error, a value is returned that indicates the nature of the problem. The complete -list of available status codes is listed in Table -:ref:`tab:status`. It is recommended to use function +list of available status codes is listed in +:numref:`tab:status`. It is recommended to use function :func:`sane_strstatus()` to convert status codes into a legible string. @@ -781,7 +793,7 @@ Option Value Type Member :member:`type` specifies the type of the option value. The possible values for type :type:`SANE_Value_Type` -are described in Table :ref:`tab:valuetype`. +are described in :numref:`tab:valuetype`. .. table:: Option Value Types (:type:`SANE_Value_Type`) :name: tab:valuetype @@ -819,8 +831,8 @@ Option Value Unit Member :member:`unit` specifies what the physical unit of the option value is. The possible values for type -:type:`SANE_Unit` are described in Table -:ref:`tab:units`. Note that the specified unit is what the +:type:`SANE_Unit` are described in +:numref:`tab:units`. Note that the specified unit is what the SANE backend expects. It is entirely up to a frontend as to how these units a presented to the user. For example, SANE expresses all lengths in millimeters. A frontend is generally expected to provide appropriate @@ -879,7 +891,7 @@ Option Capabilities Member :member:`cap` describes what capabilities the option posseses. This is a bitset that is formed as the inclusive logical OR of -the capabilities described in Table :ref:`tab:capabilities`. +the capabilities described in :numref:`tab:capabilities`. The SANE API provides the following to macros to test certain features of a given capability bitset: @@ -959,7 +971,7 @@ values that are allowed for the option are described by one of the union members of member :member:`constraint`. The possible values of type :type:`SANE_Constraint_Type` and the interpretation of the :member:`constraint` union is described -in Table :ref:`tab:constraints`. +in :numref:`tab:constraints`. .. table:: Option Value Constraints :name: tab:constraints @@ -1234,7 +1246,7 @@ of this argument is described in more detail below. The way the option is affected by a call to this function is controlled by parameter :data:`a` which is a value of type :type:`SANE_Action`. The possible values and their -meaning is described in Table :ref:`tab:actions`. +meaning is described in :numref:`tab:actions`. .. table:: Action Values (:type:`SANE_Action`) :name: tab:actions @@ -1261,7 +1273,7 @@ additional information on how well the request has been met is returned in :data:`*i` (if :data:`i` is non-:macro:`NULL`). The returned value is a bitset that may contain any combination of the values described in -Table :ref:`tab:info`. +:numref:`tab:info`. .. table:: Additional Information Returned When Setting an Option :name: tab:info @@ -1363,7 +1375,7 @@ structure is given below. Member :member:`format` specifies the format of the next frame to be returned. The possible values for type :type:`SANE_Frame` are described in -Table :ref:`tab:frameformat`. The meaning of these values is +:numref:`tab:frameformat`. The meaning of these values is described in more detail in Section :raw-latex:`\ref{sec:imageformat}`. .. table:: Frame Format (:type:`SANE_Frame`) @@ -1654,13 +1666,17 @@ Code Flow --------- The code flow for the SANE API is illustrated in -Figure :raw-latex:`\ref{fig:flow}`. Functions +:numref:`fig:flow`. Functions :func:`sane_init()` and :func:`sane_exit()` initialize and exit the backend, respectively. All other calls must be performed after initialization and before exiting the backend. -:raw-latex:`\leavevmode` -:raw-latex:`\psfig{file=figs/flow.eps,height=0.5\textheight}` +.. figure:: figs/flow.* + :name: fig:flow + :scale: 50% + :align: center + + Code flow Function :func:`sane_get_devices()` can be called any time after :func:`sane_init()` has been called. It returns the @@ -1805,7 +1821,7 @@ Scan Area Options The four most important well-known options are the ones that define the scan area. The scan area is defined by two points (x/y coordinate pairs) that specify the top-left and the bottom-right corners. This is -illustrated in Figure :raw-latex:`\ref{fig:area}`. Note that the origin +illustrated in :numref:`fig:area`. Note that the origin of the coordinate system is at the top-left corner of the scan surface as seen by the sensor (which typically is a mirror image of the scan surface seen by the user). For this reason, the top-left corner is the @@ -1815,8 +1831,12 @@ abscissa and ordinate values are simulatenously the *largest*. If this coordinate system is not natural for a given device, it is the job of the backend to perform the necessary conversions. -:raw-latex:`\leavevmode` -:raw-latex:`\psfig{file=figs/area.eps,height=0.3\textheight}` +.. figure:: figs/area.* + :name: fig:area + :scale: 90% + :align: center + + Scan area options The names of the four options that define the scan area are given in the table below: