REFERENCE MANUAL

PXIPLtm
Image Processing 'C' Library



For use with:
XCLIB V3.8



Copyright © 2023 EPIX, Inc.
No part of this document may be reproduced, transmitted, photocopied, or translated into another language without the written consent of EPIX, Inc. Information in this document is subject to change without obligation or notice. EPIX, Inc. makes no warranty of any kind with regard to this document, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. EPIX, Inc. assumes no responsibility for any errors that may appear in this document. EPIX, Inc. reserves the right to make changes to the specifications of hardware and software at any time, without obligation or notice.

4MIP, SVIP, XCIP, XCAP, 4MEG VIDEO, 1MEG VIDEO, SILICON VIDEO MUX, QUICK SET VIDEO, 12-7MUX, IMAGE MEMORY EXPANSION, COC40, and COC402 are trademarks of EPIX, Inc.

EPIX, SILICON VIDEO, and PIXCI are registered trademarks of EPIX, Inc.

Other brand, product, and company names are trademarks or registered trademarks of their respective owners.

Printing: 28-Apr-2023

EPIX, Inc.
381 Lexington Drive
Buffalo Grove IL 60089
847.465.1818
847.465.1919 (fax)
epix@epixinc.com
www.epixinc.com

Table of Contents

 

 

 

1. Getting Started

This manual describes the library of image processing functions for use with EPIX® frame grabbers. The library functions are designed for use with the SVOBJ, the library for the SILICON VIDEO® and SILICON VIDEO® MUX frame grabbers; for use with 4MOBJ, the library for the 4MEG VIDEO frame grabbers; for use with XCOBJ, the older library for the PIXCI® frame grabbers; and for use with XCLIB the new library for the PIXCI® frame grabbers. The image processing library provides a wide variety of functions for image enhancement, filtering, analysis, measurement, and file load and save.

For ease of use, the image processing functions share common image specifications, known as pximage and pximage3; the former describes a single image buffer, the latter describes a sequence of image buffers. These image specifications allows the same image processing functions to operate on a full image or on a rectangular area of interest, on images in malloc'ed memory or in image frame buffer memory (which may be on the frame grabber, or in host memory, depending on the particular frame grabber) upon the current image buffer being displayed or digitized[1] or any other image buffer, upon any one of several frame grabbers, or upon images stored on disk.

Regardless of the image's location, the image processing library must be used in conjunction with 4MOBJ, SVOBJ, XCOBJ, or XCLIB and requires the presence of a supported frame grabber.

A word about conventions used in this manual. Highlighted phrases such as Getting Started are a reference to a section of this manual. Highlighted phrases such as FUNDAMENTALS OF DIGITAL IMAGE PROCESSING are a reference to this manual or another publication. Highlighted phrases such as file.xyz are a reference to a file. Highlighted phrases such as threshold typically refer to a function's parameters. Older HTML browsers may not show these variations in a distinguished manner.

 

1.1. Installation

The PXIPL library distribution is combined with the 4MOBJ, SVOBJ, XCOBJ, or XCLIB distribution and is installed at the same time as those libraries.

Any files named readme.txt, readme1.txt, etc. contain distribution listings, corrections or additions to this manual, or other up-to-date information. All such files should be read in conjunction with this manual.

 

1.2. Organization

This manual groups the library functions according to effect. The Index provides an alphabetically sorted listing of function names.

The Support Functions chapter introduces the basic support functions required for use of the image processing library. Most important are the functions which construct pximage or pximage3 specifications.

For the SVOBJ, 4MOBJ, or XCOBJ libraries, any of pxd_defimage, pxd_defimagecolor, pxvid_setpximage, or pxvid_setpximage2 can be used to create a pximage specification describing an image frame buffer. Any of pxd_defimage3 pxd_defimage3color, or pxvid_setpximage3 can be used to create a pximage3 specification describing a sequence of image frame buffers. The programmer may prefer pxd_defimage, pxd_defimagecolor, pxd_defimage3, or pxd_defimage3color to avoid the explicit use of pointers and structures, or prefer pxvid_setpximage, pxvid_setpximage2, or pxvid_setpximage3 to obtain the flexibility that explicit use of structures and pointers provide. Examples following these functions descriptions' show their use with a typical image processing function; the same method of use applies to all library functions.

For the XCLIB library, the pxd_defineImage, ::initPximage, or ::initFilteredPximage, can be used to create a pximage specification describing an image frame buffer. The pxd_defineImage3, ::initPximage3, or ::initFilteredPximage3 can be used to create a pximage3 specification describing a sequence of image frame buffers. The pxd_defineImage and pxd_defineImage3 are used in conjunction with the XCLIB's SCF style functions, the ::initPximage, ::initFilteredPximage, ::initPximage3, ::initFilteredPximage3, are used if the non-SCF functions are chosen. Note that the XCLIB provides macros which provide compatible use of the XCOBJ's pxd_defimage, pxd_defimagecolor, pxd_defimage3, pxd_defimage3color functions;[2] for brevity examples will often simply use one of these ''functions'' with the result compatible with both old and new libraries.

The pximage_memory or pximage_memmalloc can be used to create a pximage specification describing an image buffer in host memory.

The Support Functions chapter also describes functions to interpret error codes and control premature termination of library functions.

The functions in the following chapters are independent of one another, and may be read or skipped as the application requires.

 

1.3. Compiling

The library is compatible with the following compilers, versions, memory models, and environments:

Compiled Execution Run Time
Compiler Model Library Name w. Options Environment Modules
Microsoft C/C++ V8.00 M PXIPM8DM.LIB -AM -Ox -Zl DOS V3.0+
(Visual C/C++ V1/V2)
Microsoft C/C++ V8.00 L PXIPM8DL.LIB -AL -Ox -Zl DOS V3.0+
(Visual C/C++ V1/V2)
Microsoft C/C++ V7.00 M PXIPM7DM.LIB -AM -Ox -Zl DOS V3.0+
Microsoft C/C++ V7.00 L PXIPM7DL.LIB -AL -Ox -Zl DOS V3.0+
Borland C/C++ V4.0 m PXIPB4DM.LIB -mm -O -X DOS V3.0+
Borland C/C++ V4.0 l PXIPB4DL.LIB -ml -O -X DOS V3.0+
Borland C/C++ V5.0 m PXIPB5DM.LIB -mm -O -X DOS V3.0+
Borland C/C++ V5.0 l PXIPB5DL.LIB -ml -O -X DOS V3.0+
f, 32 bit PXIPW0DF.LIB -4r -mf -w3 -ox DOS4GW
Watcom C/C++ V11.0 f PXIPW1DF.LIB -4r -mf -w3 -ox DOS4GW
32 bit
Any 16 bit Microsoft PXSV75W3.LIB -ALw -Ox -Zlp -G2sw Windows 3.x PXSV75W3.DLL
Compatible Compiler SV750W3X.DLL SV750W3X.DLL
The *.h's assume L Model
Any 16 bit Microsoft PX4M35W3.LIB -ALw -Ox -Zlp -G2sw Windows 3.x PX4M35W3.DLL
Compatible Compiler 4M350W3X.DLL 4M350W3X.DLL
The *.h's assume L Model
Any 32 bit Microsoft PX4M35W5.LIB -GB -LD Windows 95/98 PX4M35W5.DLL
Compatible Compiler 4M350W95.DLL 4M350W95.DLL
Any 32 bit Microsoft PXSV75W5.LIB -GB -LD Windows 95/98 PXSV75W5.DLL
Compatible Compiler SV750W95.DLL SV750W95.DLL
Any 32 bit Microsoft PXXC15W5.LIB -GB -LD Windows 95/98 PXXC15W5.DLL
Compatible Compiler XC150W95.DLL XC150W95.DLL
Any 32 bit Microsoft PXIPLW95.LIB -GB -LD Windows 95/98/ME PXIPLW95.DLL
Compatible Compiler XCLIBW95.DLL XCLIBW95.DLL
Any 32 bit Microsoft PX4M35WT.LIB -GB -LD Windows NT PX4M35W5.DLL
Compatible Compiler 4M350WNT.DLL 4M350WNT.DLL
Any 32 bit Microsoft PXXC15WT.LIB -GB -LD Windows NT PXXC15W5.DLL
Compatible Compiler XC150WNT.DLL XC150WNT.DLL
Any 32 bit Microsoft PXIPLWNT.LIB -GB -LD Windows NT/2000/XP/Vista/7/8/10/11 32-Bit PXIPLWNT.DLL
Compatible Compiler XCLIBWNT.DLL XCLIBWNT.DLL
Any 32 bit Microsoft PXIPLWNT.LIB -GB -LD Windows XP/Vista/7/8/10/11 64-Bit PXIPLWNT.DLL
Compatible Compiler XCLIBWNT.DLL XCLIBWNT.DLL
Any 64 bit Microsoft PXIPLW64.LIB -GB -LD Windows XP/Vista/7/8/10/11 64-Bit PXIPLW64.DLL
Compatible Compiler XCLIBW64.DLL XCLIBW64.DLL
GNU V3 or V4 pxipl_i386.a Linux 2.4 kernels
32 Bit
GNU V3 or V4 pxipl_i386_pic.a -fPIC Linux 2.4 kernels
32 Bit
GNU V3 or V4 pxipl_i386.a Linux 2.6 kernels
32 Bit
GNU V3 or V4 pxipl_i386_pic.a -fPIC Linux 2.6 kernels
32 Bit
GNU V3 or V4 pxipl_x86_64.a Linux 2.6 kernels
64 Bit
GNU V3 or V4 pxipl_x86_64_pic.a -fPIC Linux 2.6 kernels
64 Bit
TI TMS320C40 C V4.8 small PXIPC4S1.LIB -v40 -mf -x1 TMS320C40 4MOBJ
stack thru -o3 -ou w. COC40x
PXIPC4S4.LIB
The Compiled w. Options column shows the significant options used for creation of each library. The exact options shown are neither necessary nor necessarily desirable when compiling an application program.

1.3.1. Stack

When run on the 80x86 in 16 bit environments, use of the image processing function library requires 2048 bytes plus 4 times the memory space required for an image's line or column of available stack space is required. When run on the 80x86 in 32 bit environments, 4096 bytes plus 4 times the memory space required for an image's line or column of available stack space is required. These requirements are in addition to the stack space required by the frame grabber library (4MOBJ, SVOBJ, XCOBJ, or XCLIB).

When run on the TMS320C40, use of the image processing function library requires 512 words of available stack space.

The application program may require significant amounts of additional stack space. Under some operating systems, additional stack space may have to be declared during compilation or linkage to accommodate the total requirement; examples are shown below.


Note. For efficiency, the image processing library is compiled without explicit stack checks (probes). Invoking a library function with insufficient available stack space will produce strange and catastrophic results. Under Microsoft C/C++ or Watcom C/C++ such errors can be detected by using the stackavail function, such as: 

if (stackavail() < 2048+512) {
    printf("Out of Stack\n");
    pxd_close();
    exit();
}
 ...  do image processing operation ...
which explicitly tests the available stack space. Alternately, the pxd_chkstack function, provided with 4MOBJ, SVOBJ, and XCOBJ, can be used to check stack size and report any error.

1.3.2. Heap

The image processing functions malloc various amounts of storage; a common size is the horizontal dimension of the image area of interest multiplied by a small integer. This storage is free'ed before return to the application program; a few exceptions retain malloc'ed or _fmalloc'ed (in 16 bit environments) memory and are explicitly noted in the function's description.[3]

For Borland ``C'' users: In this manual, the names _fmalloc and _ffree are used instead of farmalloc and farfree, respectively. The _fmalloc and _ffree are valid alternate names under Borland ``C'' if malloc.h is included.

1.3.3. Example: Microsoft C/C++

For example, when compiling with the 4MOBJ and a 4MEG VIDEO in Microsoft ''M'' model for the DOS environment: 

cl -AM application.c  -F 1000 -link /NOE M4OBM8DM PXIPM8DM /SE:700
Or, when compiling with the SVOBJ and a SILICON VIDEO® MUX in Microsoft ''M'' model for the DOS environment: 
cl -AM application.c  -F 1000 -link /NOE SVOBM8DL PXIPM8DL /SE:700
The number following ''-F'' is the requested, application dependent, stack size in hexadecimal.

1.3.4. Example: Borland C/C++

For example, when compiling with the 4MOBJ and a 4MEG VIDEO in Borland ''M'' model for the DOS environment: 

bcc -mm application.c M4OBB5DM.LIB PXIPB5DM.LIB
Or, when compiling with the SVOBJ and a SILICON VIDEO® MUX in Borland ''L'' model for the DOS environment: 
bcc -mm application.c SVOBB5DL.LIB PXIPB5DL.LIB
Stack space should be requested by including within the program: 
extern unsigned _stklen = 0x1000;
where the initialized value of _stklen is the requested, application dependent, stack size in hexadecimal.

1.3.5. Example: Watcom 32 Bit C/C++

For example, when compiling with the 4MOBJ and a 4MEG VIDEO in Watcom V10.0 ''f'' model for the DOS environment: 

wcl386 -mf application.c -k8k M4OBW0DF.LIB PXIPW0DF.LIB
Or, when compiling with the SVOBJ and a SILICON VIDEO® MUX in Watcom V10.0 ''f'' model for the DOS environment: 
wcl386 -mf application.c -k8k SVOBW0DF.LIB PXIPW0DF.LIB
The number following ''-k'' is the requested, application dependent, stack size in 1024 (1 k) units.

1.3.6. Example: TI TMS320C40 C

For example, when compiling native code for the TMS320C40 and a 4MEG VIDEO with COC40 using the Texas Instruments TMS320C40 ``C'' compiler: 

echo -l pxipc4s1.lib  >  t.cmd
echo -l pxipc4s2.lib  >> t.cmd
echo -l pxipc4s3.lib  >> t.cmd
echo -l pxipc4s4.lib  >> t.cmd
echo -l c4obc4s1.lib  >> t.cmd
echo -l c4obc4s2.lib  >> t.cmd
echo -l c4obc4s3.lib  >> t.cmd
echo -l c4obc4s4.lib  >> t.cmd
echo -l c4obc4s5.lib  >> t.cmd
echo -heap 8192       >> t.cmd
echo -stack 1024      >> t.cmd
echo -l rts40.lib     >> t.cmd
cl30 -v40 -mf application.c -z -ar application.obj -l t.cmd
The number following ''-heap'' and the number following ''-stack'' is the requested, application dependent, heap size and stack size, respectively.

 

1.4. Inclusions

The file pxipl.h directly or indirectly contains prototype function declarations, definitions of constants and declaration of structures. Proper use of library functions requires inclusion of pxipl.h by using the statements: 

#include "pxipl.h"
at the start of each source file. Any inclusions specified for an individual function are in addition to, and should follow, the above includes.

If using the library within a C++ program, then: 

extern "C" {
#include "pxipl.h"
}
should be used, forcing interpretation of the included functions as using ''C'' calling conventions.[3]

Several examples shown in this manual utilize the ``C'' construct ''NULL'' to represent ''(void *) 0''. Application programs which use NULL must include the appropriate ''C'' include file, such as stdio.h or stdlib.h.

 

1.5. Common Types and Structures

Library functions use the following type and structure definitions to simplify programming and/or documentation. These common type definitions are shown here, rather than being repeatedly discussed with each function. The various types and structures discussed below are automatically provided via inclusion of pxipl.h; the programmer need not ''define'' or ''typedef'' these symbols.

Types defined by ``C'': 





Symbol      


 ``C'' Definition       


 Use








size_t      


 typically unsigned int 


 size of memory objects






            


 or unsigned long       


 (i.e. malloc())








off_t       


 typically long         


 size of files






            


                        


 (i.e. lseek())

Extended data types: 





Symbol      


 ``C'' Definition   


 Use








uchar        


 unsigned char      


 general






ushort       


 unsigned short     


 general






uint         


 unsigned int       


 general






ulong        


 unsigned long      


 general






uint8        


 compiler dependent 


 general






uint16       


 compiler dependent 


 general






uint32       


 compiler dependent 


 general






schar        


 signed char        


 general






sshort       


 signed short       


 general






sint         


 signed int         


 general






slong        


 signed long        


 general






pxcoord_t  


 int                


 x, y image coordinates






pximcnt_t  


 unsigned int       


 image data transfer size






pxim1size_t


 unsigned int       


 image line size






pxim2size_t


 unsigned long      


 image size






pxim3size_t


 uint32 (32 bit library) 


 image sequence size






pxim3size_t


 uint64 (64 bit library) 


 image sequence size

Library function calling convention modifiers: 





Symbol     


 Typical Definition








_cfunfcc 


 _fastcall or _pascal






_cfunvcc 


 _cdecl or blank






_cfunacc 


 _cdecl or blank
These modifiers vary in different environments, accommodating different conventions under DOS, Windows, and various compilers. Function prototypes apply modifiers automatically, thus the programmer need not normally be aware of their existence, nor are the modifiers normally shown in documentation. The exception to the programmer's need of awareness, and in the documentation, are functions that are ''called back'' from library functions.

Other types: 





Symbol          


 ``C'' Definition    


 Use








pxabortfunc_t 


 see manual page for pxabortfunc_t 


 premature termination callback function

1.5.1. Coordinates, Images, and Image Window Structures

Many functions use the following structures to simplify passing of collections of parameters.

The pxy struct provides a pair of x, y coordinates defining a point in two dimensions: 

struct pxy {
    pxcoord_t   x;
    pxcoord_t   y;
};
typedef struct pxy pxy_s;
typedef struct pxy pxypoint_s;
The pxyz struct provides a triplet of x, y, z coordinates defining a point in three dimensions: 
struct pxyz {
    pxcoord_t   x;
    pxcoord_t   y;
    pxcoord_t   z;
};
typedef struct pxyz pxyz_s;
typedef struct pxyz pxyzpoint_s;

The pxywindow struct provides a pair of x, y coordinates defining a rectangle in two dimensions: 

struct  pxywindow {
    struct  pxy nw;   // north west corner inclusive
    struct  pxy se;   // south east corner, usually exclusive
};
typedef struct pxywindow pxywindow_s;
The pxyzwindow struct provides a pair of x, y, z coordinates defining a rectangle in three dimensions: 
struct pxyzwindow {
    struct  pxyz nw;  // north west corner inclusive
    struct  pxyz se;  // south east corner, usually exclusive
};
typedef struct pxywindow pxyzwindow_s;

The pximage struct is used as an object[4] defining: (a) An image, (b) The dimensions of the image, (c) A rectangular area of interest, (d) The means of accessing the image, (e) Other parameters for internal use. The pximage must be initialized[5] using a provided function, such as pxd_defimage, pxd_defineImage, pxvid_setpximage, and others described in Support Functions.

The following abstract of the pximage shows the fields of interest to the application programmer. 

struct pximage {
    struct  pxywindow imdim; // nw.x = nw.y = 0. se.x & se.y is dimension of image
    struct  pxywindow wind;  // subwindow within imdim
        ...         ...
};
typedef struct pximage pximage_s;
The pximage.imdim provides the image's dimensions. The pximage.wind defines an area of interest within the image; the pximage.wind may be directly altered by the application programmer.

Similarly, the pximage3 defines a sequence of images (or depending on point of view, a three-dimensional image), and means of access. The following abstract of the pximage3 shows the fields of interest to the application programmer. 

struct pximage3 {
    struct  pxyzwindow imdim; // nw.x = nw.y = nw.z = 0. se.x, se.y & se.z is dimension of image
    struct  pxyzwindow wind;  // subwindow within imdim
        ...         ...
};
typedef struct pximage3 pximage3_s;

The pxyf and pxyd structs provides a pair of noninteger coordinates defining a point in two dimensions: 

struct pxyd {
    double  xd;     // i.e. x
    double  yd;     // i.e. y
};
typedef struct pxyd pxyd_s;
typedef struct pxyd pxydpoint_s;
struct pxyf {
    float  xd;     // i.e. x
    float  yd;     // i.e. y
};
typedef struct pxyf pxyf_s;
typedef struct pxyf pxyfpoint_s;
for use with routines that support spatial calibration and thus require floating point coordinates.

The pxydwindow struct provides a pair of noninteger coordinates defining a rectangle in two dimensions: 

struct pxydwindow {
    struct  pxyd nw;    // north west corner inclusive
    struct  pxyd se;    // south east corner, usually exclusive
};
typedef struct pxydwindow pxydwindow_s;

1.5.2. Image Region Structures

The pximregion struct is used to define an image region which, unlike the pximage struct, need not be rectangular and parallel to the image axis. The pximregion struct is used to encode a variety of image region types; interpretation of the fields varies from type to type. All types are based upon a pximage structure to define an image, and then additionally define a region within that image.

The pximregion is fully described in Nonrectangular Regions - Support Functions.

 

1.6. Running

1.6.1. Error Codes

Library functions return a common set of return codes, indicating success or failure. These codes are defined via inclusion of pxipl.h with mnemonic names beginning with ''PXER''. All error return codes are negative values. Specific error conditions can be differentiated by reading the definitions in pxerrno.h, or by use of the pxerrnomesg function.

1.6.2. Multiple Frame Grabbers & Their Buffers

Through pxd_defimage, pxd_defineImage, pxvid_setpximage or similar functions, an image buffer and rectangular area of interest is defined as the source and the destination to be used by a typical image processing function. The image buffer need not be the currently displayed image buffer, nor must the source and destination be the same buffer.

Applications which utilize multiple frame grabbers should specify unit selection via pxdrv_devunit before pxvid_setpximage, pxvid_setpximage2, or pxvid_setpximage3, is invoked; or should specify unit selection via pxd_unit before pxd_defimage, pxd_defimage3, pxd_defimagecolor, or pxd_defimage3color is invoked; or should specify unit selection as a parameter to pxd_defineImage, pxd_defineImage3, ::initPximage, ::initFilteredPximage, ::initPximage3 or ::initFilteredPximage3. The unit selection is encoded into the resultant pximage structure; the unit selection in effect when the image processing operation is actually invoked does not effect the unit selection encoded into the pximage structure.

This allows any image processing operation to operate across frame grabbers, as easily as across image buffers. For example, using SVOBJ, 4MOBJ, or XCOBJ, to subtract the lower right quadrant of buffer 1 on frame grabber 0 from the upper left quadrant of buffer 2 on frame grabber 1 and put the result in the lower left quadrant of buffer 3 on frame grabber 0, requires: 

struct  pximage src1, src2, dst;


pxdrv_devunit(0);                       // specify unit 0
pxvid_setpximage(&src1, PXSDIGI, 1);    // define full image
src1.wind.nw.x = src1.wind.se.x / 2;    // set area of interest
src1.wind.nw.y = src1.wind.se.y / 2;    // as lower right quad
pxvid_setpximage(&dst, PXSDIGI, 3L);    // define full image
src1.wind.se.x = src1.wind.se.x / 2;    // set area of interest
src1.wind.nw.y = src1.wind.se.y / 2;    // as lower left  quad
pxdrv_devunit(1);                       // specify unit 1
pxvid_setpximage(&src2, PXSDIGI, 2L);   // define full image
src1.wind.se.x = src1.wind.se.x / 2;    // set area of interest
src1.wind.se.y = src1.wind.se.y / 2;    // as upper left  quad


pxip8_pairsub(NULL, &src1, &src2, &dst, 0);
Invoking pxdrv_devunit need not be done by applications using a single frame grabber.

All of the above assumes the frame grabber libraries have already been opened, with pxd_svopen, or svdrv_open for the SVOBJ library; with pxd_m4open or m4drv_open for the 4MOBJ library; with pxd_xcopen or xcdrv_open for the XCOBJ library; or with pxd_PIXCIopen or xclib_open for the XCLIB library.

1.6.3. Frame Grabbers & Processing Speed

When used with 4MOBJ and SVOBJ, most image processing functions operate quicker when invoked with the frame grabber neither acquiring nor displaying video. Application programs can, if desired, take advantage of this feature by: (1) Turning video capture and display off, (2) Invoking the image processing function, (3) Restoring video to the previous state. See pxd_video, pxvid_go, or similar functions.

When used with XCOBJ or XCLIB, image buffers are, by definition, in PC memory, and access while acquiring video is not slowed significantly. Still, capturing video does utilize PC bus bandwidth, and image processing functions might be (depending upon the particular PCI chipset and CPU used) slightly faster if video capture were turned off.

1.6.4. Math Coprocessors

A math coprocessor is not required for operation of any library function, but some functions will perform faster if a math coprocessor is installed. Those functions which would benefit from a math coprocessor are so noted in their description.

1.6.5. On Color(s)

Most library functions are insensitive to the color gamut claimed by the provided pximage. For example, pxip8_pixset sets pixel components to a specified value, quite independently of whether the components claim to be RGB, HSB, or YCrCb. Exceptions, functions which support only specified color gamuts, or functions which automatically modify their actions according to the claimed color gamut, are explicitly noted.

Some functions may claim to support only monochrome (or single component pixel) images. Or, it maybe useful to operate upon only one of the color components. The pximage_colorslice can be used to create a ''filtering'' pximage on top of the color pximage; the filtered result claiming to be, and operating as, an image with single component pixels, accessing and modifying a selected component of the color image.

1.6.6. On Structures and Signatures

Various structures which might change between versions of PXIPL may utilize a ''signature'', so that an application compiled with an older version of PXIPL can't declare an older, smaller, structure and have it accepted by a newer library expecting a newer, larger, structure. Structures that are changed typically define the added fields so that a zero value maintains the previous structure's effect.

Applications should initialize ''new'' instances of structures by zeroing the entire structure to 0. If the structure has ddch.len and ddch.cnt ''signatures'', the ddch.len and ddch.cnt should be set to the size of the structure, and to a signature constant, respectively. For example, 

    struct pximfileinfo fileinfo_structure;


    memset(&fileinfo_structure, 0, sizeof(fileinfo_structure));
    // and then, as required by the application ...
    fileinfo_structure.fi.bmp.biXPelsPerMeter = 1000;
    fileinfo_structure.fi.bmp.biYPelsPerMeter = 1000;

 

 

 

2. Support Functions

User-Defined Premature Termination Functions --- pxabortfunc_t



Summary 
typedef int (_cfunfcc pxabortfunc_t)(void*,int,int); // _cfunfcc is a predefined
int _cfunfcc users_abort_function(vp,done,total);    // .. function modifier
void                *vp;
int                 done;
int                 total;



Description

Image processing functions, such as the ''pxip8_'' and ''pxirp8_'' series, typically accept an abortp parameter of type pxabortfunc_t, such as: 

int pxip8_copy(abortp, sip, dip);
pxabortfunc_t   **abortp;
struct  pximage *sip;
struct  pximage *dip;
If abortp≠NULL, the image processing function will periodically invoke: 
(*abortp)(abortp, ipos, npos);
and prematurely terminate if the return value is nonzero, echoing the same return value. Use of termination values less than 0 is required. Use of the particular value PXERBREAK is suggested.

The values passed as done and total indicate the approximate progress of the processing function. If total>0, then the processing function, or one phase of the processing function, is approximately done*100.0/total percent complete.

If total=0 and done=0, this particular invocation of *abortp is not updating the progress information, or this processing function does not provide progress information.

If total<0, then the processing is being done in phases, with each phase independently reporting progress from 0 to 100%; the number of phases is -total, of which the current phase is done, where 1<=done<=-total. The processing time required may differ among the phases.

If total=0 and done≠0, then done should be added to an internal ''disable'' counter whose initial value is 0. While the disable counter is less than 0, interpretation of invocations with total>0 (percent completion) or total<0 (operation phase) should be ignored.

The total and done values are intended solely for optionally advising an interactive user of computational progress, and have accuracy suitable only for such use.


Example

An example code fragment using the ``C'' library signal function is shown. 

#include <signal.h>     // c library
#include <stdio.h>      // c library


int              brokeflag;
int _cfunfcc     userabort(void*p,int a,int b)  { return(brokeflag); }
pxabortfunc_t    *userabortadrs = userabort;
void             sigint(void)                   { brokeflag = PXERBREAK; }


/*
 * Set up signal catching & flag setting, then invoke an image
 * processing function. The image processing function will
 * prematurely terminate if CTRL+BREAK is pressed.
 */
brokeflag = 0;
signal(SIGINT, sigint);
 ...
pxip8_copy(&userabortadrs, ...);
Construct PXIMAGE: Access Image in Host Memory --- pximage_memory
Construct PXIMAGE: Access Image in Host Memory --- pximage_memory2
Construct PXIMAGE3: Access Image Sequence in Host Memory --- pximage3_memory
Construct PXIMAGE3: Access Image Sequence in Host Memory --- pximage3_memory2



Summary 
int pximage_memory  (tp, imagep, dimp, rsvd, pixtype, bitsused, pixies, pixelhint, accflags);
int pximage3_memory (t3p,imagep, dim3p,rsvd, pixtype, bitsused, pixies, pixelhint, accflags);
int pximage_memory2 (tp, imagep, dimp, rsvd, pixtype, bitsused, pixies, pixelhint, accflags,
                     pixelwidth, pixelheight, pixelwhunits);
int pximage3_memory2(t3p,imagep, dim3p,rsvd, pixtype, bitsused, pixies, pixelhint, accflags,
                     pixelwidth, pixelheight, pixelwhunits, pixeldepth, pixeldunits);


struct pximage      *tp;            // Constructed pximage
struct pximage3     *t3p;           // Constructed pximage3
void  _far          *imagep;        // Image buffer, supplied [16 bit mode]
void                *imagep;        // Image buffer, supplied [32 bit mode]
const struct pxy    *dimp;          // Image dimensions
const struct pxyz   *dim3p;         // Image sequence dimensions
uint                rsvd;           // Reserved. must be 0
int                 pixtype;        // Pixel type, PXDATUCHAR, PXDATUSHORT, ...
int                 bitsused;       // For uint type, # bits actually used per pixie
int                 pixies;         // Number of pixies per pixel
int                 pixelhint;      // Pixel interpretation hint, or 0
uint                accflags;       // PXACC* flags describing access to *imagep, or 0
float               pixelwidth;     // Actual pixel width, or 0
float               pixelheight;    // Actual pixel height, or 0
int                 pixelwhunits;   // Width/height units, PXUNITINCH, ..., or 0
float               pixeldepth;     // Actual pixel depth, or 0
int                 pixeldunits;    // Depth units, PXUNITINCH, PXUNITSECOND, or 0



Description

The pximage (or pximage3) structure pointed to by tp (or t3p) is initialized so that it references a two-dimensional image (or sequence of two-dimensional images) in a memory buffer starting at address imagep. The image dimensions are dimp->x pixels wide by dimp->y pixels high (or dim3p->x pixels wide by dim3p->y pixels high with dim3p->z images in the sequence). The pixtype specifies the size and interpretation of each pixel value as follows: 





C Type         


 Pixtype








unsigned char  


 PXDATUCHAR






unsigned short 


 PXDATUSHORT






unsigned int   


 PXDATUINT






unsigned long  


 PXDATULONG






float          


 PXDATFLOAT






double         


 PXDATDOUBLE






 8 bit unsigned integer 


 PXDATUINT8






16 bit unsigned integer 


 PXDATUINT16






32 bit unsigned integer 


 PXDATUINT32
The PXDATULONG is not available in programming environments where a ''long'' is 64 bits. Use of PXDATUINT8, PXDATUINT16, and PXDATUINT32 instead of PXDATUCHAR, PXDATUSHORT, PXDATUINT, and PXDATULONG is recommended for easier portability between 16, 32, and 64 bit programming environments. The pixies specifies the number of component values per pixel; e.g. pixies=1 for monochrome pixels. For unsigned integer pixels, the bitsused specifies the number of bits actually used (right justified) per pixie, e.g. bitsused=12 for pixel values ranging from 0 to 4095; if bitsused=0, then all bits of the pixtype are used.

The pixelhint is an optional hint as to how the pixel, particularly multiple component pixels (i.e. color), is to be interpreted; typical values are described under pximage. The accflags are PXACC* flags describing the relative delay in accessing the buffer at imagep; it may be used by some algorithms to decide whether there is an advantage to caching pixel data. If unknown, accflags=0 should be used.

The pixelwidth, pixelheight, and pixelwhunits are optional hints as to the actual dimensions of each pixel; the pixelwidth and pixelheight provide either the numeric size, or a dimensionless ratio, and the pixelwhunits provides the units or specifies dimensionless ratio. (The pixeldepth and pixeldunits are optional hints as to the actual depth of pixels through image sequence; the pixeldepth provides the numeric size, and the pixeldunits provides the dimensional or temporal units). Typical values of pixelwhunits (and pixeldunits) are described under pximage. If unknown, values of 0 should be used for pixelwidth, pixelheight, and pixelwhunits (or pixeldepth and pixeldunits). The slightly simpler pximage_memory (or pximage3_memory) versions are equivalent to invoking pximage_memory2 (or pximage3_memory2) with pixelwidth, pixelheight, and pixelwhunits (or pixeldepth and pixeldunits) set to 0.

The pximage_memory, pximage_memory2 (or pximage3_memory, pximage3_memory2) does not malloc, free, or otherwise create or destroy the actual image buffer (or image buffers). It assumes that the *imagep is of size: 

dimp->x * dimp->y * pixies * size_of_the_pixtype
or 
dim3p->x * dim3p->y * pixies * size_of_the_pixtype * dim3p->z
Access to the buffer is in the order: 
Each pixie of a pixel.
Each pixel of a line, left-to-right.
Each line of image, top-to-bottom.
(Each image of sequence, first to last).
The pximage constructed by pximage_memory, pximage_memory2 (or pximage3_memory, pximage3_memory2) may be freely copied, cleared, and destroyed without concern of deallocating resources.

After use of pximage_memory, pximage_memory2 (or pximage3_memory, pximage3_memory2), the AOI window, tp->wind (or t3p->wind), is the same as the image dimensions, tp->imdim (or t3p->imdim). The tp->wind (or t3p->wind) can thereafter be modified by the caller. Other members of the pximage (or pximage3) structure should not be directly modified.

For pixtype of PXDATFLOAT or PXDATDOUBLE, the range of expected pixel values is 0.0 through 1.0.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp (or t3p) is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Contact Technical Support.



See Also The pximage_memmalloc and pximage_memmalloc2 (or pximage3_memmalloc and pximage3_memmalloc2) are similar, but also allocate the image memory and/or the pximage (or pximage3) instance.


Example

A pximage is constructed and used. 

    struct pximage image;
    struct pxy dim = {256, 256};
    uchar  buffer[256][256][3];


    pximage_memory(&image, buffer, dim, 0, PXDATUCHAR, 8, 3, PXHINTRGB, 0);
    pxip8_testpattern(NULL, &image, 0, 100);
    pxio8_tifwrite(NULL, &image, NULL, "test.tif", 8, 0, 0, NULL);

A pximage3 is constructed and used, demonstrating alternate methods of access to common pixel data. 

    //
    // image dimensions
    #define XDIM    234
    #define YDIM    123
    #define ZDIM    23
    //
    // pick one pixel to play with
    #define X       2
    #define Y       3
    #define Z       4
    //
    // Use array for image data & array subscripts
    // for raw access? Or use malloc and explicit expression.
    #define XYZARRAY    1
    //
    #if XYZARRAY
      uchar     image[ZDIM][YDIM][XDIM];
    #else
      uchar     *image = NULL;
      #define   Index3(X,Y,Z)   (Z)*(XDIM*YDIM)+(Y)*(XDIM)+(X)
    #endif
    //
    pximage3_s  image3;
    pximage_s   image2;
    pxyz_s   xyz = {XDIM, YDIM, ZDIM};
    int     r;
    uchar   c;
    .sp .5
    //
    // Allocate space for image buffers?
    #if !XYZARRAY
        image = malloc(XDIM*YDIM*ZDIM);
        if (!image) {
            printf("No memory!\n");
            return(0);
        }
    #endif
    //
    // Clear & set chosen pixel to nonzero
    // via raw access.
    #if XYZARRAY
        memset(image, 0, XDIM*YDIM*ZDIM);
        image[Z][Y][X] = 1;
    #else
        memset(image, 0, XDIM*YDIM*ZDIM);
        image[Index3(X,Y,Z)] = 1;
    #endif
    //
    // Create pximage3 style access.
    r = pximage3_memory(&image3, image, &xyz, XDIM,
             PXDATUCHAR, 8, 1, PXHINTGREY, 0);
    printf("pximage3_memory = %d\n", r);
    r = image3.ioset(&image3, PXRXSCAN, PXDATUCHAR, 1);
    printf("pximage3.ioset = %d\n", r);


    //
    // R/W chosen pixel, demonstrating
    // access to same data either via pximage3 or
    // via raw access.
    r = image3.ioread(&image3, 0, &c, 1, X, Y, Z);
    printf("pximage3.ioread r=%d  c=%d\n", r, c);
    c = 2;
    r = image3.iorite(&image3, 0, &c, 1, X, Y, Z);
    printf("pximage3.iorite r=%d  c=%d\n", r, c);
    #if XYZARRAY
        c = image[Z][Y][X];
    #else
        c = image[Index3(X,Y,Z)];
    #endif
    printf("raw read c=%d\n", c);
    //
    // Create a 2-d pximage to access one slice of the 3-d image.
    r = pximage_def2from3(&image2, &image3, PXRXSCAN, PXRYSCAN, Z, 0);
    printf("pximage_def2from3 = %d\n", r);
    r = image2.ioset(&image2, PXRXSCAN, PXDATUCHAR, 1);
    printf("pximage2.ioset = %d\n", r);
    //
    // R/W chosen pixel, demonstrating
    // access to same data either via pximage2 or
    // via raw access.
    r = image2.ioread(&image2, 0, &c, 1, X, Y);
    printf("pximage2.ioread r=%d  c=%d\n", r, c);
    c = 3;
    r = image2.iorite(&image2, 0, &c, 1, X, Y);
    printf("pximage2.iorite r=%d  c=%d\n", r, c);
    #if XYZARRAY
        c = image[Z][Y][X];
    #else
        c = image[Index3(X,Y,Z)];
    #endif
    printf("raw read c=%d\n", c);
    //
    // clean up
    #if !XYZARRAY
        free(image);
    #endif
Construct PXIMAGE: Allocate Image in Malloc'ed Memory --- pximage_memmalloc
Construct PXIMAGE: Release Image in Malloc'ed Memory --- pximage_memfree
Construct PXIMAGE3: Allocate Image Sequence in Malloc'ed Memory --- pximage3_memmalloc
Construct PXIMAGE3: Release Image Sequence in Malloc'ed Memory --- pximage3_memfree



Summary 
int pximage_memmalloc (tp, handlep, dimp, pixtype, bitsused, pixies, pixelhint);
int pximage3_memmalloc(t3p,handlep, dim3p,pixtype, bitsused, pixies, pixelhint);


struct pximage      *tp;            // Constructed pximage
struct pximage3     *t3p;           // Constructed pximage3
void _far * _far    *handlep;       // A * NULL, becomes *handle [16 bit mode]
void                **handlep;      // A * NULL, becomes *handle [32 bit mode]
const struct pxy    *dimp;          // Image dimensions
const struct pxyz   *dim3p;         // Image sequence dimensions
int                 pixtype;        // Pixel type, PXDATUCHAR, PXDATUSHORT, ...
int                 bitsused;       // For uint type, # bits actually used per pixie
int                 pixies;         // Number of pixies per pixel
int                 pixelhint;      // Pixel interpretation hint, or 0


int pximage_memfree (tp, handlep);
int pximage3_memfree(t3p, handlep);
struct pximage      *tp;            // Deconstructed pximage
struct pximage3     *t3p;           // Deconstructed pximage3
void                **handlep;      // A * handle, becomes *NULL



Description

A memory buffer for a two-dimensional image (or three-dimensional image sequence) is obtained from _fmalloc'ed (16 bit environments) or malloc'ed (32 bit environments), and the pximage (or pximage3) structure pointed to by tp (or t3p) is initialized so that it references the memory buffer.

The *handlep must initially be NULL; pximage_memmalloc (or pximage3_memmalloc) sets *handlep as a reference to resources which must be eventually released by pximage_memfree (or pximage3_memfree).

The image dimensions are dimp->x pixels wide by dimp->y pixels high. (or dim3p->x pixels wide by dim3p->y pixels high with dim3p->z images in the sequence). The pixtype, bitsused, pixies, and pixelhint have the same meaning as for pximage_memory (or pximage3_memory); the pximage_memmalloc (or pximage3_memmalloc) is, in essence, allocation of an image memory buffer followed by pximage_memory (or pximage3_memory).

After use of pximage_memmalloc (or pximage3_memmalloc) the AOI window, tp->wind (or t3p->wind), is the same as the image dimensions, tp->imdim (or t3p->imdim). The tp->wind (or t3p->wind) can thereafter be modified by the caller. Other members of the pximage (or pximage3) structure should not be directly modified.

After finishing use of (all copies of) the pximage (or pximage3) the pximage_memfree (or pximage3_memfree) must be called with the same handlep to free the resources allocated by pximage_memmalloc (or pximage3_memmalloc). The pximage (or pximage3) referenced by tp (or t3p) is re-initialized as a NULL image with dimensions of 0 to prevent accidental reuse of released resources.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp (or t3p) is initialized as a NULL image with dimensions of 0.

PXERMALLOC
Memory allocation error.

PXERLOGIC
Contact Technical Support.



See Also The pximage_memmalloc2 (or pximage3_memmalloc2) are similar, but also allocate the pximage (or pximage3).
Construct PXIMAGE: Allocate Image in Malloc'ed Memory --- pximage_memmalloc2
Construct PXIMAGE: Release Image in Malloc'ed Memory --- pximage_memfree2
Construct PXIMAGE3: Allocate Image Sequence in Malloc'ed Memory --- pximage3_memmalloc2
Construct PXIMAGE3: Release Image Sequence in Malloc'ed Memory --- pximage3_memfree2



Summary 
struct pximage *  pximage_memmalloc2 (imagep, pixtype, bitsused, pixies, pixelhint,
                                      xdim, ydim, pixelwidth, pixelheight, pixelwhunits);
struct pximage3 * pximage3_memmalloc2(imagep, pixtype, bitsused, pixies, pixelhint,
                                      xdim, ydim, pixelwidth, pixelheight, pixelwhunits,
                                      zdim, pixeldepth, pixeldunits);


void  _far          *imagep;        // Supplied image buffer [16 bit mode], or NULL
void                *imagep;        // Supplied image buffer [32 bit mode], or NULL
int                 pixtype;        // Pixel type, PXDATUCHAR, PXDATUSHORT, ...
int                 bitsused;       // For uint type, # bits actually used per pixie
int                 pixies;         // Number of pixies per pixel
int                 pixelhint;      // Pixel interpretation hint, or 0
pxcoord_t           xdim;           // Horizontal image dimension
pxcoord_t           ydim;           // Vertical image dimension
pxcoord_t           zdim;           // Sequence image dimension
float               pixelwidth;     // Actual pixel width, or 0
float               pixelheight;    // Actual pixel height, or 0
int                 pixelwhunits;   // Width/height units, PXUNITINCH, ..., or 0
float               pixeldepth;     // Actual pixel depth, or 0
int                 pixeldunits;    // Depth units, PXUNITINCH, PXUNITSECOND, or 0


int pximage_memfree2 (tp, imagep);
int pximage3_memfree2(t3p,imagep);
struct pximage      *tp;            // Deconstructed pximage
struct pximage3     *t3p;           // Deconstructed pximage3
void  _far          *imagep;        // Supplied image buffer [16 bit mode], or NULL
void                *imagep;        // Supplied image buffer [32 bit mode], or NULL



Description

A two-dimensional image buffer (or three-dimensional image buffer sequence) and a pximage (or pximage3) structure which refers to the image buffer (sequence) is constructed.

If imagep is NULL, a memory buffer for a two-dimensional image (or three-dimensional image sequence) is obtained from _fmalloc'ed (16 bit environments) or malloc'ed (32 bit environments). Otherwise, imagep is assumed to be an existing memory buffer sufficiently large for the image (or image sequence).

The pximage (or pximage3) structure is always malloc'ed.

The image dimensions are xdim pixels wide by ydim pixels high. (or xdim pixels wide by ydim pixels high with zdim images in the sequence). The pixtype, bitsused, pixies, pixelhint, pixelwidth, pixelheight, and pixelwhunits, (and pixeldepth, pixeldunits) have the same meaning as for pximage_memory2 (or pximage3_memory2); the pximage_memmalloc2 (or pximage3_memmalloc2) is, in essence, an optional allocation of an image memory buffer and allocation of a pximage (or pximage3) followed by pximage_memory2 (or pximage3_memory2).

After use of pximage_memmalloc2 (or pximage3_memmalloc2) the AOI window, tp->wind (or t3p->wind), is the same as the image dimensions, tp->imdim (or t3p->imdim).

After finishing use of the pximage (or pximage3) the pximage_memfree2 (or pximage3_memfree2) must be called with the return'ed pximage (or pximage3) and the same imagep to free the resources allocated by pximage_memmalloc2 (or pximage3_memmalloc2).

As compared to pximage_memory and pximage_memmalloc (or pximage3_memory and pximage3_memmalloc), the pximage_memmalloc2 (or pximage3_memmalloc2) are intended to be significantly easier to use, especially from non-C/C++ environments.


Returns The pximage_memmalloc2 (or pximage3_memmalloc2) returns a pointer to the pximage (or pximage3) which has been constructed, or NULL in the event of an error such as invalid parameters or memory allocation error.

The pximage_memfree2 (or pximage3_memfree2) returns:


0
Operation complete.

PXERROR
Invalid parameters.



Example

An image buffer and pximage is allocated, constructed, used, and freed. 

    struct pximage *ip;


    ip = pximage_memmalloc2(NULL, PXDATUCHAR, 8, 3, PXHINTRGB, 1024, 1024, 0, 0, 0);
    if (ip) {
        pxip8_testpattern(NULL, ip, 0, 100);
        pxio8_tifwrite(NULL, ip, NULL, "test.tif", 8, 0, 0, NULL);
        pximage_memfree2(ip, NULL);
    }

A pximage is constructed to refer to an existing memory buffer, used, and freed. 

    struct pximage *ip;
    uchar  buffer[256][256];
    int    x, y;


    ip = pximage_memmalloc2(buffer, PXDATUCHAR, 8, 1, PXHINTGREY, 256, 256, 0, 0, 0);
    for (x = 0; x < 256; x++)
        for (y = 0; y < 256; y++)
            buffer[x][y] = (x*y)/(256*256);
    if (ip) {
        pxio8_tifwrite(NULL, ip, NULL, "test.tif", 8, 0, 0, NULL);
        pximage_memfree2(ip, buffer);
    }
Construct PXIMAGE: Access Image in File --- pximage_file
Construct PXIMAGE: Access Image in File, Done --- pximage_filedone



Summary 
int pximage_file(tp,handlep,filep,dimp,type,bitsused,pixies,rsvd,buffersize);
struct pximage      *tp;            // Constructed pximage
void                **handlep;      // A * NULL, becomes *handle
const char          *pathname;      // Name of image file
const char          *filemode;      // Fopen() modes for file, or NULL
const struct pxy    *dimp;          // Image dimensions
int                 pixtype;        // Pixel type, PXDATUCHAR, PXDATUSHORT, ...
int                 bitsused;       // For uint type, # bits actually used.
int                 pixies;         // Number of pixies per pixel
int                 pixelhint;      // Pixel interpretation hint, or 0
uint                buffersize;     // Size of file buffer, or 0


int pximage_filedone(tp, handle);
struct pximage      *tp;            // Unconstructed pximage
void                **handlep;      // A * handle, becomes *NULL



Description

The pximage_file initializes the pximage structure pointed to by tp so that it references a two-dimensional image in a file named pathname. The pathname is fopen'ed with modes specified by filemode, which should specify (see fopen) read, write, or read/write modes, as appropriate for the intended image access. If filemode=NULL, modes of "wb" are used.

The file's image dimensions are dimp->x pixels wide by dimp->y pixels high. The pixtype specifies the size and interpretation of each pixel value as follows: 





C Type         


 Pixtype








unsigned char  


 PXDATUCHAR






unsigned short 


 PXDATUSHORT






unsigned int   


 PXDATUINT






unsigned long  


 PXDATULONG






float          


 PXDATFLOAT






double         


 PXDATDOUBLE






 8 bit unsigned integer 


 PXDATUINT8






16 bit unsigned integer 


 PXDATUINT16






32 bit unsigned integer 


 PXDATUINT32
The PXDATULONG is not available in programming environments where a ''long'' is 64 bits. Use of PXDATUINT8, PXDATUINT16, and PXDATUINT32 instead of PXDATUCHAR, PXDATUSHORT, PXDATUINT, and PXDATULONG is recommended for easier portability between 16, 32, and 64 bit programming environments. The pixies specifies the number of component values per pixel; e.g. pixies=1 for monochrome pixels. For unsigned integer pixels, the bitsused specifies the number of bits actually used (right justified), e.g. bitsused=12 for pixel values ranging from 0 to 4095. The pixelhint is an optional hint as to how the pixel, particularly multiple component pixels (i.e. color), is to be interpreted; typical values are described under pximage.

The pixels in the file are in the order: 

Each pixie of a pixel.
Each pixel of a line, left-to-right.
Each line, top-to-bottom.

The buffersize is a suggested buffer size; such a buffer is internally malloc'ed. A larger buffer size may provide more efficient access to the image file, at the expense of memory usage.

The *handlep must be initially NULL; pximage_file sets *handlep as a reference to resources which must be eventually released by pximage_filedone.

After use of pximage_file, the AOI window, tp->wind, is the same as the image dimensions, tp->imdim. The tp->wind can thereafter be modified by the caller. Other members of the pximage structure should not be directly modified.

The pximage constructed by pximage_file may be freely copied, cleared, and destroyed without concern of deallocating resources. After finishing use of (all copies of) the pximage, the pximage_filedone must be called with the same handlep to free the resources allocated by pximage_file. The pximage referenced by tp is re-initialized as a NULL image with dimensions of 0 to prevent accidental reuse of released resources.

Currently, use of pixies>1 is not supported.

The pximage_file is (was) primarily for use on machines with insufficient memory to contain the desired image buffers. It has little, if any, use on machines with sufficient program memory, whether physical or virtual.


Returns


0
Operation complete.

PXERMALLOC
Memory allocation error.

PXERROR
Invalid parameters.

PXERLOGIC
Contact Technical Support.
In event of error, the structure referenced by tp is initialized as a NULL image with dimensions of 0.

During or after use of the pximage, the pximage.error may be invoked to check whether any errors have occurred, as follows:


0
No error occurred.

PXERNOFILE
File could not be opened with specified modes.

PXERDOSIO
DOS/Windows I/O read or write error.

PXERFILEFORM
The image was read, and the file referenced by filep is smaller than the image's size.
Construct PXIMAGE: Slice of Color Image --- pximage_colorslice



Summary 
int pximage_colorslice(tp, otp, windpassthru, colormap, rsvd);
struct pximage      *tp;            // Constructed pximage
struct pximage      *otp;           // Existing pximage
int                 windpassthru;   // 1: Imdim same as *otp, xwind passed thru to *otp
                                    // 0: Imdim is *otp wind, xwind is private
uint                colormap;       // Which color component(s) to slice off and present
int                 rsvd;           // Reserved. should be 0



Description

The pximage structure pointed to by tp is initialized so that it references one color component ''slice'' of the existing, multi-color, image referenced by otp. The *tp is initialized to the same data type as *otp, but with only one pixie per pixel. Any reference to a pixel through *tp becomes a reference to the colormap pixie of *otp, where colormap is a bit mapped color selector with only one bit set (i.e. 0x01 for the first pixie, 0x02 for the second pixie, 0x04 for the third pixie, etc).

The *tp becomes a filter to the *otp; the *otp must remain in existence while *tp is used. Also, as *tp uses pximage::ioset and similar services of *otp, the *otp cannot be shared with other usages.

If windpassthru=1, the image dimensions and initial window of *tp are the same as the dimensions and initial window of *otp, respectively; any ::xwind on *tp is passed through to *otp. If windpassthru=0, the image dimensions and initial window of *tp are the same as the initial window of *otp; any ::xwind on *tp affects only the *tp's window.

The pximage_colorslice isn't needed simply to access color components of pximage, the ::ioset of the color pximage directly allows access to an individual component. Rather, pximage_colorslice is useful to ''trick'' an existing library function, which expects only a single component pixel, to operate upon a selected component of a multi-component pixel. For example, to perform a histogram on only the red component of an RGB image, using a histogram function that expects a monochrome image.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Contact Technical Support.
Construct PXIMAGE: Converted Color Space of Image --- pximage_colorconverter



Summary 
int pximage_colorconverter(tp, otp, newhint, windpassthru);
struct pximage      *tp;            // Constructed pximage
struct pximage      *otp;           // Existing pximage
int                 newpixelhint;   // Requested color space
int                 windpassthru;   // 1: Imdim same as *otp, xwind passed thru to *otp
                                    // 0: Imdim is *otp wind, xwind is private



Description

The pximage structure pointed to by tp is initialized as a filter which converts the color space of the image referenced by otp to the color space specified by newpixelhint. The *tp is initialized to the same data type as *otp.

The newpixelhint can be any PXHINT type value, such as PXHINTGREY, PXHINTRGB, etc., although not all combinations of possible color space conversions are actually supported.

The *tp becomes a filter to the *otp; the *otp must remain in existence while *tp is used. Also, as *tp uses pximage::ioset and similar services of *otp, the *otp cannot be shared with other usages. The image data referenced by tp is not changed, except by explicit use of pximage::iorite or similar functions.

If windpassthru=1, the image dimensions and initial window of *tp are the same as the dimensions and initial window of *otp, respectively; any ::xwind on *tp is passed through to *otp. If windpassthru=0, the image dimensions and initial window of *tp are the same as the initial window of *otp; any ::xwind on *tp affects only the *tp's window.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp is initialized as a NULL image with dimensions of 0.

PXERNOCOLOR
The combination of newpixelhint, tp->d.pixelhint, and tp->d.pixeltype isn't supported. The structure referenced by tp is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Contact Technical Support.



Example

An existing pximage, which accesses an existing image buffer in one color space is filtered so as to allow access to the image buffer in a different color space. 

    struct  pximage image;      // existing pximage, perhaps RGB
    struct  pximage filter;     // newly constructed pximage


    r = pximage_colorconverter(&filter, &image, PXHINTGREY, 0);
    if (r < 0)
        printf("error\n");
    else
        //
        // Complement image, in grey scale color space.
        // The result is written back into the original
        // image, thus it will be RGB, but with R=G=B.
        //
        pxip8_pixneg(NULL, &filter, &filter);
Construct PXIMAGE: 2-D Slice of 3-D Image --- pximage_def2from3



Summary 
int pximage_def2from3(tp, otp, xaxis, yaxis, slice, windpassthru);
struct pximage      *tp;            // Constructed pximage
struct pximage3     *otp;           // Existing pximage3
int                 xaxis;          // New xaxis should be: PXR*SCAN of otp
int                 yaxis;          // New yaxis should be: PXR*SCAN of otp
pxcoord_t           slice;          // Fixed coordinate for remaining axis of otp
                                    // relative to window
int                 windpassthru;   // 1: Imdim same as *otp, xwind passed thru to *otp
                                    // 0: Imdim is *otp wind, xwind is private



Description

The pximage structure pointed to by tp is initialized so that it references a two-dimensional ''slice'' of the existing, three-dimensional, image referenced by otp. The *tp is initialized to the same data type as *otp.

The xaxis must be PXRXSCAN, PXRYSCAN, or PXYZSCAN, specifying that the ''x'' coordinate of tp is to correspond to the ''x'', ''y'', or ''z'' coordinate of otp. Similarly, the yaxis must be PXRXSCAN, PXRYSCAN, or PXYZSCAN, yaxis≠xaxis, specifying that the ''y'' coordinate of tp is to correspond to the ''x'', ''y'', or ''z'' coordinate of otp. The slice specifies the fixed coordinate for the third remaining coordinate of otp.

Any reference to a pixel through *tp becomes a reference to the corresponding pixel of *otp. Typically, xaxis=PXRXSCAN and yaxis=PXRYSCAN allowing tp to access all pixels at the slice buffer (i.e. ''Z'' coordinate) of otp.

The *tp becomes a filter to the *otp; the *otp must remain in existence while *tp is used. Also, as *tp uses pximage::ioset and similar services of *otp, the *otp cannot be shared with other usages.

If windpassthru=1, the image dimensions and initial window of *tp are the same as the dimensions and initial window of *otp, respectively; any ::xwind on *tp is passed through to *otp. If windpassthru=0, the image dimensions and initial window of *tp are the same as the initial window of *otp; any ::xwind on *tp affects only the *tp's window.

The pximage_def2from3 is useful to ''trick'' an existing library function, which expects only a two-dimensional image, to operate upon a selected slice of a three-dimensional image.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Contact Technical Support.
Construct PXIMAGE: 3-D Representation of 2-D Image --- pximage_def3from2



Summary 
int pximage_def3from2(tp, otp, windpassthru);
struct pximage3     *tp;            // Constructed pximage3
struct pximage      *otp;           // Existing pximage
int                 windpassthru;   // 1: Imdim same as *otp, xwind passed thru to *otp
                                    // 0: Imdim is *otp wind, xwind is private



Description

The pximage structure pointed to by tp is initialized so that it references a three-dimensional representation of the existing, two-dimensional, image referenced by otp. The *tp is initialized to the same data type as *otp, with a ''z'' dimension of 1.

The *tp becomes a filter to the *otp; the *otp must remain in existence while *tp is used. Also, as *tp uses pximage::ioset and similar services of *otp, the *otp cannot be shared with other usages.

If windpassthru=1, the image dimensions and initial window of *tp are the same as the dimensions and initial window of *otp, respectively; any ::xwind on *tp is passed through to *otp. If windpassthru=0, the image dimensions and initial window of *tp are the same as the initial window of *otp; any ::xwind on *tp affects only the *tp's window.

The pximage_def3from2 is useful to ''trick'' an existing library function, which expects only a three-dimensional image, to operate upon a two-dimensional image.


Returns


0
Operation complete.

PXERROR
Invalid parameters. The structure referenced by tp is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Contact Technical Support.
Set PXIMAGE: Set 2-D Area of Interest Window --- pximage_setwind
Set PXIMAGE3: Set 3-D Area of Interest Window --- pximage3_setwind



Summary 
int pximage_setwind (tp, ulx, uly, lrx, lry);
int pximage3_setwind(t3p,ulx, uly, ulz, lrx, lry, lrz);


struct pximage      *tp;            // Existing pximage
struct pximage3     *t3p;           // Existing pximage3
pxcoord_t           ulx;            // Upper left corner, x coordinate
pxcoord_t           uly;            // Upper left corner, y coordinate
pxcoord_t           ulz;            // Upper left corner, z coordinate
pxcoord_t           lrx;            // Lower right corner, x coordinate
pxcoord_t           lry;            // Lower right corner, y coordinate
pxcoord_t           lrz;            // Lower right corner, z coordinate



Description

The pximage_setwind (or pximage3_setwind) allows setting the two-dimensional (or three-dimensional) area of interest window in an existing pximage (or pximage3). They are particularly handy for for non ''C/C++'' environments, that don't have easy access to the ''C'' structures that are used with the pximage (or pximage3) services.

The ulx and uly respectively specify the horizontal (x) and vertical coordinate (y) of the upper left corner of an area of interest in the image to be used. The lrx and lry respectively specify a value one greater than the horizontal and vertical coordinate of the lower right corner of an area of interest in the image (i.e. an exclusive corner point) to be used. The lrx and lry may each be abbreviated to -1 to specify the extreme right horizontal coordinate or the extreme bottom vertical coordinate, respectively.

(The ulz specifies the depth or sequence (z) coordinate of the upper left corner of an area of interest in the image sequence to be used. The lrz specifies a value one greater than the depth or sequence coordinate of the lower right corner of an area of interest in the image sequence (i.e. an exclusive corner point) to be used. The lrz may be abbreviated to -1 to specify the extreme depth coordinate.)


Returns


0
Operation complete.

PXERROR
Invalid parameters, such as coordinate values that are negative or exceed the image bounds.



Example

An image is constructed, and the area of interest changed. 

    struct pximage *ip;


    ip = pximage_memmalloc2(NULL, PXDATUCHAR, 8, 3, PXHINTRGB, 1024, 1024, 0, 0, 0);
    if (ip) {
        pximage.setwind(ip, 0, 0, 512, 512);    // set to upper left quadrant
        pxip8_testpattern(NULL, ip, 0, 100);    // draw in upper left quadrant
        pximage.setwind(ip, 0, 0, -1, -1);      // set to full image
        pxip8_testpattern(NULL, ip, 0, 100);    // draw in full image
        pximage_memfree2(ip, NULL);
    }
Errors: Translate Error Code to String --- pxerrnomesg



Summary 
char *pxerrnomesg(errno);
int                 errno;



Description

Any of the ''PXER...'' error codes returned by various library functions, given as the errno argument, is translated and returned as a suitable, concise, NULL terminated error message string. A NULL value is returned if errno can't be an error code; i.e. if errno≥0. A message of ''Unknown error'' is returned if errno is not a recognized ''PXER...'' code.

The ''PXER...'' codes are defined in pxerrno.h, included via xcobj.h. Code should never assume specific values of these error codes, but may presume that all error codes are negative and that 0 and positive values are reserved for nonerror conditions. Thus, if an arbitrary ''library_function'' returns ''PXER...'' codes, the assumptions utilized in: 

int i;
if ((i = library_function(...)) < 0) {
   printf("error %s\n", pxerrnomesg(i));
   return;
}
or in: 
char *cp;
if ((cp = pxerrnomesg(library_function(...)))) {
   printf("error %s\n", cp);
   return;
}
are valid.

Under Windows 95, 98, ME, NT, 2000, XP, Server 2003: The pxerrnomesg is not multi-thread cognizant, as it builds the error message into a single internal buffer; the message referenced by the returned pointer may change.


Returns

A char * to an error message, or (char *) 0.

 

 

 

3. Support Functions - SVOBJ, 4MOBJ, XCOBJ

The following functions are provided in the SVOBJ, 4MOBJ, or XCOBJ libraries, and described in those library's documentation. Their description is included here for convenience.

Get PXIMAGE: Access Imaging Board Buffer --- pxd_defimage
Get PXIMAGE: Access Imaging Board Color Buffer --- pxd_defimagecolor



Summary 
struct pximage * pxd_defimage(buffer, ulx, uly, lrx, lry);
struct pximage * pxd_defimagecolor(buffer, ulx, uly, lrx, lry, colorname);


long                buffer;         // Frame buffer. 0L for current frame buffer
int                 ulx;            // Upper left x coord. of area of interest
int                 uly;            // Upper left y coord. of area of interest
int                 lrx;            // Lower right x coord. exclusive of AOI
int                 lry;            // Lower right y coord. exclusive of AOI


char                *colorname;     // Name of requested color representation



Description

A reference to an image frame buffer and an area of interest within the image is constructed and returned. The pxd_defimage or pxd_defimagecolor function does not have observable effect on any frame buffer. Rather, it is an artifice for defining an image frame buffer and an area of interest for use with other library functions which expect a ''struct pximage *'', and where the programmer prefers to avoid the (explicit) use of structures and pointers. The pxd_defimage or pxd_defimagecolor, with appropriate parameters, can be used to replace any library function argument of the form ''struct pximage *''.

The buffer defines the frame buffer to be accessed, it need not be the frame buffer currently being displayed or digitized. Valid values are between 1 and the return value of inclusive. In addition, use of 0L specifies the current frame buffer.

The ulx and uly respectively define the horizontal (x) and vertical coordinate (y) of the upper left corner of an area of interest in the frame buffer. The lrx and lry respectively define a value one greater than the horizontal and vertical coordinate of the lower right corner of an area of interest in the frame buffer; i.e. an exclusive corner point. Use of: 

pxd_defimage     (1L, 0, 0, pxd_xdim(), pxd_ydim()<<pxd_ylace())
pxd_defimagecolor(1L, 0, 0, pxd_xdim(), pxd_ydim()<<pxd_ylace(), NULL)
specifies the entire image of frame buffer 1, as will: 
pxd_defimage     (1L, 0, 0, -1, -1)
pxd_defimagecolor(1L, 0, 0, -1, -1, NULL)
which is provided for ease of use.

When used with color frame buffers, pxd_defimage provides a reference to the RGB representation of the frame buffer, or if an RGB representation isn't available, to the default, natural representation of the frame buffer. When used with monochrome grey scale frame buffers, pxd_defimage provides a reference to the grey scale image.

For pxd_defimagecolor, the colorname allows selecting a color representation. If colorname=NULL, the frame buffer's natural, internal, color representation is used. Otherwise, colorname is the name of a color representation, as follows: 





colorname   


 Number of Components 


 Color Representation








"RGB"       


 3 


 Red, Green, Blue






"RGBx"      


 4 


 Red, Green, Blue, Pad






"BGR"       


 3 


 Blue, Green, Red (RGB reordered)






"BGRx"      


 4 


 Blue, Green, Red, Pad (RGB reordered)






"YCrCb"     


 3 


 Intensity, Red Chroma, Blue Chroma






"YCrCbX"    


 4 


 Intensity, Red Chroma, Blue Chroma, Pad






"BSH"       


 3 


 Brightness, Saturation, Hue (HSB reordered)






"Grey"      


 1 


 Grey Scale
The colorname is case insensitive. If the colorname is not recognized, or the frame buffer can't be accessed in the requested color representation, the returned ''struct pximage'' references no buffer of 0 dimensions, and can safely, but to no effect, be used by library functions which expect a ''struct pximage *''.


Esoterica. The number of distinct ''struct pximage *'' returned by pxd_defimage or pxd_defimagecolor is limited. The limit supports use of any library function in the manner shown in the example below; other uses of the ''struct pximage *'' provided by pxd_defimage or pxd_defimagecolor should either copy the structure pointed to by pxd_defimage or pxd_defimagecolor, or use pxvid_setpximage or pxvid_setpximage2.


Returns

Effectively returns a ''struct pximage *''.


Example

Consider for example the image processing library function which should be invoked as: 

int pxip8_pixand(abortp, sip, dip, mask);
pxabortfunc_t   **abortp;   // premature termination function, or NULL
struct  pximage *sip;       // source
struct  pximage *dip;       // destination
int     mask;               // and mask
The following code invokes this library function, operating on the upper left quadrant of frame buffer 1 and placing the result in the lower right quadrant of frame buffer 2, without explicitly using structures or pointers. 
int xdim, ydim;


xdim = pxd_xdim();                  // current image dimensions
ydim = pxd_ydim() << pxd_ylace();
pxip8_pixand(NULL,                  // no abort
             pxd_defimage(1L, 0, 0, xdim/2, ydim/2),
             pxd_defimage(2L, xdim/2, ydim/2, xdim, ydim),
             0xC0 );                // chosen mask value
Get PXIMAGE3: Access Imaging Board Buffers --- pxd_defimage3
Get PXIMAGE3: Access Imaging Board Color Buffers --- pxd_defimage3color



Summary 
struct pximage3 * pxd_defimage3(sbuf, ebuf, ulx, uly, lrx, lry);
struct pximage3 * pxd_defimage3color(sbuf, ebuf, ulx, uly, lrx, lry, colorname);


long                sbuf;           // First frame buffer
long                ebuf;           // Last frame buffer, inclusive
int                 ulx;            // Upper left x coord. of area of interest
int                 uly;            // Upper left y coord. of area of interest
int                 lrx;            // Lower right x coord. exclusive of AOI
int                 lry;            // Lower right y coord. exclusive of AOI


char                *colorname;     // Name of requested color representation



Description

A reference to a sequence of image frame buffer and an area of interest within the image sequence is constructed and returned. The pxd_defimage3 or pxd_defimage3color function does not have observable effect on any frame buffer(s). Rather, it is an artifice for defining a sequence of image frame buffers and an area of interest for use with other library functions which expect a ''struct pximage3 *'', and where the programmer prefers to avoid the (explicit) use of structures and pointers. The pxd_defimage3 or pxd_defimage3color, with appropriate parameters, can be used to replace any library function argument of the form ''struct pximage3 *''.

The sbuf and ebuf define the first frame buffer, and last frame buffer, respectively, to be accessed. Valid values are between 1 and the return value of inclusive, with sbuf<=ebuf.

The ulx, uly, lrx, lry, and, optionally, colorname parameters are the same as described for pxd_defimage and pxd_defimagecolor.


Returns

Effectively returns a ''struct pximage3 *''.


Example

Consider for example the image processing library function which saves a sequence of images. It may be invoked as: 

    pxio8_tifwriteseq(NULL, pxd_defimage3(1, pxd_imbufs, 0, 0, -1, -1),
                      NULL, "test.tif", 8, 0, 0, NULL);
to save all image frame buffers.
Construct PXIMAGE: Access Imaging Board Buffer --- pxvid_setpximage
Construct PXIMAGE: Access Imaging Board Buffer --- pxvid_setpximage2



Summary 
int pxvid_setpximage(pximagep, bufstate, framebuffer);
int pxvid_setpximage2(pximagep, bufstate, framebuffer, pixelhint, rsvd1, rsvd2);


struct pximage      *pximagep;      // The pximage to be initialized
int                 bufstate;       // Usually PXSDIGI
pxbuffer_t          framebuffer;    // Frame buffer
int                 pixelhint;      // 0 (default) or PXHINT*, as below
int                 rsvd1;          // Reserved. must be 0
int                 rsvd2;          // Reserved. must be 0



Description

The pximage structure pointed to by pximagep is initialized so that it references the full frame buffer framebuffer on the currently selected imaging board unit(s), where framebuffer is bounded by: 

1 <= framebuffer <= pxvid_xbufs(bufstate|PXSIMOP)
If framebuffer is 0, the current frame buffer is referenced.

The bufstate selects the video state under which the framebuffer is interpreted. Specifically, bufstate defines the partition of frame buffer memory into individual buffers. Use of bufstate=PXSDIGI is suggested for all applications which do not involve multiple (simultaneous) resolutions, or multiple imaging boards. The PXSIMOP adjective (see etc.) is implied as added to the bufstate.

The pixelhint requests the pixel color representation to be accessed by the pximage. 





                


 Color          


 Pixel Component






pixelhint       


 Representation 


 1         


 2          


 3          


 4








0               


 Default        


           


            


            






PXHINTGREY      


 Grey scale     


 Grey level


            


            






PXHINTRGB       


 RGB            


 Red       


 Green      


 Blue       






PXHINTBGR       


 RGB            


 Blue      


 Green      


 Red        






PXHINTRGBX      


 RGB            


 Red       


 Green      


 Blue       


 Pad






PXHINTBGRX      


 RGB            


 Blue      


 Green      


 Red        


 Pad






PXHINTYCRCB     


 YCrCb          


 Intensity 


 Red Chroma 


 Blue Chroma






PXHINTBSH       


 HSB            


 Brightness


 Saturation 


 Hue
Use of pixelhint=0 requests the default, natural, color interpretation of the underlying frame buffer. Other values of pixelhint request and suggest a desired interpretation, but without any guarantee of success; if the desired interpretation isn't available, an alternate is provided. For monochrome frame buffers, the result pximage always accesses monochrome pixels.

The pxvid_setpximage short-form is effectively the same as: 

pxvid_setpximage2(pximagep, bufstate, framebuffer, 0, 0, 0);

The pximage structure is used as a parameter to many library functions to reference an frame buffer and image area of interest on an imaging board unit. The pximage structure is defined via inclusion of xcobj.h in part as: 

struct pximage
{
    struct  pxywindow wind;     // subwindow within imdim
    struct  pxywindow imdim;    // nw.x = nw.y = 0. se.x & se.y are dimensions of image
    . . .
    struct  pximagedata {
         . . .
        int     pixies;         // samples/colors/components per pixel: 1,2,3,...
        int     pixelhint;      // hints on pixel interpretation
        . . .
    } d;
    . . .
};
where pxywindow is: 
struct  pxywindow
{
    struct  pxy     nw;     // north west corner inclusive
    struct  pxy     se;     // south east corner exclusive
};
and where pxy is: 
struct pxy
{
    pxcoord_t   x;
    pxcoord_t   y;
};

After use of pxvid_setpximage, the pximagep->imdim.nw is always x=y=0 and the pximagep->imdim.se are the dimensions of the full image buffer. The pximagep->wind is initially the same as the imdim, but is intended to be modified by the user to define an area of interest. Other members of the pximage structure should not be directly modified.

Use of pxvid_setpximage has no effect on the current video or driver state.


Returns


1
Operation complete. The requested pixelhint has been fulfilled. (Never returned by pxvid_setpximage).

0
Operation complete. The requested pixelhint was 0, or was not fulfilled.

PXERROR
The bufstate is not currently defined; the structure referenced by pximagep is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Internal logic error, notify EPIX, Inc. Technical Support.



See Also

See pxd_defimage or pxd_defimagecolor for an alternate method of obtaining a pximage structure which references an area of interest.


Example

Consider for example the image processing library function which should be invoked as: 

int pxip8_pixand(abortp, sip, dip, mask);
pxabortfunc_t   **abortp;   // premature termination function, or NULL
struct  pximage *sip;       // source
struct  pximage *dip;       // destination
int     mask;               // and mask
The following invokes this library function, operating on the upper left quadrant of frame buffer 1 and placing the result in the lower right quadrant of frame buffer 2. 
struct  pximage src, dst;


pxvid_setpximage(&src, PXSDIGI, 1L);// defines full AOI
pxvid_setpximage(&dst, PXSDIGI, 2L);// ditto, for buffer 2
src.wind.se.x /= 2;                 // reduce lower right
src.wind.se.y /= 2;                 // coordinates to midpoint
dst.wind.nw.x = dst.imdim.se.x/2;   // increase upper left
dst.wind.nw.y = dst.imdim.se.y/2;   // coordinates to midpoint


pxip8_pixand(NULL, &src, &dst, 0xC0);
Construct PXIMAGE3: Access Imaging Board Buffers --- pxvid_setpximage3



Summary 
int pxvid_setpximage3(pximage3p, bufstate, pixelhint, rsvd1, rsvd2);
struct  pximage3    *pximage3p;     // The pximage3 to be set
int                 bufstate;       // Usually PXSDIGI
int                 pixelhint;      // 0 (default) or PXHINT*, as below
int                 rsvd1;          // Reserved. must be 0
int                 rsvd2;          // Reserved. must be 0



Description

The pximage3 structure pointed to by pximage3p is initialized so that it references all frame buffers on the currently selected imaging board unit(s).

The bufstate selects the video state which defines the partition of frame buffer memory into individual frame buffers. Use of bufstate=PXSDIGI is suggested for all applications which do not involve multiple (simultaneous) resolutions, or multiple imaging boards. The PXSIMOP adjective (see etc.) is implied as added to the bufstate.

The pixelhint requests the pixel color representation to be accessed by the pximage3, with values as described under pxvid_setpximage2. Use of pixelhint=0 requests the default, natural, color interpretation of the underlying frame buffer. Other values of pixelhint request and suggest a desired interpretation, but without any guarantee of success; if the desired interpretation isn't available, an alternate is provided. For monochrome frame buffers, the result pximage always accesses monochrome pixels.

The pximage3 structure is used as a parameter to many driver and library functions to reference a sequence of frame buffers and image area of interest on an imaging board unit. The pximage3 structure is defined via inclusion of xcobj.h in part as: 

struct pximage3
{
    struct  pxyzwindow wind;    // subwindow within imdim
    struct  pxyzwindow imdim;   // nw.x = nw.y = nw.z = 0. se.x, se.y, se.z are dimensions
    . . .
    struct  pximagedata {
         . . .
        int     pixies;         // samples/colors/components per pixel: 1,2,3,...
        int     pixelhint;      // hints on pixel interpretation
        . . .
    } d;
    . . .
};
where pxyzwindow is: 
struct  pxyzwindow
{
    struct  pxyz    nw;     // north west corner inclusive
    struct  pxyz    se;     // south east corner exclusive
};
and where pxyz is: 
struct pxyz
{
    pxcoord_t   x;
    pxcoord_t   y;
    pxcoord_t   z;
};

After use of pxvid_setpximage, the pximage3p->imdim.nw is always x=y=z=0, the pximage3p->imdim.se.x and pximage3p->imdim.se.y are the dimensions of an image buffer, and pximage3p->imdim.se.z is the number of image buffers. The pximage3p->wind is initially the same as the imdim, but is intended to be modified by the user to define a subsequence and/or an area of interest. Other members of the pximage3 structure should not be directly modified.


Note: Unlike other usages of ''frame buffer number'', in the XCOBJ ``C'' Library, the pximage3p->imdim.se.z, pximage3p->wind.nw.z, and pximage3p->wind.se.z coordinates are 0 based, not 1 based. Also, in 16 bit environments the ''z'' coordinates are limited to 32767.

Use of pxvid_setpximage3 has no effect on the current video or driver state.


Returns


1
Operation complete. The requested pixelhint has been fulfilled.

0
Operation complete. The requested pixelhint was 0, or was not fulfilled.

PXERROR
The bufstate is not currently defined; the structure referenced by pximage3p is initialized as a NULL image with dimensions of 0.

PXERLOGIC
Internal logic error, notify EPIX, Inc. Technical Support.

 

 

 

4. Support Functions - XCLIB

The following functions are provided in the XCLIB library, and described in that library's documentation. Their description is included here for convenience.

Get PXIMAGE: Access Frame Grabber Image Buffer --- pxd_defineImage
Get PXIMAGE3: Access Frame Grabber Image Buffers --- pxd_defineImage3
Get PXIMAGE: Access Frame Grabber Image Buffer --- pxd_definePximage
Get PXIMAGE3: Access Frame Grabber Image Buffers --- pxd_definePximage3
Get PXIMAGE: Release Access to Frame Grabber Image Buffers --- pxd_definePximageFree
Get PXIMAGE3: Release Access to Frame Grabber Image Buffers --- pxd_definePximage3Free



Summary 
struct pximage  * pxd_defineImage (unitmap, framebuf, ulx, uly, lrx, lry, colorspace);
struct pximage3 * pxd_defineImage3(unitmap, startbuf, endbuf, ulx, uly, lrx, lry, colorspace);


struct pximage  * pxd_definePximage (unitmap, framebuf, ulx, uly, lrx, lry, colorspace);
struct pximage3 * pxd_definePximage3(unitmap, startbuf, endbuf, ulx, uly, lrx, lry, colorspace);
void              pxd_definePximageFree(image);
void              pxd_definePximage3Free(image3)




int                 unitmap;        // Unit selection bit map (1 for single unit)
pxbuffer_t          framebuf;       // Image frame buffer
pxcoord_t           ulx;            // Upper left x coord. of area of interest
pxcoord_t           uly;            // Upper left y coord. of area of interest
pxcoord_t           lrx;            // Lower right x coord. exclusive of AOI
pxcoord_t           lry;            // Lower right y coord. exclusive of AOI
char                *colorspace;    // Name of requested color representation


pxbuffer_t          startbuf;       // First image frame buffer
pxbuffer_t          endbuf;         // Last image frame buffer


struct pximage      image;          // Image access to be released
struct pximage3     image3;         // Image access to be released



Description

A reference to an image frame buffer and an area of interest within the image frame buffer, or a reference to a sequence of image frame buffers and an area of interest within each image frame buffer, is constructed and returned.

These functions are useful for constructing a reference which specifies an image frame buffer and an area of interest for use with other library functions, in particular functions in the PXIPL Image Processing Library, which expect a ''struct pximage *'' or ''struct pximage3 *'', to specify image access, and where the programmer prefers to avoid the (explicit) use of structures and pointers.

The unitmap specifies the single unit to be accessed. For pxd_defineImage, the framebuf, where 1<=framebuf<=pxd_imageZdim(), specifies the image frame buffer to be accessed. For pxd_defineImage3, the startbuf and endbuf, where startbuf<=endbuf, 1<=startbuf<=pxd_imageZdim(), and 1<=endbuf<=pxd_imageZdim(), specify the first and last, inclusively, image frame buffer to be accessed. The ulx and uly respectively specify the horizontal (x) and vertical coordinate (y) of the upper left corner of an area of interest in the frame buffer to be used. The lrx and lry respectively specify a value one greater than the horizontal and vertical coordinate of the lower right corner of an area of interest in the frame buffer (i.e. an exclusive corner point) to be used. The lrx and lry may each be abbreviated to -1 to specify the extreme right horizontal coordinate (i.e. or the extreme bottom vertical coordinate (i.e. respectively.

The colorspace specifies the color space and color component(s) in which the image frame buffer(s) are to be accessed. Valid choices are: 





colorspace  


 Number of  


 Color Representation






            


 Components 








"Default"   


 ? 


 Image frame buffer's default representation,






            


   


 typically Grey, RGB, BGR, or YCrCb.














"Display"   


 ? 


 Optimum representation for display purposes,






            


   


 typically Grey, RGB, BGR, RGBx, or BGRx.














"RGB"       


 3 


 Red, Green, Blue






"RofRGB"    


 1 


 Red






"GofRGB"    


 1 


 Green






"BofRGB"    


 1 


 Blue






"BGR"       


 3 


 Blue, Green, Red (RGB reordered)






"BofBGR"    


 1 


 Blue






"GofBGR"    


 1 


 Green






"RofBGR"    


 1 


 Red






"BSH"       


 3 


 Brightness, Saturation, Hue (HSB reordered)






"BofBSH"    


 1 


 Brightness






"SofBSH"    


 1 


 Saturation






"HofBSH"    


 1 


 Hue






"RGBx"      


 4 


 Red, Green, Blue, Pad






"RofRGBx"   


 1 


 Red






"GofRGBx"   


 1 


 Green






"BofRGBx"   


 1 


 Blue






"BGRx"      


 4 


 Blue, Green, Red, Pad (RGB reordered)






"BofBGRx"   


 1 


 Blue






"GofBGRx"   


 1 


 Green






"RofBGRx"   


 1 


 Red






"Grey"      


 1 


 Grey Scale






"GREY"      


 1 


 Grey Scale (alternate spelling for "Grey")






"Gray"      


 1 


 Grey Scale (alternate spelling for "Grey")






"GRAY"      


 1 


 Grey Scale (alternate spelling for "Grey")






"YCrCb"     


 3 


 Intensity, Red Chroma, Blue Chroma






"YofYCrCb"  


 1 


 Intensity






"RofYCrCb"  


 1 


 Red Chroma






"BofYCrCb"  


 1 


 Blue Chroma






"YCrCbX"    


 4 


 Intensity, Red Chroma, Blue Chroma, Pad






"YofYCrCbX" 


 1 


 Intensity






"RofYCrCbX" 


 1 


 Red Chroma






"BofYCrCbX" 


 1 


 Blue Chroma






"Bayer"     


 1 


 Raw Bayer Pattern Values






"CbYCrY"    


 2 


 UYVY (Blue & Intensity, Red & Intensity)






"CMY"       


 3 


 Cyan, Magenta, Yellow






"CofCMY"    


 1 


 Cyan






"MofCMY"    


 1 


 Magenta






"YofCMY"    


 1 


 Yellow

The ''BGRx'' selection, when read into a ''uchar'' buffer on Intel machines with little-endian architecture (i.e. least significant byte of multi-byte word has lowest address), with the buffer typecast to the Windows ''COLORREF'' type, results in pixels that are compatible with Windows' RGB() data type.

The ''Bayer'' selection is available only in conjunction with cameras that actually output raw Bayer pattern values, and where the frame grabber library would otherwise be responsible for converting the values to RGB(x) or BGR(x).

The ''CbYCrY'' selection is available only in conjunction with frame grabbers that actually capture CbYCrY (UYVY) values, and where the frame grabber library would otherwise be responsible for converting the values to RGB(x), BGR(x), or YCrCb.

The ''Display'' selection chooses an optimum color representation for use with pxio8_GDIDisplay and similar display functions (in the PXIPL Image Processing Library), and is dependent upon the camera, video format configuration, and current graphics display system.

For ease of use, the pxd_defineImage and pxd_defineImage3 return ''struct pximage *'' or ''struct pximage3 *'' that need not (and must not) be free'ed. Instead, pxd_defineImage and pxd_defineImage3 provide references to a limited number of statically allocated structures. The limit is sufficient to support the convenient use of any library function in the manner shown in the example below; invoking pxd_defineImage or pxd_defineImage3 as ''in-line'' functions. The returned ''struct pximage *'' or ''struct pximage3 *'' should not be assigned to a pointer variable and used repeatedly. Nor should pxd_defineImage or pxd_defineImage3 be used from a multi-threaded environment, unless the call to pxd_defineImage or pxd_defineImage3 and the use of the resulting ''struct pximage *'' or ''struct pximage3 *'' are both protected against other threads invoking pxd_defineImage or pxd_defineImage3.

In contrast, the pxd_definePximage and pxd_definePximage3 return a ''struct pximage *'' or ''struct pximage3 *'' that after use must be released via pxd_definePximageFree or pxd_definePximage3Free, respectively. The pxd_definePximage and pxd_definePximage3 alternatives are appropriate when accessing the library from a multi-threaded environment, or when the programmer chooses to assign the return values to a pointer variable for repeated use. The pxd_definePximage and pxd_definePximage3 creates a copy of the image access structures in malloc'ed memory, but does not copy the image contents; each use of the returned ''struct pximage *'' or ''struct pximage3 *'' accesses the current contents of the frame buffer.


Returns

As described above.

Returns NULL if the library is not open for use, if the colorspace or other parameter is invalid, or for pxd_definePximage and pxd_definePximage3 if memory could not be malloc'ed.


Example

Consider the typical image processing library function which should be invoked as: 

int pxip8_pixand(abortp, sip, dip, mask);
pxabortfunc_t   **abortp;   // premature termination function, or NULL
struct  pximage *sip;       // source
struct  pximage *dip;       // destination
int     mask;               // and mask
The following invokes this library function, operating on the upper left quadrant of image frame buffer 1 and placing the result in the lower right quadrant of image frame buffer 2, without explicitly using structures or pointers. 
int xdim, ydim;


xdim = pxd_imageXdim();
ydim = pxd_imageYdim();
pxip8_pixand(NULL,                  // no abort
             pxd_defineImage(1, 1, 0,      0,      xdim/2, ydim/2, "Default"),
             pxd_defineImage(1, 2, xdim/2, ydim/2, xdim,   ydim,   "Default"),
             0xC0 );                // chosen mask value

Consider the typical image processing library function which saves a sequence of images. It may be invoked as: 

pxio8_tifwriteseq(NULL,
                  pxd_defineImage3(1, 1, pxd_imageZdim(), 0, 0, -1, -1, "Default"),
                  NULL, "test.tif", 8, 0, 0, NULL);
to save the entire AOI of all image frame buffers.
Obtain pximage Access into Frame Grabber Memory --- ::pxlib.initPximage
Obtain pximage3 Access into Frame Grabber Memory --- ::pxlib.initPximage3
Obtain Filtered pximage Access into Frame Grabber Memory --- ::pxlib.initFilteredPximage
Obtain Filtered pximage3 Access into Frame Grabber Memory --- ::pxlib.initFilteredPximage3



Summary 
int (pxlib.initPximage)         (&pxlib, unitmap, ip,  ipcnt, colorhint, altspace, stateid,
                                 framebuf, mbpcihint);
int (pxlib.initPximage3)        (&pxlib, unitmap, ip3, ipcnt, colorhint, altspace, stateid,
                                 unused,   mbpcihint);
int (pxlib.initFilteredPximage) (&pxlib, unitmap, ip,  ipcnt, colorhint, altspace, stateid,
                                 framebuf, mbpcihint, colormap);
int (pxlib.initFilteredPximage3)(&pxlib, unitmap, ip3, ipcnt, colorhint, altspace, stateid,
                                 unused,   mbpcihint, colormap);


struct pxlibservice pxlib;          // A pxlibservice instance
int                 unitmap;        // Unit selection bit map (1 for single unit)
struct pximage      ip[];           // Array of pximage's
struct pximage      ip3[];          // Array of pximage3's
int                 ipcnt;          // Dimension of ip or ip3
int                 colorhint;      // Requested color representation
uint                altspace;       // 0: image frame buffer memory
int                 stateid;        // Video state id
pxbuffer_t          framebuf;       // Image frame buffer
int                 mbpcihint;      // Reserved, should be 0
int                 colormap;       // Pixel value component selection



Description

A pximage or pximage3 is initialized so as to provide access to the frame grabber's frame buffers, or to other memory associated with the frame grabber. The ::initPximage provides access to a single image frame buffers, in the color space(s) directly obtainable from the image frame buffer. The ::initPximage3 provides access to a sequence of all image frame buffers, in the color space(s) directly obtainable from the image frame buffer. The ::initFilteredPximage and ::initFilteredPximage3 are similar, but initializes additional conversions, as needed, to provide any supported color space interpretation of the image frame buffers.

These services initialize the pximage or pximage3 structures provided; thereafter these structures can be used to access pximage or pximage3 services.

The unitmap specifies the single unit to which access is to be provided. The stateid specifies a video state id previously defined by against which the framebuf is interpreted.

The ip or ip3 specify instances of an array of pximage or pximage3 structures; the ipcnt specifies the number of structures provided. In the worst case, ::initPximage and ::initPximage3 may require ipcnt=PXMAX_IRBGF, ::initFilteredPximage and ::initFilteredPximage3 may require ipcnt=PXMAX_FIRBGF.

The colorhint is a PXHINT... type value specifying the desired color space. The colorhint may not be available; the ip or ip3 may be initialized so as to access the image frame buffers with a different color space. More colorhint's are available through use of ::initFilteredPximage and ::initFilteredPximage3 instead of ::initPximage and ::initPximage3.

For ::initFilteredPximage and ::initFilteredPximage3, the colormap selects which color component values are to be accessed. The colormap is a bit-map; the i'th bit selects the i'th color component.

If altspace=0, access is provided to image frame buffers. For PIXCI® A, CL1, CL2, CL3SD, D, D24, D32, D2X, D3X, D3XE, E1, E1DB, E4, E4DB, E4G2-2F, E4G2-4B, E4G2-F2B, E4TX2-2F, E4TX2-4B, E4TX2-F2B, E8, E8CAM, E8DB, e104x4-2f, e104x4-4b, e104x4-f2b, EB1, EB1G2, EB1-PoCL, EB1G2-PoCL, EB1mini, miniH2B, miniH2F, miniH2x4F, mf2280, EC1, ECB1, ECB1-34, ECB2, EL1, EL1DB, ELS2, SI, SI1, SI2, and SI4 frame grabbers, using altspace=(('t'<<8)|'s') provides access to the four byte video field counter attached to each captured frame buffer.


Returns


≥1
Operation complete. The return value indicates the number of pximage or pximage3 structures used.

PXERROR
Invalid parameters.

PXERMORESPACE
There are insufficient pximage or pximage3 structures to provide access.

PXER...
Other error codes as appropriate.

 

 

 

5. Contrast Enhancement & Threshold

Contrast Enhance --- pxip8_pixcontrast



Summary 
int pxip8_pixcontrast(abortp, sip, dip, lowbound, highbound);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                lowbound;       // lowest useful grey level
uint                highbound;      // highest useful grey level



Description

The contrast of the image referenced by sip is enhanced, and the modified image put in the image referenced by dip. The range of pixel values from lowbound through highbound are stretched into the range of 0 through the maximum pixel value (255 for 8 bit pixels). Pixel values less than lowbound or greater than highbound are set to 0 and the maximum pixel value, respectively. Specifically, the numeric value of each pixel of the source image referenced by sip is modified by (assuming 8 bit pixels): 

if (pixel_value <= lowbound)
   result = 0;
else if (pixel_value > highbound)
   result = 255;
else
   result = ((pixel_value - lowbound)*255) / (highbound - lowbound);
and the result placed in the corresponding pixel of the destination image referenced by dip.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Contrast Enhance Real Pixels --- pxipf_pixcontrast



Summary 
int pxipf_pixcontrast(abortp, sip, dip, lowbound, highbound);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
double              lowbound;       // lowest useful grey level
double              highbound;      // highest useful grey level



Description

The contrast of the image referenced by sip is enhanced, and the modified image put in the image referenced by dip. The range of pixel values from lowbound through highbound are stretched into the range of the 0 and the maximum pixel value. Pixel values less than lowbound or greater than highbound are set to 0 and the maximum pixel value, respectively. Specifically, the numeric value of each pixel of the source image referenced by sip is modified by: 

if (pixel_value <= lowbound)
   result = 0;
else if (pixel_value > highbound)
   result = max_pixel_value;
else
   result = ((pixel_value - lowbound)*max_pixel_value) / (highbound - lowbound);
and the result placed in the corresponding pixel of the destination image referenced by dip.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of float pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Contrast Enhance By Percentile --- pxip8_pixcontrastperc



Summary 
int pxip8_pixcontrastperc(abortp, sip, dip, lowperc, highperc, lobp, hibp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                lowperc;        // lowest useful percentile
uint                highperc;       // highest useful percentile
uint                *lobp;          // returned !
uint                *hibp;          // returned !



Description

The contrast of the image referenced by sip is enhanced, and the modified image put in the image referenced by dip. The enhancement is identical to that performed by pxip8_pixcontrast, however the contrast range is specified by the histogram percentiles; 0<=lowperc<highperc<=100. The pixel value at the lowperc percentile, and the pixel value at the highperc percentile, respectively form the lowbound and highbound of the operation defined for pxip8_pixcontrast. These pixel values are also ''returned'', the lowbound at *lobp and the highbound at *hibp. Either lobp or hibp may be NULL, no value is returned to the NULL address.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

pxip8_pixcontrast.

Gamma Correction --- pxip8_pixgamma



Summary 
int pxip8_pixgamma(abortp, sip, dip, gamma);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
double              gamma;          // gamma value



Description

The pixels of the image referenced by sip are ''gamma corrected'' and the modified image put in the image referenced by dip.

A gamma correction nonlinearly scales each pixel according to the specified gamma parameter. A gamma of 1.00 has no effect, a gamma less than 1.00 brightens the image, a gamma greater than 1.00 darkens the image. If correcting for a camera with known gamma, use the inverse of the camera's gamma, such as gamma=1.43 to correct for a camera with stated gamma of 0.70.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Threshold Pixel Values --- pxip8_pixthreshold
Threshold Pixel Values --- pxip8_pixthreshold2



Summary 
int pxip8_pixthreshold(abortp,sip,dip,lowbound,highbound,newvalue);
int pxip8_pixthreshold2(abortp,sip,dip,lowbound,highbound,newvalue,altvalue);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                lowbound;       // pixel w. value between
uint                highbound;      // low/highbounds, inclusive,
uint                newvalue;       // set to newvalue
uint                altvalue;       // otherwise to altvalue



Description

The numeric value of each pixel of the source image referenced by sip is compared to the lowbound and highbound, a new pixel value assigned, and the result placed in the corresponding pixel of the destination image referenced by dip. For color pixels, each component (i.e. ''pixie'') is independently compared to lowbound and highbound and a new value assigned.

For pxip8_pixthreshold, pixel values that are between lowbound and highbound (inclusive) are replaced with newvalue, otherwise the pixel value is unchanged; i.e. 

if (lowbound <= pixel_value && pixel_value <= highbound)
    result = newvalue;
else
    result = pixel_value
For pxip8_pixthreshold2, pixel values that are between lowbound and highbound (inclusive) are replaced with newvalue, otherwise the pixel is replaced with altvalue; i.e. 
if (lowbound <= pixel_value && pixel_value <= highbound)
    result = newvalue;
else
    result = altvalue;

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Threshold Pixel Values --- pxip8_pixthreshold3



Summary 
int pxip8_pixthreshold3(abortp, sip, dip, lowbound, highbound, invalue, outvalue, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                lowbound[];     // pixel w. value between
uint                highbound[];    // low/highbounds, inclusive,
uint                invalue[];      // set to invalue (if not NULL)
uint                outvalue[];     // otherwise to outvalue (if not NULL)
int                 rsvd;           // reserved. should be 0



Description

The numeric value of each pixel of the source image referenced by sip is compared to the lowbound and highbound; if between lowbound and highbound, inclusive, the invalue, otherwise the outvalue, is placed in the corresponding pixel of the destination image referenced by dip. Either the invalue or outvalue may be NULL (but not both); the original pixel value is used in place of the NULL invalue or outvalue.

For monochrome imagery, lowbound[0] and highbound[0] specifies the grey level bounds, ranging from 0 to the maximum pixel component value (255 for 8 bit pixels); invalue[0] and outvalue[0] specifies the new pixel values.

For color pixels, the lowbound, highbound, invalue, and outvalue are each dimensioned equal to the number of pixel components (i.e. ''pixies'') of sip and dip; each component (i.e. ''pixie'') is compared to the corresponding indexed value of lowbound and highbound.

The sip may be color and the dip monochrome; the lowbound and highbound are each dimensioned equal to the number of pixel components (i.e. ''pixies'') of sip; the invalue[0] and outvalue[0] specify the new pixel values. Neither invalue nor outvalue may be NULL.

The lowbound value(s) may be greater than the highbound value(s); the comparison is modified by (1) Swapping (a copy of) the values, and (2) Complementing the sense of the comparison. For example, if: 

    lowbound[0] = 10;   highbound[0] = 20;
    lowbound[1] = 200;  highbound[1] = 100;
    lowbound[2] = 210;  highbound[2] = 220;
The comparison performed is: 
    if ( (10  <= pixie[0] && pixie[0] <= 20)
     && !(100 <= pixie[1] && pixie[1] <= 200)
     &&  (210 <= pixie[2] && pixie[2] <= 220) )
        Assign invalue[]
    else
        Assign outvalue[]

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3 color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or 3 color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

6. Simple Pixel Operations

Set Pixel Values --- pxip8_pixset



Summary 
int pxip8_pixset(abortp, dip, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *dip;           // destination
uint32              value;          // pixel value



Description

The numeric value of each pixel of the destination image referenced by dip is set to value. For color pixels, each component (i.e. ''pixie'') of the pixel is set to value.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Set Color Pixel Values --- pxip8_pixset3



Summary 
int pxip8_pixset3(abortp, dip, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *dip;           // destination
uint                value[];        // pixel value(s)



Description

The numeric value of the i'th component of each pixel of the destination image referenced by dip is set to values[i].

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Set Real Pixel Values --- pxipf_pixset3



Summary 
int pxipf_pixset3(abortp, dip, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *dip;           // destination
double              value[];        // pixel value(s)



Description

The numeric value of the i'th component of each pixel of the destination image referenced by dip is set to values[i].

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of float pixels.



Returns

0

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
AND Pixels with Mask --- pxip8_pixand
OR Pixels with Mask --- pxip8_pixor
XOR Pixels with Mask --- pxip8_pixxor
Complement Pixel Values --- pxip8_pixneg
Left Shift Pixel Values --- pxip8_pixshl
Right Shift Pixel Values --- pxip8_pixshr
Left Rotate Pixel Values --- pxip8_pixrotl
Right Rotate Pixel Values --- pxip8_pixrotr
Bit Reverse Pixel Values --- pxip8_pixreverse
MSB Extend Pixel Values --- pxip8_pixmsb
Gray Code/Decode Pixel Values --- pxip8_pixgraycode
Set Pixel Components to Minimum --- pxip8_pixiemin
Set Pixel Components to Maximum --- pxip8_pixiemax
Set Pixel Components to Median --- pxip8_pixieave
Copy Pixel Components --- pxip8_pixiecopy



Summary 
int pxip8_pixand(abortp, sip, dip, mask);
int pxip8_pixor(abortp, sip, dip, mask);
int pxip8_pixxor(abortp, sip, dip, mask);
int pxip8_pixneg(abortp, sip, dip);
int pxip8_pixshl(abortp, sip, dip, cnt);
int pxip8_pixshr(abortp, sip, dip, cnt);
int pxip8_pixrotl(abortp, sip, dip, cnt);
int pxip8_pixrotr(abortp, sip, dip, cnt);
int pxip8_pixreverse(abortp, sip, dip, rsvd);
int pxip8_pixmsb(abortp, sip, dip);
int pxip8_pixgraycode(abortp, sip, dip, mode);
int pxip8_pixiemin(abortp, sip, dip);
int pxip8_pixiemax(abortp, sip, dip);
int pxip8_pixieave(abortp, sip, dip);
int pxip8_pixiecopy(abortp, sip, dip, pixiesrc, pixiedstmap);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                mask;           // and, or, xor mask
uint                cnt;            // shift/rotate count
uint                pixiesrc;       // index of source pixie
uint                pixiedstmap;    // bit map of destination pixies
int                 rsvd;           // reserved. should be 0
int                 mode;           // see below



Description

The numeric value of each pixel of the source image referenced by sip is numerically modified and placed in the corresponding pixel of the destination image referenced by dip. The pxip8_pixand performs a bit-wise, boolean AND of the pixel value's binary representation with the numeric mask. The pxip8_pixor performs a bit-wise, boolean INCLUSIVE-OR of the pixel value's binary representation with the numeric mask. The pxip8_pixxor performs a bit-wise, boolean EXCLUSIVE-OR of the pixel value's binary representation with the numeric mask. The pxip8_pixneg performs a subtraction of each pixel value from the maximum pixel value (255 for 8 bit pixels), effectively forming the ''negative'' of the image. The pxip8_pixshl performs a left-shift of the pixel value's binary representation by cnt bits. The pxip8_pixshr performs a right-shift of the pixel value's binary representation by cnt bits. The pxip8_pixrotl performs a left-rotate of the pixel value's binary representation by cnt bits. The pxip8_pixrotr performs a right-rotate of the pixel value's binary representation by cnt bits. The pxip8_pixreverse performs a reversal of the bits of the pixel value's binary representation. The pxip8_pixmsb performs an extension of the most significant bit through all bit positions of the pixel value's binary representation.

The pxip8_pixgraycode with mode=0 converts binary pixel values to Gray Code, a reflected code in which each two successive values differs by one bit. The pxip8_pixgraycode with mode=1 performs the inverse conversion.

For operations above applied to color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The pxip8_pixiemin replaces each component of each color pixel with the minimum value of the pixel's components. The pxip8_pixiemax operation replaces each component of each color pixel with the maximum value of the pixel's components. The pxip8_pixieave operation replaces each component of each color pixel with the mean, or average, value of the pixel's components. The pxip8_pixicopy operation replaces one or more components of each color pixel with the value of one of the pixel's components; the pixiesrc specifies the index of the pixel's components to copied, the pixiedstmap bitmap specifies one or more of the pixel's components to replaced. The pxip8_pixiemin, pxip8_pixiemax, pxip8_pixieave, and pxip8_pixiecopy have no effect when used on a monochrome image.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. The pxip8_pixneg, pxip8_pixiemin, pxip8_pixiemax, and pxip8_pixieave, also supports monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Scale Pixel Values --- pxip8_pixscale
Offset Pixel Values --- pxip8_pixadd
Scale Pixel Values --- pxipf_pixscale
Offset Pixel Values --- pxipf_pixadd



Summary 
int pxip8_pixscale(abortp, sip, dip, numerator, denominator);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                numerator;
uint                denominator;


int pxip8_pixadd(abortp, sip, dip, constant, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 constant;       // value added
int                 mode;           // 2: bounded by max pixel value and 0,
                                    // ?: modulo pixel word size


int pxipf_pixadd(abortp, sip, dip, constant, mode);
int pxipf_pixscale(abortp, sip, dip, constant, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
double              constant;       // value
int                 mode;           // reserved. should be 2



Description

The numeric value of each pixel of the source image referenced by sip is numerically modified and placed in the corresponding pixel of the destination image referenced by dip.

The pxip8_pixscale scales each source pixel by multiplication with the factor numerator/denominator, with the integer result placed in the corresponding destination pixel. Results are bounded to the maximum pixel value (255 for 8 bit pixels). Use of numerator=1 and denominator=1 (among other values) effectively copies the image without modification. If denominator=0, the destination pixels are set to the maximum pixel value.

The pxip8_pixadd modifies each source pixel by addition with the signed constant, with the integer result placed in the corresponding destination pixel. If mode=2, results are bounded to the minimum and maximum pixel value (0 and 255, respectively, for 8 bit pixels). Otherwise, the result is truncated by overflow of the pixel word size.

The pxipf_pixadd modifies each source pixel by addition with the signed constant, with the result placed in the corresponding destination pixel. The pxipf_pixscale modifies each source pixel by multiplication with the signed constant, with the result placed in the corresponding destination pixel. Results are bounded to the minimum and maximum pixel value.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
For pxip8_pixscale and pxip8_pixadd: Monochrome and color, of unsigned integer pixels, of 1 to 32 bits. For pxipf_pixadd and pxipf_pixscale: Monochrome and color, of float or double pixels.

COC40
For pxip8_pixscale and pxip8_pixadd: Monochrome and color, of uchar pixels, of 1 to 16 bits.

The pxip8_pixscale also supports ulong pixels for sip with more bits than for dip, allowing reduction of 32 bit summations.


Returns


0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Map Uchar Pixel Values --- pxip8_pixmap
Map uint16 Pixel Values --- pxip8_pixmaps
Map uint32 Pixel Values --- pxip8_pixmapl
Map Pixel Values --- pxip8_pixmaplut



Summary 
int pxip8_pixmap(abortp, sip, dip, ucharmap, nmap);
int pxip8_pixmaps(abortp, sip, dip, uint16map, nmap);
int pxip8_pixmapl(abortp, sip, dip, uint32map, nmap);
int pxip8_pixmaplut(abortp, lutip, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uchar               *ucharmap;      // lookup table
uint16              *uint16map;     // lookup table
uint32              *uint32map;     // lookup table
size_t              nmap;           // dimension of ..map[]
struct  pximage     *lutip;         // lookup table(s)



Description

The numeric value of each pixel of the source image referenced by sip is used as an index into a lookup table, and the indexed value placed in the corresponding pixel of the destination image referenced by dip.

The pxip8_pixmap operates on uchar pixels, using ucharmap[0] through ucharmap[2bitsperpixie-1] as the lookup table. The pxip8_pixmaps operates on uint16 pixels, using uint16map[0] through uint16map[2bitsperpixie-1] as the lookup table. The pxip8_pixmapl operates on uint32 pixels, using uint32map[0] through uint32map[2bitsperpixie-1] as the lookup table. For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above, using the same lookup table.

The pxip8_pixmaplut operates on uchar, uint16, or uint32 pixels, using the contents of the image referenced by lutip as the lookup table. The lutip should be of the same data type and have the same number of pixies as sip and dip, with a dimension of (2bitsperpixiex1) (e.g. 256x1 for 8 bit pixies). For color pixels, each pixie of sip is mapped through an individual lookup table composed of the corresponding pixies of lutip.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip. The image referenced by lutip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome and color: for pxip8_pixmaplut; for pxip8_pixmap, of uchar pixels, of 1 to 8 bits; for pxip8_pixmaps, of uint16 pixels, of 1 to 16 bits; for pxip8_pixmapl, of uint32 pixels, of 1 to 32 bits (subject to available memory for the uint32map table).

COC40
Monochrome and color: for pxip8_pixmap and pxip8_pixmaplut, monochrome, of uchar pixels, of 1 to 32 bits. The pxip8_pixmaps and pxip8_pixmapl are neither needed nor available.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

The pxip8_pixmap is used to ''bin'' pixel values in the first image frame buffer. Pixels with values from 0 through 15 are set to 0, from 16 to 31 set to 16, etc. 

uchar   map[256];
int     i;


/*
 * Set up the pixel translation map. The set up code is simplified
 * by taking advantage of bin levels that are powers of two;
 * i.e. the low four bits of each pixel value are set to 0.
 */
for (i = 0; i < 256; i++)
    map[i] = i & ~0xF


pxip8_pixmap(NULL,
             #if 1       // w. XCLIB
               pxd_defineImage(1,1,0,0,-1,-1,"Default"),
               pxd_defineImage(1,1,0,0,-1,-1,"Default"),
             #else       // w. SVOBJ,4MOBJ,XCOBJ
               pxd_defimage(1, 0, 0, -1, -1),
               pxd_defimage(1, 0, 0, -1, -1),
             #endif
             map, 256);

 

 

 

7. Histograms & Computations

Compute Histogram Statistics --- pxip8_histstat
Compute Histogram Statistics --- pxip8_histstat2
Compute Histogram Statistics w. Interpretation --- pxip8_histstatf
Compute Histogram Statistics w. Interpretation --- pxip8_histstat2f



Summary 
int pxip8_histstat(hp, sp, pp);
int pxip8_histstat2(ip, count, ncount, sp, pp);
int pxip8_histstatf(hp, zifunc, funcrefp, sp, pp);
int pxip8_histstat2f(ip, count, ncount, zifunc, funcrefp, sp, pp);


struct  pxip8histab   *hp;          // one form of input
struct  pxip8histstat *sp;          // output or NULL
struct  pxip8histperc *pp;          // output or NULL
double      (_cfunfcc *mapzifunc)(void *refp,struct pxyd *xyp,double z);
                                    // map pixel values. _cfunfcc is a predefined function modifier
void                  *mapfuncrefp; // arg for mapzifunc


pxim2size_t           *count;       // alternate form of input
size_t                ncount;       // dimension of alternate form of input
struct  pximage       *ip;          // pixel size of alternate form of input






#define PXIP8HISTPERC   101
struct pxip8histperc    // percentile record
{
    uint  value[PXIP8HISTPERC];
};
struct pxip8histstat    // histogram statistics
{
                    //                  Fi is frequency:
                    //                  Xi is variate:
    ulong   nnn;    // # of pixels      sum of Fi
    double  sum;    // sum of pixels    sum of Fi * Xi
    double  sum2;   // sum of pixels^2  sum of Fi * Xi * Xi
    ulong   maxn;   // max count        max Fi
    ulong   minn;   // min count        min Fi
    uint    maxv;   // pixel of maxn    Xi of maxn's Fi
    uint    minv;   // pixel of minn    Xi of minn's Fi
    uint    low;    // lowest pixel     lowest Xi w. nonzero Fi
    uint    high;   // highest pixel    highest Xi w. nonzero Fi
    /*
     * Derived values
     */
    float   mom1;   // first moment
    float   var;    // variance
    float   stddev; // standard deviation
    float   rms;    // rms value
};



Description

Given an image's histogram in the pxip8_histab structure referenced by hp, previously computed by pxip8_histab, or given an image's histogram in the array referenced by count previously computed by pxip8_histab2, several statistics on the image's histogram are computed and returned in the pxip8histstat and pxip8histperc structures referenced by sp and pp, respectively.

The sp->nnn is the total number of pixels, sp->sum the sum of pixel values, and sp->sum2 the sum of pixel values squared. The sp->maxv is the pixel value which occurs most frequently, and sp->maxn is that pixel's frequency of occurrence. Similarly, sp->minv is the pixel value which occurs least frequently, and sp->minn is that pixel's frequency of occurrence. The sp->mom1 is the mean of pixel values, sp->var the variance of pixel values, sp->stddev the standard deviation of pixel values, sp->rms the r.m.s of pixel values. The sp->low is the lowest pixel value with nonzero frequency, and sp->high is the highest pixel value with nonzero frequency.

The pp->value array provides pixel values which separate the pixel percentiles, within the limit of integer values. Thus, approximately equal number of pixels are above and are below the pixel value in pp->value[50].

A NULL sp or pp is ignored; the corresponding statistics are not computed.

The pxip8_histstat and pxip8_histstat2 compute the statistics based upon the binary value of each pixel. The pxip8_histstatf and pxip8_histstat2f allows computing statistics based upon an interpretation of pixel value, such as intensity, density, thickness, etc. The mapzifunc should reference a caller provided function which maps a pixel value into the desired interpretation. The mapzifunc is invoked with three parameters: (1) The mapfuncrefp as passed to pxip8_histstatf, (2) A NULL pointer, and (3) A pixel value (0 to the maximum pixel value). The mapzifunc returns an arbitrary value corresponding to the pixel value's interpretation.

For pxip8_histstat2 and pxip8_histstat2f, if the provided histogram was binned, i.e. the dimension of count smaller than the number of possible pixel values, the accuracy of the statistics returned by pxip8_histstat2 and pxip8_histstat2f will, necessarily, be reduced.


Returns


0
Operation complete.



Supports

80x86
Any pixel type and precision.

COC40
Any pixel type and precision..



See Also

See pxip8_histab and pxip8_histab2. For use with pxip8_histstatf, see pxip_calibxyhv and pxip_calibzi.


Example 

struct  pxip8histab   histab;
struct  pxip8histstat histstat;
struct  pxip8histperc histperc;
int     i;


/*
 * Do histogram & statistics on the first image frame buffer.
 */
i = pxip8_histab(NULL,
                 #if 1       // w. XCLIB
                   pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                 #else       // w. SVOBJ,4MOBJ,XCOBJ
                   pxd_defimage(1,0,0,-1,-1),
                 #endif
                 &histab);
if (i < 0) {
    printf("error\n");
} else {
    pxip8_histstat(&histab, &histstat, &histperc);
    printf("Lower right quadrant mean: %f, variance %f\n",
            histstat.mom1, histstat.var);
}

To compute statistics using pixel value interpretation, an appropriate mapping function is defined. The following implements a logarithmic mapping. 

double _cfunfcc density(void *p, struct pxyd *xyp, double i)
{
    return(log(i+.01));
}
    ...
{
    i = pxip8_histab(NULL,
                     #if 1       // w. XCLIB
                       pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                     #else       // w. SVOBJ,4MOBJ,XCOBJ
                       pxd_defimage(1,0,0,-1,-1),
                     #endif
                     &histab);
    if (i < 0) {
        printf("error\n");
    } else {
        pxip8_histstatf(&histab, density, NULL, &histstat, &histperc);
        printf("Lower right quadrant mean: %f, variance %f\n",
                histstat.mom1, histstat.var);
    }
}
Compute Histogram --- pxip8_histab



Summary 
int pxip8_histab(abortp, sip, hp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source image
struct  pxip8histab *hp;            // result table




struct  pxip8histab
{
    int         histpix;                // always 256 for 8 bit pixels
    pxim2size_t count[256];
};



Description

The image referenced by sip is scanned and a histogram of pixel values constructed. The histogram is returned in the pxip8histab structure referenced by hp.

The number of occurrences of each of the 256 possible pixel values are tallied in hp->count. The hp->histpix is always set to 256.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently scanned and tallied. The sum of the tallies is the number of pixels in the image referenced by sip times the number of pixies per pixel.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of uchar pixels, of 1 to 8 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 8 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Tabulated Histogram --- pxip8_histab2
Compute Tabulated Histogram --- pxip8_histab3



Summary 
int pxip8_histab2(abortp, sip, count, ncount);
int pxip8_histab3(abortp, sip, count, ncount, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source image
pxim2size_t         *count;         // result count table
size_t              ncount;         // dimension of count[]
int                 mode;           // options



Description

The image referenced by sip is scanned and a histogram of pixel values constructed. The histogram is returned in the array referenced by count, of dimension ncount. The ncount must be a power of 2.

If ncount is equal to, or larger, than the number of possible pixel values, each pixel is tallied in count[pixel]. Alternately, ncount may be less than the number of possible pixel values; pixel values are tallied into the corresponding bin of count. For example, if ncount is ¼ the number of possible pixel values, then each pixel is tallied in count[pixel/4].

For color pixels, all components (i.e. ''pixies'') of the pixel are scanned and tallied. The sum of the tallies is the number of pixels in the image referenced by sip times the number of pixies per pixel. For example, the histogram of two RGB pixels with values: 

    (1, 2, 3)
    (2, 3, 4)
would result in: 
    count[0] = 0
    count[1] = 1
    count[2] = 2
    count[3] = 2
    count[4] = 1
    count[5] = 0
        ...

For pxip8_histab3, if mode&0x100, the count array is not zeroed before tallying, allowing a second tally to be efficiently added to the first.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Tabulated Histogram of Differences --- pxip8_histabpair



Summary 
int pxip8_histabpair(abortp, s1p, s2p, count, ncount, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source image A
struct  pximage     *s2p;           // source image B
pxim2size_t         *count;         // result count table
size_t              ncount;         // size of count[]
int                 mode;           // 'd'    : A-B
                                    // 'd'^'|': abs(A-B)
                                    // 'd'^'2': (A-B)*(A-B)



Description

The images referenced by s1p and s2p are scanned and a histogram of the differences of corresponding pixel values constructed. The histogram is returned in the array referenced by count, of dimension ncount.

If mode='d', the values of s1p minus the corresponding pixel values of s2p are tabulated. The ncount must be 

    (1<<b)*2-1
where b is the number of bits per pixel component. The values returned in count correspond to differences: 
    -(1<<b)+1, -(1<<b)+2, ..., -1, 0, 1, ..., (1<<b)-2, (1<<b)-1
For example, for 8 bit pixels the ncount must be 511 and the values returned in count correspond to differences: 
    -255, -254, ..., -1, 0, 1, ..., 254, 255

If mode='d'^'|', the absolute value of pixel values of s1p minus the corresponding pixel values of s2p are tabulated. The ncount must be 

    (1<<b)
where b is the number of bits per pixel component.

If mode='d'^'2', the square of pixel values of s1p minus the corresponding pixel values of s2p are tabulated. The ncount must be 

    ((1<<b)-1)*((1<<b)-1)+1
where b is the number of bits per pixel component.

For color pixels, all components (i.e. ''pixies'') of the pixel are scanned and tallied. The sum of the tallies is the number of pixels in the image referenced by sip times the number of pixies per pixel.

If mode&0x100, the count array is not zeroed before tallying, allowing a second tally to be efficiently added to the first.

The s1p and s2p areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Center of Mass, Binary Image --- pxip8_masscenterbin



Summary 
int pxip8_masscenterbin(abortp, sip, area, xsum, ysum);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image
ulong               *area;          // result area
ulong               *xsum;          // result sum x coordinates
ulong               *ysum;          // result sum y coordinates



Description

The image referenced by sip is scanned and descriptive statistics returned. The image is interpreted as a binary image; pixels with value zero are background and all other pixels are foreground. The returned area is the number of foreground pixels, the returned xsum is the sum of x coordinates of foreground pixels, and the returned ysum is the sum of y coordinates of foreground pixels. If sip is an area of interest, the xsum and ysum are the sum of coordinates relative to the area of interest. From these values the x and y coordinates of the center of mass can be computed as xsum/area and ysum/area, respectively, again relative to the area of interest.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Center of Mass --- pxip8_masscenter
Compute Center of Mass of N'th Power --- pxip8_masscenterpow



Summary 
int pxip8_masscenter(abortp, sip, mass, xcenter, ycenter);
int pxip8_masscenterpow(abortp, sip, mass, xcenter, ycenter, pow, rsvd);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image
double              *mass;          // result mass
double              *xcenter;       // result center x
double              *ycenter;       // result center y
double              pow;            // should be 8
int                 rsvd;           // reserved. should be 0



Description

The image referenced by sip is scanned and descriptive statistics returned. For pxip8_masscenter, interpreting each pixel's value as its mass, or for pxip8_masscenterpow, interpreting each pixel's value to the 8'th power as its mass, the image's total mass, and the x and y center of mass, xcenter and ycenter respectively, are ''returned''. If sip is an area of interest, the xcenter and ycenter coordinates are relative to the area of interest.

The pxip8_masscenterpow is useful when finding the location of a single bright spot in an otherwise dark background, but where the background is not perfectly 0; the non-linear 8'th power diminishes the effect of the many small background values.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits. Monochrome, of float or double pixels.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Moments --- pxip8_moments



Summary 
int pxip8_moments(abortp, sip, aoiorigin, momp)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image
int                 aoiorigin;      // 1: origin is aoi, 0: origin is image
struct pxip8moments *momp;          // result




struct pxip8moments
{
    double  n;              // number of points
    double  nz;             // number of points not zero
    /*
     * Center of mass
     */
    double  cmass_x;
    double  cmass_y;
    /*
     * Moments, in form of array[x][y].
     * Up to third order is supported:
     *      [0][0], [0][1], [0][2], [0][3],
     *      [1][0], [1][1], [1][2],
     *      [2][0], [2][1],
     *      [3][0].
     * Fourth and higher order moments such as [2][2], [2][3], are always set to 0.
     */
    double  mom[4][4];      // raw moments about origin
    double  cmom[4][4];     // central moments, unnormalized
    double  cnormmom[4][4]; // central moments, scale normalized


    double  hu_mom[7];      // invariant moments, as per Hu
};



Description

The image referenced by sip is scanned and descriptive statistics returned. The statistics are returned in the pxip8moments structure referenced by momp.

Interpreting each pixel's value as its mass, the momp->mom are the various moments about the origin. If aoiorigin≠0, the origin is taken to be the upper left coordinate of the area of interest specified by sip; if aoiorigin=0, the origin is taken to be the upper left corner of the image specified by sip. The momp->n is the number of pixels, the momp->nz is the number of nonzero pixels. The momp->cmass_x is the X coordinate of the center of mass, the momp->cmass_y is the Y coordinate of the center of mass. The momp->cmom are the various central moments. The momp->cnormmom are the various central moments normalized for scale. The momp->hu_mom are 7 moment descriptors, invariant under scale, rotation and reflections.

Summations and computations are performed to the precision of a ''double'', thus the various statistics are a close approximation, but not exact. When comparing statistics of different images, using aoiorigin≠0 will provide reduced error due to limitations of numerical precision.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits. A math coprocessor is recommended.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

Gonzalez & Wintz, DIGITAL IMAGE PROCESSING, Addison-Wesley, 1987, pp. 419-423 for discussion on the use of moments.

The pxip8_masscenter is quicker when only the mass and center of mass is required.

Compute Moments w. Interpretation --- pxip8_momentsf



Summary 
int pxip8_momentsf(abortp, sip, aoiorigin, mapzifunc, mapxyhvfunc, mapzirefp, mapxyhvrefp, momp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image
int                 aoiorigin;      // 1: origin is aoi, 0: origin is image
double    (_cfunfcc *mapzifunc)(void *refp,struct pxyd *xyp, double z);
void      (_cfunfcc *mapxyhvfunc)(void*refp,struct pxyd*xyp,struct pxyd*hvp);
                                    // mappings: z to i, xy to hv
                                    // _cfunfcc is a predefined function modifier
void                *mapzirefp;     // arg for mapzifunc
void                *mapxyhvrefp;   // arg for mapxyhvfunc
struct pxip8moments *momp;          // result



Description

The image referenced by sip is scanned and descriptive statistics returned. The statistics are returned in the pxip8moments structure referenced by momp, shown under pxip8_moments. The pxip8_momentsf allows computation of the descriptive statistics based upon an arbitrary interpretation of pixel value and pixel location. In contrast, the similar pxip8_moments is limited to using the pixel's binary value and its x, y coordinates.

The mapzifunc should reference a caller provided function which maps a pixel's value into the desired interpretation, such as intensity, density, thickness, etc. The mapzifunc is invoked with three parameters: (1) The mapzirefp as passed to pxip8_momentsf, (2) A pointer to a struct pxyd containing the pixel's X, Y coordinates, and (3) The pixel's value (0 to the maximum pixel value). The mapzifunc should return a value corresponding to the pixel's value interpretation.

The mapxyhvfunc should reference a caller provided function which maps a pixel's X, Y coordinates into ''H'' and ''V'' axis coordinates. The mapxyhvfunc is invoked with three parameters: (1) The mapxyhvrefp as passed to pxip8_momentsf, (2) A pointer to a struct pxyd containing the pixel's X, Y coordinates, and (3) A pointer to a struct pxyd wherein the pixel's H, V coordinates are returned. The X, Y notations within the pxip8moments structure, and as discussed under pxip8_moments, should be respectively interpreted as ''H'', ''V'' coordinates.

Summations and computations are performed to the precision of a ''double'', thus the various statistics are a close approximation, but not exact. When comparing statistics of different images, using aoiorigin≠0 will provide reduced error due to limitations of numerical precision.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits. A math coprocessor is recommended.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

See pxip_calibxyhv and pxip_calibzi.


Example

A logarithmic density mapping and simple dimensional scaling functions are defined. 

double _cfunfcc densityfunc(void *p, struct pxyd *xyp, double i)
{
    return(log(i+.01));
}
void _cfunfcc xyhvmapfunc(void *p, struct pxyd *xyp, struct pxyd *hvp)
{
    hvp->xd = 10+.5 * xyp->xd;
    hvp->yd = 10+.5 * xyp->yd;
}
The mapping functions are now used in a code extract. 
struct pxip8moments moments;


pxip8_momentsf(NULL,
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               0, densityfunc, xyhvmapfunc, NULL, NULL, &moments))
Search for Smallest Pixel Value --- pxip8_findpixelmin
Search for Largest Pixel Value --- pxip8_findpixelmax



Summary 
int pxip8_findpixelmin(abortp, sip, xyp, valuep, countp, mode);
int pxip8_findpixelmax(abortp, sip, xyp, valuep, countp, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image
struct  pxy         *xyp;           // result coordinates
uint                *valuep;        // result value
pxim2size_t         *countp;        // result count
int                 mode;           // reserved, should be 0



Description

The image referenced by sip is scanned and descriptive statistics returned. The pxip8_findpixelmin reports the coordinates of the first occurrence of the smallest pixel value at *xyp, the smallest pixel's value at valuep, and the number of occurrences of the smallest value at countp. The pxip8_findpixelmax reports the coordinates of the first occurrence of the largest pixel value at *xyp, the largest pixel's value at valuep, and the number of occurrences of the largest value at countp.

Pixel values are scanned left-to-right and top-to-bottom. Should there be multiple occurrences of the smallest (or largest) pixel value, the coordinates returned are that of the first pixel found - the smallest y coordinate and smallest x coordinate. If sip is an area of interest, the coordinates returned are relative to the area of interest.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

1
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Count Pixels by Threshold --- pxip8_pixthresholdcnt



Summary 
int pxip8_pixthresholdcnt(abortp, sip, threshold, mode, countp)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // source image
uint32              threshold;      // threshold value
int                 mode;           // reserved. should be 0
pxim2size_t         *countp;        // returned !



Description

The image referenced by sip is scanned and the number of pixels that are greater than or equal to the threshold are ''returned'' at *countp. For color pixels, all components (i.e. ''pixies'') of the pixel are scanned, compared to the threshold, and counted. The maximum returned count is the number of pixels in the image referenced by sip times the number of pixies per pixel.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Count Real Pixels by Threshold --- pxipf_pixthresholdcnt



Summary 
int pxipf_pixthresholdcnt(abortp, sip, threshold, mode, countp)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // source image
double              threshold;      // threshold value
int                 mode;           // reserved. should be 0
pxim2size_t         *countp;        // returned !



Description

The image referenced by sip is scanned and the number of pixels that are greater than or equal to the threshold are ''returned'' at *countp. For color pixels, all components (i.e. ''pixies'') of the pixel are scanned, compared to the threshold, and counted. The maximum returned count is the number of pixels in the image referenced by sip times the number of pixies per pixel.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of float pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Radial Mass --- pxip8_radialmass



Summary 
int pxip8_radialmass(abortp, sip, origp, data, ndata, xscale, yscale);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image
struct  pxy         origp;          // origin
double              data[];         // result table
size_t              ndata;          // size of data[]
double              xscale;         // scale x coordinates by ...
double              yscale;         // scale y coordinates by ...



Description

The image referenced by sip is scanned and a table of the sum of pixels values versus their distance from an origin is returned.

The origp specifies the origin from which pixel distances are computed. The sum of pixels at various distances are added to data[0] through data[ndata-1]. The pxip8_radialmass does not initialize data[] elements to 0; pixel values are added to the existing data[] elements. For a pixel at coordinates (X, Y), the pixel's value is added to the i'th element of data, where i is: 

    double t1 = (X - origp->x) * xscale;
    double t2 = (Y - origp->y) * yscale;
    int i = (int)(sqrt(t1*t1 + t2*t2)+0.5)
Values of i greater or equal to ndata are ignored. The xscale and yscale serve both as scale factors to compensate for the image's aspect ratio, as well as to allow scaling of the result to the desired number of data elements.

The sip can be a full image or an area of interest. The image referenced by sip is not modified. The sip area of interest determines which pixel values are used, however their distance from the origp coordinates are interpreted relative to image coordinates, not area of interest coordinates.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 32 bits Monochrome, of float or double pixels.

COC40
Monochrome, of uchar or float pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Compute Radial Mass w. Interpretation --- pxip8_radialmassf



Summary 
int pxip8_radialmassf(abortp, sip, xyorigp, data, ndata, mapzifunc, mapxyhvfunc, mapzirefp, mapxyhvrefp, dscale);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image
struct  pxyd        xyorigp;        // origin
double              data[];         // result table
size_t              ndata;          // size of data[]
double    (_cfunfcc *mapzifunc)(void *refp,struct pxyd *xyp, double z);
void      (_cfunfcc *mapxyhvfunc)(void*refp,struct pxyd*xyp,struct pxyd*hvp);
                                    // mappings: z to i, xy to hv
                                    // _cfunfcc is a predefined function modifier
void                *mapzirefp;     // arg for mapzifunc
void                *mapxyhvrefp;   // arg for mapxyhvfunc
double              dscale;         // scale distance by ...



Description

The image referenced by sip is scanned and a table of the sum of pixels values versus their distance from an origin is returned.

The pxip8_radialmassf allows tabulating mass versus distance based upon an arbitrary interpretation of pixel value and pixel location. In contrast, the similar pxip8_radialmass is limited to using the pixel's binary value and its x, y coordinates.

The mapzifunc should reference a caller provided function which maps a pixel's value into the desired interpretation, such as intensity, density, thickness, etc. The mapzifunc is invoked with three parameters: (1) The mapzirefp as passed to pxip8_momentsf, (2) A pointer to a struct pxyd containing the pixel's X, Y coordinates, and (3) The pixel's value (0 to the maximum pixel value). The mapzifunc should return a value corresponding to the pixel's value interpretation.

The mapxyhvfunc should reference a caller provided function which maps a pixel's X, Y coordinates into ''H'' and ''V'' axis coordinates. The mapxyhvfunc is invoked with three parameters: (1) The mapxyhvrefp as passed to pxip8_momentsf, (2) A pointer to a struct pxyd containing the pixel's X, Y coordinates, and (3) A pointer to a struct pxyd wherein the pixel's H, V coordinates are returned. The X, Y notations within the pxip8moments structure, and as discussed under pxip8_moments, should be respectively interpreted as ''H'', ''V'' coordinates.

The xyorigp specifies the origin from which pixel distances are computed, before mapping by mapxyhvfunc. The sum of pixels at various distances are added to data[0] through data[ndata-1]. The pxip8_radialmassf does not initialize data[] elements to 0; pixel values are added to the existing data[] elements. For a pixel at coordinates (X, Y) with value Z, the value i is added to the k'th element of data, where i and k are: 

    struct pxyd xy1, xy2, xy3;
    xy1.xd = X;
    xy1.yd = Y;
    (mapxyhvfunc)(mapxyhvrefp, &xy1, &xy2);
    (mapxyhvfunc)(mapxyhvrefp, xyoriginp, &xy3);
    double d = sqrt((xy2.xd-xy3.xd)*(xy2.xd-xy3.xd)+(xy2.yd-xy3.yd)*(xy2.yd-xy3.yd));
    int k = (int)(dscale * d + 0.5)
    double i = (>mapzifunc)(mapzirefp, &xy1, Z);
Values of k greater or equal to ndata are ignored.

The sip can be a full image or an area of interest. The image referenced by sip is not modified. The sip area of interest determines which pixel values are used, however their distance from the xyorigp coordinates are interpreted relative to image coordinates, not area of interest coordinates.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 32 bits Monochrome, of float or double pixels.

COC40
Monochrome, of uchar or float pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

See pxip_calibxyhv and pxip_calibzi.

 

 

 

8. Filtering Operations

Filter, Low Pass, Weighted --- pxip8_3x3lowpass
Filter, Low Pass, Fixed --- pxip8_3x3lowpassf



Summary 
int pxip8_3x3lowpass(abortp, sip, dip, weight);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                weight;         // center pixel weight


int pxip8_3x3lowpassf(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

A low pass filter operation is applied to the image referenced by sip, with the result placed in the image referenced by dip.

The pxip8_3x3lowpass filter operates on the 3x3 neighborhood of each pixel, replacing the pixel with the mean of its 8 neighbors and the pixel replicated weight times. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels. The weight parameter, weight≥0, effectively controls the degree of filtering; the larger the weight, the weaker the low pass filter. The operation is equivalent to use of pxip8_NxNconvolve with a convolution mask of: 

 1    1     1
 1  weight  1
 1    1     1
but is significantly faster.

The pxip8_3x3lowpassf filter operates on the 3x3 neighborhood of each pixel, equivalent to use of pxip8_NxNconvolve with a convolution mask of: 

 1    2     1
 2    4     2
 1    2     1
but is faster than pxip8_NxNconvolve and pxip8_3x3lowpass.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Filter, Low Pass, Low Smear --- pxip8_3x3lowpassmear



Summary 
int pxip8_3x3lowpassmear(abortp, sip, dip, threshold);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 threshold;      // no smear threshold



Description

A low pass, low smearing filter operation is applied to the image referenced by sip, with the result placed in the image referenced by dip. Similar to pxip8_3x3lowpass, the filter operates on the 3x3 neighborhood of each pixel, replacing the pixel with the mean of itself and its 8 neighbors; however neighboring pixels with a difference in value from the center pixel greater than the threshold do not participate in the mean. With a suitable threshold value, the image can be low pass filtered, without smearing or blurring strong edges. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Filter, Sharpen, Laplacian --- pxip8_3x3sharpenl



Summary 
int pxip8_3x3sharpenl(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

An image sharpen, or high pass filter, operation is applied to the image referenced by sip, with the result placed in the image referenced by dip. The pxip8_3x3sharpenl filter operates on the 3x3 neighborhood of each pixel, replacing the pixel with its value minus the laplacian (2nd derivative) of its neighborhood. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

The operation is equivalent to a pxip8_NxNconvolve with a convolution mask of: 

 0   -1     0
-1    5    -1
 0   -1     0
but is significantly faster.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Filter, Median --- pxip8_3x3median



Summary 
int pxip8_3x3median(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

A median filter is applied to the 3x3 neighborhood of each pixel in the binary image referenced by sip with the result placed in the image referenced by dip. Each pixel is replaced with the median of itself and its 8 adjacent pixels. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Filter, Median, Weighted --- pxip8_3x3medianw



Summary 
int pxip8_3x3medianw(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

A median filter is applied to the 3x3 neighborhood of each pixel in the image referenced by sip, with the result placed in the image referenced by dip. Each pixel is replaced with the median computed upon itself replicated three times and its 8 adjacent pixels. Replicating provides greater weight to the center pixel value, avoiding certain types of edge & corner smear of single pixel width lines. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

See D.R.K Brownrigg, "The Weighted Median Filter", COMMUNICATIONS OF THE ACM, Vol. 27-8, August 1984, pp. 807-818.

Filter, Median, Binary Images --- pxip8_3x3binmedian



Summary 
int pxip8_3x3binmedian(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

A median filter is applied to the 3x3 neighborhood of each pixel in the binary image referenced by sip, with the result placed in the image referenced by dip. Each pixel is replaced with the median of itself and its 8 adjacent pixels. The most significant bit of each pixel is used as the binary value indicator; result pixels in dip are set to value 0 or the value of the most significant bit (e.g. 0 or 128 for 8 bit pixels). For binary images, pxip8_3x3binmedian produces the same result as pxip8_3x3median, but is quicker. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Filter, Rank Low (Erode) --- pxip8_3x3ranklow
Filter, Rank High (Dilate) --- pxip8_3x3rankhigh



Summary 
int pxip8_3x3ranklow(abortp, sip, dip);
int pxip8_3x3rankhigh(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

A rank filter is applied to the 3x3 neighborhood of each pixel in the binary image referenced by sip with the result placed in the image referenced by dip. The pxip8_3x3ranklow replaces each pixel with the lowest value of itself and its 8 adjacent pixels. The pxip8_3x3rankhigh replaces each pixel with the highest value of itself and its 8 adjacent pixels. Boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

9. Edge Detection Operations

Edge Detection, Kirsch --- pxip8_3x3kirsch
Edge Detection, Roberts --- pxip8_2x2roberts
Edge Detection, Sobel --- pxip8_3x3sobel
Edge Detection, Sobel Absolute --- pxip8_3x3sobela



Summary 
int pxip8_3x3kirsch(abortp, sip, dip, mode);
int pxip8_2x2roberts(abortp, sip, dip, mode);
int pxip8_3x3sobel(abortp, sip, dip, mode);
int pxip8_3x3sobela(abortp, sip, dip, mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // 0: scaled magnitude
                                    // 1: old pixel - scaled magnitude
                                    // 2: 5 bit log magn. & 3 bit angle
                                    // 3: magnitude (unscaled)



Description

An edge detection operation is applied to the 3x3 neighborhood (2x2 neighborhood for Roberts) of each pixel in the image referenced by sip, with the result placed in the image referenced by dip. According to the choice of the Kirsch, Roberts or Sobel operation, the standard masks are used to compute the edge gradient at each pixel of sip. The pxip8_3x3sobel variant uses root-mean-square, while the pxip8_3x3sobela variant uses the quicker absolute value method.

If mode=0, the magnitude of the gradient is linearly scaled to fit, with the maximum possible gradient magnitude scaled to the maximum pixel value (255 for 8 bit pixels), and placed in the corresponding pixel of dip. If mode=3, the magnitude of the gradient is bounded to the maximum pixel value (255 for 8 bit pixels), and placed in the corresponding pixel of dip. For both modes, areas of the source image without edges produce a 0, black, result. Areas of the result are grey and white in proportion to edge strengths in the source image.

If mode=1, the magnitude of the gradient is linearly scaled to fit in 8 bits, subtracted from the original pixel of sip, with results below 0 limited to 0, and placed in the corresponding pixel of dip. The result enhances the original image's edges, an operation sometime referred to as ''unsharp masking''.

If mode=2, the magnitude of the gradient is log scaled to fit in the upper 5 bits, the angle coded to fit in the lower 3 bits, and both placed in the corresponding pixel of dip. 'ne 1i The encoding of angles is: 

3  2  1
4  *  0
5  6  7
where ''*'' represents the pixel under consideration. Thus, angle code 0 represents angles from -22.5 to +22.5 degrees of east, angle code 1 represents angles from +22.5 to +67.5 of east, etc. The angle is in the direction of maximum gradient from dark to light, orthogonal to the direction in which the edge ''runs''. A magnitude of 0 is always coded with an angle of 0.

For mode=1, the boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels. For other modes, result pixels on the boundary are set to 0.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Hints

The manner of encoding angles in mode=2 as least significant bits invites use of various operations upon the magnitude, while ignoring the angular component. For example, after edge detection with mode=2, all weak edges with log magnitude less than or equal to 5 can be removed and set to 0 with: 

pxip8_pixthreshold(NULL, sip, dip, 0, 5<<3, 0);



Supports

80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.
Only the upper 8 bits per pixel are used.


Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Edge Gradient, Thin --- pxip8_3x3ksrthin



Summary 
int pxip8_3x3ksrthin(abortp, sip, dip, thinmode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 thinmode;       // 0: minimal
                                    // 1: maximal



Description

An edge thinning operation is applied to each pixel in the image defined by sip, with the result placed in the image defined by dip. The sip image must be the result of a previous edge gradient detection, with the magnitude of the gradient log scaled to fit in the upper 5 bits, and the angle coded to fit in the lower 3 bits, of each pixel. Such results are produced by pxip8_3x3kirsch, pxip8_2x2roberts, pxip8_3x3sobel, or pxip8_3x3sobela with a mode=2.

The pxip8_3x3ksrthin thins the gradient coded edges by evaluation of each edge and its local 3x3 neighborhood. Any gradient edge which is weaker than its two orthogonal neighbors, or which is neither preceded nor followed by another gradient edge in the same direction ±1, is removed. The criteria is strengthened if thinmode=1: retained gradient edges must be stronger than its two orthogonal neighbors, and must be both preceded and followed by another gradient edge in the same direction ±1. The pxip8_3x3ksrthin may be repeated for additional effect, although it is not a ''relaxation'' type algorithm and repetitions beyond two or three will have little beneficial effect.

The boundary conditions (pixels lacking eight neighbors) are treated by duplicating, in dip, the adjacent result pixels.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

pxip8_3x3kirsch, pxip8_2x2roberts, pxip8_3x3sobel.

 

 

 

10. Image Pair Operations

Contrast Match Image Pair --- pxip8_contrastmatch



Summary 
int pxip8_contrastmatch(abortp, s1p, s2p, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination



Description

The contrast of the image referenced by s2p is modified so that the first two moments of pixel values match (to the extent possible) the moments of the image referenced by s1p, with the result placed in the image referenced by dip. This operation is useful before subtraction of two images taken under different exposure conditions, such as subtractive radiography.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

Ruttimann, et. al., SPIE Vol. 314, p. 372.

Add Pixels of Image Pair --- pxip8_pairadd



Summary 
int pxip8_pairadd(abortp, s1p, s2p, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // Low byte:
                                    //   1: unbounded
                                    //   2: bounded by the maximum pixel value
                                    // 0x8000: use top line of s1p, replicated



Description

The numeric value of pixels of the image referenced by s1p are added to the corresponding pixels in the image referenced by s2p and the result placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently added.

If mode&0xFF=2, sums greater than the maximum pixel value are bounded to the minimum and maximum pixel value (0 and 255, respectively, for 8 bit pixels). If mode&0xFF=1, sums are not bounded by the maximum pixel value, but integer values are truncated by overflow of the pixel word size. If mode&0x8000, only the top line of s1p is used and reused as each line of the s1p.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.

In mode=1, also supports unsigned integer pixels of 32 bits for s2p combined with unsigned integer pixels of 1 to 16 bits for s1p, allowing direct summation of 1 to 16 bit pixels into a 32 bit sum. In mode=1, also supports double pixels for s2p combined with float pixels for s1p, allowing direct summation of float pixels into a double sum.


Returns


0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Subtract Pixels of Image Pair --- pxip8_pairsub



Summary 
int pxip8_pairsub(abortp, s1p, s2p, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // Low byte:
                                    //    1: (pixel2-pixel1) modulo pixel_word_size
                                    //    5: (pixel1-pixel2) modulo pixel_word_size
                                    //    2: max(pixel2-pixel1, minimum_pixel_value)
                                    //    6: max(pixel1-pixel2, minimum_pixel_value)
                                    //    3: abs(pixel2-pixel1)
                                    //    7: abs(pixel1-pixel2)
                                    //    4: (maximum_pixel_value+pixel2-pixel1)/2
                                    //    8: (maximum_pixel_value+pixel1-pixel2)/2
                                    //    9: (maximum_pixel_value+(pixel2-pixel1))
                                    //   10: (maximum_pixel_value+(pixel2-pixel1)*2)
                                    //   11: (maximum_pixel_value+(pixel1-pixel2))
                                    //   12: (maximum_pixel_value+(pixel1-pixel2)*2)
                                    //   100: (pixel2+(pixel2-pixel1))
                                    //   101: (pixel2+(pixel2-pixel1)*2)
                                    //   102: (pixel2+(pixel2-pixel1)*4)
                                    // 0x8000: use top line of s1p, replicated



Description

The difference of the numeric value of corresponding pixels of the image referenced by s1p and by s2p are placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently subtracted.

For 1≥mode&0xFF<=4, the pixels of s1p are subtracted from corresponding pixels of s2p. If mode&0xFF=1, the difference is not bounded by the minimum pixel value, but integer values are truncated by overflow of the pixel word size. If mode&0xFF=2, the difference is bounded by the minimum pixel value (0 for 8 bit pixels). If mode&0xFF=3, the absolute value of the difference is used. If mode&0xFF=4, the difference is divided by two and added to half of the maximum pixel value (½ of 255 for 8 bit pixels).

For 5≥mode&0xFF<=8, the pixels of s2p are subtracted from corresponding pixels of s1p. If mode&0xFF=5, the difference is not bounded by the minimum pixel value, but integer values are truncated by overflow of the pixel word size. If mode&0xFF=6, the difference is bounded by the minimum pixel value (0 for 8 bit pixels). If mode&0xFF=7, the absolute value of the difference is used. If mode&0xFF=8, the difference is divided by two and added to half of the maximum pixel value. The mode&0xFF=3 and mode&0xFF=7 are, of course, identical; both are provided for the sake of ease of use.

If mode&0xFF=9 the difference of pixels of s1p subtracted from corresponding pixels of s2p and added to half of the maximum pixel value, bounded by the minimum and maximum pixel value. If mode&0xFF=10 twice the difference of pixels of s1p subtracted from corresponding pixels of s2p and added to half of the maximum pixel value, bounded by the minimum and maximum pixel value. If mode&0xFF=11 the difference of pixels of s2p subtracted from corresponding pixels of s1p and added to half of the maximum pixel value, bounded by the minimum and maximum pixel value. If mode&0xFF=12 twice the difference of pixels of s2p subtracted from corresponding pixels of s1p and added to half of the maximum pixel value, bounded by the minimum and maximum pixel value.

If mode&0xFF=100, the difference of pixels of s2p and s1p are added to pixel of s2p, bounded by the minimum and maximum pixel value. If mode&0xFF=101 or mode&0xFF=102, twice or four times, respectively, the difference of pixels of s2p and s1p are added to pixel of s2p, bounded by the minimum and maximum pixel value.

If mode&0x8000, only the top line of s1p is used and reused as each line of the s1p.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Average Pixels of Image Pair --- pxip8_pairave
Maximum of Pixels of Image Pair --- pxip8_pairmax
Minimum of Pixels of Image Pair --- pxip8_pairmin



Summary 
int pxip8_pairave(abortp, s1p, s2p, dip);
int pxip8_pairmax(abortp, s1p, s2p, dip);
int pxip8_pairmin(abortp, s1p, s2p, dip);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination



Description

The numeric value of pixels of the image referenced by s1p are operated upon by the value of corresponding pixels in the image referenced by s2p and the result placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently operated upon.

For pxip8_pairave, the operation is the numeric average of corresponding pixels. For pxip8_pairmax, the operation is the numeric maximum of corresponding pixels. For pxip8_pairmin, the operation is the numeric minimum of corresponding pixels.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Exclusive OR Pixels of Image Pair --- pxip8_pairxor
AND Pixels of Image Pair --- pxip8_pairand
OR Pixels of Image Pair --- pxip8_pairor



Summary 
int pxip8_pairxor(abortp, s1p, s2p, dip);
int pxip8_pairand(abortp, s1p, s2p, dip);
int pxip8_pairor(abortp, s1p, s2p, dip);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination



Description

The numeric value of pixels of the image referenced by s1p are operated upon by the value of corresponding pixels in the image referenced by s2p and the result placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently operated upon.

For pxip8_pairxor, the operation is a boolean, bitwise, EXCLUSIVE-OR of corresponding pixels. For pxip8_pairand, the operation is a boolean, bitwise, AND of corresponding pixels. For pxip8_pairor, the operation is a boolean, bitwise, INCLUSIVE-OR of corresponding pixels.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Difference for Insert of Image Pair --- pxip8_pairinsdiff
Insert of Differences of Image Pair --- pxip8_pairinsert



Summary 
int pxip8_pairinsdiff(abortp, s1p, s2p, dip, epsilon);
int pxip8_pairinsert(abortp, s1p, s2p, dip);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 epsilon;        // epsilon



Description

The pxip8_pairinsdiff and pxip8_pairinsert are a pair of operations to extract the differences between two source images and to reconstruct one of the source images given the other source image and the difference result.

The pxip8_pairinsdiff compares corresponding pixel values of the image referenced by s1p and s2p; if the values are identical to within ±epsilon the corresponding pixel of the image referenced by dip is set to 0, otherwise the corresponding dip pixel is set equal to the s2p pixel value. Specifically, 

If ( Abs(s2p - s1p) <= epsilon)
    dip = 0;
else
    dip = s2p;
Thus the result image dip shows those areas of s2p which differ significantly from s1p.

The pxip8_pairinsert does the inverse of pxip8_pairinsdiff. For every pixel of the image referenced by s2p which is 0, the corresponding pixel of the result image referenced by dip is set equal to the corresponding pixel of the image referenced by s1p; if the s2p is not 0 the corresponding pixel of the result dip is set equal to the s2p pixel. Thus the result image is a copy of s1p, except for nonzero pixels of s2p which were inserted. 

If      pxip8_pairinsdiff(image_X, image_W, image_Y, epsilon)
and     pxip_pairinsert(image_X, image_Y, Image_Z)
then    image_X = Image_Z
The equality between image_X and image_Z is precise if the epsilon was 0 and neither image_X nor image_W had 0 pixels, otherwise the equality is approximate.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Product of Pixels of Image Pair --- pxip8_pairprod
Product of Pixels of Image Pair --- pxipf_pairprod
Ratio of Pixels of Image Pair --- pxip8_pairratio
Ratio of Pixels of Image Pair --- pxipf_pairratio



Summary 
int pxip8_pairprod(abortp, s1p, s2p, dip, mode, coef);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
int                 coef[5];        // 5 coefficients


int pxipf_pairprod(abortp, s1p, s2p, dip, mode, coef);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
double              coef[5];        // 5 coefficients


int pxip8_pairratio(abortp, s1p, s2p, dip, mode, coef);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
int                 coef[4];        // 4 coefficients


int pxipf_pairratio(abortp, s1p, s2p, dip, mode, coef);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
double              coef[4];        // 4 coefficients



Description

The numeric value of pixels of the image referenced by s1p are algebraically combined with corresponding pixels in the image referenced by s2p and the result placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently algebraically combined.

For pxip8_pairprod and pxipf_pairprod, letting Pix1 and Pix2 represent corresponding pixels of s1p and s2p, the computation is: 

(coef[0] * Pix1 + coef[1]) * (coef[2] * Pix2 + coef[3])) / coef[4]
with the result bounded to the minimum and maximum pixel value (0 and 255, respectively, for 8 bit pixels) and placed in the corresponding pixel of dip. A coef[4]=0 is interpreted as value 1.

For pxip8_pairratio and pxipf_pairratio, the computation is: 

(coef[0] * Pix2 + coef[1])  / (coef[2] * Pix1 + coef[3])
with the result bounded to the minimum and maximum pixel value (0 and 255, respectively, for 8 bit pixels) and placed in the corresponding pixel of dip. If the divisor is 0, the result pixels are set to the maximum pixel value.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
For pxip8_pairprod and pxip8_pairratio: Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. For pxipf_pairprod and pxipf_pairratio: Monochrome or color, of float or double pixels.

COC40
For pxip8_pairprod and pxip8_pairratio: Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Overlay Pixels of Image Pair --- pxip8_pairoverlay
Overlay Pixels of Image Pair --- pxipf_pairoverlay



Summary 
int pxip8_pairoverlay(abortp, s1p, s2p, dip, mode, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
uint                value[];        // chroma key value


int pxipf_pairoverlay(abortp, s1p, s2p, dip, mode, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
double              value[];        // chroma key value



Description

The pixels of the image referenced by s2p are selectively replaced by corresponding pixels of the image referenced by s1p and the result placed in the corresponding pixels of the image referenced by dip. Pixels of s1p which are equal to the chroma key value do not replace the corresponding pixels of s2p. Pixels of s1p which are not equal to the chroma key value replace the corresponding pixels of s2p.

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
For pxip8_pairoverlay: Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. For pxipf_pairoverlay: Monochrome or color, of float or double pixels.

COC40
For pxip8_pairoverlay: Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Blend Pixels of Image Pair --- pxip8_pairblend



Summary 
int pxip8_pairblend(abortp, s1p, s2p, s3p, dip, mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1
struct  pximage     *s2p;           // source 2
struct  pximage     *s3p;           // source 3
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0



Description

The pixels of the image referenced by s1p are blended with the corresponding pixels in the image referenced by s3p as per the weighting in the pixel values referenced by s2p and the result placed in the corresponding pixels of the image referenced by dip. For color pixels, each corresponding component (i.e. ''pixie'') of the pixels are independently operated upon.

The s2p weights are relative to the maximum pixel value. At maximum weight, the pixel value of s1p is used; at minimum weight the pixel value of s3p is used. For other weights, a weighted average of s1p and s3p is used: 

s2p × (s1p ÷ maxvalue) + (maxvalue - s2p) × (s3p ÷ maxvalue)

The s1p, s2p, and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by s1p and s2p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

11. Morphological Operations

Morphology Erosion w. 3x3 Element --- pxip8_morperode3x3
Morphology Dilation w. 3x3 Element --- pxip8_morpdilate3x3



Summary 
int pxip8_morperode3x3(abortp, sip, dip, mode);
int pxip8_morpdilate3x3(abortp, sip, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0



Description

A morphological operation is performed upon the source image referenced by sip with the result placed in the destination image referenced by dip. The source is interpreted as a binary valued image as indicated by the high bit of each pixel. The resulting image is binary valued; pixels are either 0 or have only the high bit set (e.g. 0 and 128 for 8 bit pixels).

The pxip8_morperode3x3 performs morphological erosion, using the standard 3x3 structure element. The result is nonzero if the structure element, center positioned over the corresponding pixel of the source image, covers only source pixels with the high bit set. The pxip8_morpdilate3x3 performs morphological dilation, using the standard 3x3 structure element. The result is nonzero if the structure element, center positioned over the corresponding pixel of the source image, covers any source pixels with the high bit set.

The pxip8_morperode and pxip8_morpdilate can also perform erosion and dilation, but allow arbitrary structure elements and provide reports on results. The pxip8_morperode3x3 and pxip8_morpdilate3x3 are quicker when the standard 3x3 structure element is used, and result reports are not needed.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

See pxip8_morperode and pxip8_morpdilate.

Morphology Erosion --- pxip8_morperode
Morphology Dilation --- pxip8_morpdilate
Morphology Open --- pxip8_morpopen
Morphology Close --- pxip8_morpclose
Morphology Hit-Miss --- pxip8_morphitmiss



Summary 
int pxip8_morperode(abortp, sip, dip, msep, msedim, rotate, outab, countp);
int pxip8_morpdilate(abortp, sip, dip, msep, msedim, rotate, outab, countp);
int pxip8_morpopen(abortp, sip, dip, msep, msedim, rotate, outab, countp);
int pxip8_morpclose(abortp, sip, dip, msep, msedim, rotate, outab, countp);
int pxip8_morphitmiss(abortp, sip, dip, msep, msedim, rotate, outab, countp);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uchar               *msep;          // 2-d structure element array
int                 msedim;         // dimension of above
int                 rotate;         // amount to rotate, 0-7
int                 outab;          // output mapping logic table
pxim2size_t         *countp;        // 'returns' nonzero result pixels



Description

A specified morphological operation is performed upon the source image referenced by sip with the result placed in the destination image referenced by dip. The source is interpreted as a binary valued image as indicated by the high bit of each pixel. The resulting image is binary valued; pixels are either 0 or have only the high bit set (e.g. 0 and 128 for 8 bit pixels).

An arbitrary morphological structure element, defined by msep, is applied to the image according to the definition of the particular operation. The morphological structure element is represented by the square, possibly sparse, array msep of dimension msedim (squared). The elements of the array should be the constant PXIP8MORPFORE to define a foreground or object element pixel, PXIP8MORPBACK to define a background element pixel (for those operations which utilize background element pixels), or 0 for no element. One array element should be ORed with PXIP8MORPORIG to define the origin; otherwise the center is used as the origin. For example, the commonly used 3x3 block structure element may be defined by: 

uchar mse3x3[3][3] = {
    PXIP8MORPFORE, PXIP8MORPFORE,               PXIP8MORPFORE,
    PXIP8MORPFORE, PXIP8MORPFORE|PXIP8MORPORIG, PXIP8MORPFORE,
    PXIP8MORPFORE, PXIP8MORPFORE,               PXIP8MORPFORE,
};
As another example, the structure element represented by: 
X  X  X
   X
O  O  O
where the ''X'' is foreground-object, the ''O'' is background, and the center is the origin may be defined by: 
uchar mse1[3][3] = {
    PXIP8MORPFORE, PXIP8MORPFORE,               PXIP8MORPFORE,
    0,             PXIP8MORPFORE|PXIP8MORPORIG, 0,
    PXIP8MORPBACK, PXIP8MORPBACK,               PXIP8MORPBACK,
};
with msedim=3. There is no explicit limit on the value of msedim, but malloc'ed memory proportional to the square of msedim is required.

If rotate≠0, the morphological structure element defined by msep and msedim is rotated by rotate*45 degrees counterclockwise before use in the morphological operation. The rotation is performed around the defined or default origin within the limits of the discrete array. For example, a 5x5 array: 

a  b  c  d  e
f  g  h  i  j
k  l  m  n  o
p  q  r  s  t
u  v  w  x  y
rotated 45 degrees around the origin ''m'' would yield: 
c  d  e  j  o
b  h  i  n  t
a  g  m  s  y
f  l  q  r  x
k  p  u  v  w
Note that the rotation's effect could be directly accomplished by suitable redefinition of the msep; the rotation capability is an added convenience.

The pxip8_morperode performs erosion. The result is nonzero if the foreground structure element, origin positioned over the corresponding pixel of the source image, covers only source pixels with the high bit set. Any background elements of the structure are ignored.

The pxip8_morpdilate performs dilation. The result is nonzero if the foreground structure element, origin positioned over the corresponding pixel of the source image, covers any source pixels with the high bit set. Any background elements of the structure are ignored.

The pxip8_morpopen performs opening; an erosion followed by dilation. Any background elements of the structure are ignored.

The pxip8_morpclose performs closing; a dilation followed by erosion. Any background elements of the structure are ignored.

The pxip8_morphitmiss compares the structure element ''mask'' against the source image; the result is nonzero if the structure element, origin positioned over the corresponding pixel of the source image, exactly matches the source pixels - foreground elements over pixels with the high bit set and background elements over pixels without the high bit set.

The pixel values written to the destination image dip are a function of the source image pixels and the result of the morphological operation. All 16 possible functions of these two variables are available, selected by outab. 





Source pixel 


 Morphological 


 Destination






High Bit 


 Result 


 High Bit








0 


 0 


 bit 0 of outab






0 


 1 


 bit 1 of outab






1 


 0 


 bit 2 of outab






1 


 1 


 bit 3 of outab
Thus, outab=0xA yields the morphological result, outab=0x5 yields the complement of the morphological result, and outab=0x4 yields the set difference between the source image and the morphological result.

If countp≠NULL, the number of nonzero pixels in the destination image is ''returned'' at *countp. In addition to error return codes noted below, 1 is returned if the high bit of pixels of sip is different than dip, or 0 is returned if the operation had no effect (other than possibly clearing bits 0 through 6).

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

1
Operation complete, contents of destination image different from source image.

0
Operation complete, contents of destination image same as source image.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
The pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

Erosion is performed on the first image frame buffer, with the same buffer used as both source and destination. The morphological structure element is a 5x5 box, used without rotation. 

uchar   mse2[5][5];
ulong   count;
int     i;


memset(mse2, PXIP8MORPFORE, 25);        // a C library function
mse2[2][2] |= PXIP8MORPORIG;
i = pxip8_morperode(NULL,
                    #if 1       // w. XCLIB
                      pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                      pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                    #else       // w. SVOBJ,4MOBJ,XCOBJ
                      pxd_defimage(1,0,0,-1,-1),
                      pxd_defimage(1,0,0,-1,-1),
                    #endif
                    mse2, 5, 0, 0xA, &count);
if (i < 0)
    printf("Error %s\n", pxerrnomesg(i));
else if (i == 0)
    printf("Image unchanged, %ld nonzero pixels\n", count);
else
    printf("Image changed, %ld nonzero pixels\n", count);
Boundary detection can be performed by using an outab to form the difference between the original image and its erosion. A 3x3 box is a more suitable morphological structure element for this operation. 
uchar   mse3[3][3];


memset(mse3, PXIP8MORPFORE, 9);         // a C library function
mse3[1][1] |= PXIP8MORPORIG;
i = pxip8_morperode(NULL,
                    #if 1       // w. XCLIB
                      pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                      pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                    #else       // w. SVOBJ,4MOBJ,XCOBJ
                      pxd_defimage(1,0,0,-1,-1),
                      pxd_defimage(1,0,0,-1,-1),
                    #endif
                    mse3, 3, 0, 0x4, &count);
    ...
The above example formed a boundary which is the outer edge of each nonzero object. A boundary which is outside each nonzero object can be formed by using an outab to form the difference between a dilation and the original image. 
memset(mse3, PXIP8MORPFORE, 9);         // a C library function
mse3[1][1] |= PXIP8MORPORIG;
i = pxip8_morpdilate(NULL,
                     #if 1       // w. XCLIB
                       pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                       pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                     #else       // w. SVOBJ,4MOBJ,XCOBJ
                       pxd_defimage(1,0,0,-1,-1),
                       pxd_defimage(1,0,0,-1,-1),
                     #endif
                     mse3, 3, 0, 0x2, &count);
    ...
The skeleton of a nonzero object can be found by rotated matchings of the morphological structure element shown above as mse1, subtracting the result from the original image. 
for (i = 0; i < 8; i++)
    pxip8_morphitmiss(NULL,
                      #if 1       // w. XCLIB
                        pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                        pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                      #else       // w. SVOBJ,4MOBJ,XCOBJ
                        pxd_defimage(1,0,0,-1,-1),
                        pxd_defimage(1,0,0,-1,-1),
                      #endif
                      mse1, 3, i, 0x4, &count);
Each 8 passes selectively removes pixels along each of 8 edge orientations. The process may be repeated until the edges are single width lines.
Medial Axis Thinning --- pxip8_binmaxisthin



Summary 
int pxip8_binmaxisthin(sip, dip, x1, x2, x3, outab, countp);


struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
void                *x1;            // unused
int                 x2, x3;         // unused
int                 outab;          // output mapping logic table
pxim2size_t         *countp;        // 'returns' nonzero result pixels



Description

A medial axis thinning operation (i.e. skeleton generation) is performed upon the source image referenced by sip with the result placed in the destination image referenced by dip. The source is interpreted as a binary valued image as indicated by the high bit of each pixel. The resulting image is binary valued; pixels are either 0 or have only the high bit set (e.g. 0 and 128 for 8 bit pixels).

At each pixel of the source image, pxip8_binmaxisthin computes a result which is nonzero when the source pixel is at the edge and can be removed without affecting connectivity.

The pixel values written to the destination image dip are a function of the source image pixels and the result of the computation described above. All 16 possible functions of these two variables are available, selected by outab. 





Source pixel 


 Computation 


 Destination






High Bit 


 Result 


 High Bit








0 


 0 


 bit 0 of outab






0 


 1 


 bit 1 of outab






1 


 0 


 bit 2 of outab






1 


 1 


 bit 3 of outab
Thus, outab=0xA yields the computation result as described, and outab=0x4 yields the set difference between the source image and the computation result described above. The outab=0x4 is normally used for generation of the medial axis skeleton.

If countp≠NULL, the number of nonzero pixels in the destination image is ''returned'' at *countp. In addition to error return codes noted below, 1 is returned if the high bit of pixels of sip is different than dip, or 0 is returned if the operation had no effect (other than possibly clearing bits 0 through 6).

The sip and dip can be a full image or an area of interest. The sip and dip must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

1
Operation complete, contents of destination image different from source image.

0
Operation complete, contents of destination image same as source image.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

See pxip8_morperode3x3 and pxip8_morpdilate3x3.


Example

Medial axis thinning is repeatedly applied until further applications have no effect. At that point the nonzero image objects have been thinned to lines of single width. 

ulong   count;
int     i;


do {
    i = pxip8_binmaxisthin(NULL,
                           #if 1       // w. XCLIB
                             pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                             pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                           #else       // w. SVOBJ,4MOBJ,XCOBJ
                             pxd_defimage(1,0,0,-1,-1),
                             pxd_defimage(1,0,0,-1,-1),
                           #endif
                           NULL,0,0,0x4,&count);
} while (i == 1);
if (i < 0)
    printf("Error %s\n", pxerrnomesg(i));
else
    printf("%ld nonzero pixels\n", count);

 

 

 

12. Image Sequence Operations

Integrate Image Sequence --- pxip8_integratebufs
Average Image Sequence --- pxip8_averagebufs
Mean/Std.Dev/Variance of Image Sequence --- pxip8_pixelstatsbufs



Summary 
int pxip8_integratebufs(abortp, si3p, dip, divisor, mode);
int pxip8_averagebufs(abortp, si3p, dip);
int pxip8_pixelstatsbufs(abortp, si3p, dip, rsvd, scale, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage3     *si3p;          // images to average or integrate
struct pximage      *dip;           // result
pxcoord_t           divisor;        // summation divisor. 0 for number of images
int                 mode;           // see below
int                 rsvd;           // reserved. should be 0
double              scale;          // scaling factor



Description

The pxip8_integratebufs sums each set of corresponding pixels of a sequence of images referenced by si3p, divides by the divisor, and places the result, limited to the maximum pixel value (e.g. 255 for 8 bit pixels) in the corresponding pixel of the result image referenced by dip. If the divisor=0, the number of images in the sequence is used as the divisor. The mode is reserved and should be 0.

The pxip8_averagebufs averages each set of corresponding pixels of a sequence of images referenced by si3p, and places the average in the corresponding pixel of the result image referenced by dip; it is the same as using pxip8_integratebufs with divisor=0. The mode is reserved and should be 0.

The pxip8_pixelstatsbufs computes mean, standard deviation, or variance on each set of corresponding pixels of a sequence of images referenced by si3p, multiplies by scale, and places the result, limited to the maximum pixel value (e.g. 255 for 8 bit pixels) in the corresponding pixel of the result image referenced by dip. If mode='m' the mean is computed, if mode='s' the standard deviation is computed, if mode='v' the variance is computed.

The pxip8_integratebufs and pxip8_averagebufs operate with 32 bit arithmetic, and therefore, for 8 bit pixels, provide full precision for a sequence of up to 223 images; all corresponding pixels are summed, followed by a single division.

The dip and si3p areas of interest must be of identical ''x'' and ''y'' dimensions. The image referenced by si3p is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

The second through fifth image frame buffers are averaged into the second buffer. 

    pxip8_averagebufs(NULL,
                      #if 1       // w. XCLIB
                        pxd_defineImage3(1,2,5,0,0,-1,-1,"Default"),
                        pxd_defineImage(1,2,0,0,-1,-1,"Default"));
                      #else       // w. SVOBJ,4MOBJ,XCOBJ
                        pxd_defimage3(2,5,0,0,-1,-1),
                        pxd_defimage(2,0,0,-1,-1));
                      #endif
Tile Image Sequence --- pxip8_seqtile



Summary 
int pxip8_seqtile(abortp,sip,dip,overlap,framesize,bordersize,frame,background,aspect,mode,zdim);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage3    *sip;           // source images
struct  pximage     *dip;           // destination image
pxcoord_t           overlap;        // zdim of sip which is same as dip, or -1.
struct  pxy         *framesize;     // frame width & height
struct  pxy         *bordersize;    // border width & height
uint                frame[];        // pixel value(s) of frame
uint                background[];   // pixel value(s) of border/background
double              aspect;         // reserved. should be 0
int                 mode;           // reserved. should be 'b'
int                 zdim;           // reserved. should be 0



Description

The images in the sequence referenced by sip are ''tiled'', i.e. reduced in size and positioned without overlap, into the destination image referenced by ''dip''.

Each tiled image is surrounded by a frame, against a background. The frame has width framesize->x and height framesize->y with pixel value frame (i.e. frame[0] for monochrome images, frame[0] through frame[2] for three component color images, etc). Each tile, framed, image is set against a background of minimal width bordersize->x and minimal height bordersize->y with pixel value border. The actual border may be larger, as the border value is also used to fill unused areas of dip.

The pxip8_seqtile attempts, to the extent possible, to maintain the aspect ratio of the original images as they are reduced and tiled. Thus, the position and size of the tiled images will vary according to relationship of the dimension of each image in sip versus the dimensions of dip, as well as varying according to the number if images in the sip sequence. Because maintenance of aspect ratio is given priority, parts of dip may be unused, although still filled with the background pixel value. For example, a six image sequence could be tiled as two rows of three, three rows of two, a row of four and a partial row of two, or even as one row of six or one column of six; according to the relative dimensions.

The dip may overlap with sip, the overlap must provide the z coordinate of the image (slice) of sip which is identical to dip. If sip and dip do not overlap, the overlap must be -1.

The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters. Or, unable to tile the sip sequence into dip, e.g. if there are more images in sip than there are pixels in dip.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

13. File Load and Saves

BMP File, Load Image --- pxio8_bmpread
AVI File, Load Image Sequence --- pxio8_avireadseq
AVI File, Load Image Sequence --- pxio8_aviread



Summary 
int pxio8_bmpread(abortp, dip, paldip, pathname, windp, mode);
int pxio8_avireadseq(abortp, dip3, paldip, pathname, subfile, windp, mode);
int pxio8_aviread(abortp, dip, paldip, pathname, subfile, windp, mode);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *dip;           // Image & AOI to be loaded
struct pximage3     *dip3;          // Image sequence & AOI to be loaded
struct pximage      *paldip;        // Palette to load, or NULL
const char          *pathname;      // File path name
long                subfile;        // Sub image index within AVI file
struct pxywindow    *windp;         // Aoi of file to load, or NULL
int                 mode;           // 'n': Nearest neighbor, 'b': Bilinear
                                    // 0x100: convert to color space



Description

For pxio8_bmpread, the file pathname, in the Windows Device Independent Bitmap File format, is loaded into the image referenced by dip. For pxio8_avireadseq or pxio8_aviread the file pathname, in the Windows Video File format (AVI 1.0 or 2.0), is loaded into the image sequence referenced by dip3 or dip, respectively. Windows Device Independent Bitmap files typically have a ''.bmp'' or ''.dib'' suffix, Windows Video files typically have a ''.avi'' suffix, although pxio8_bmpread, pxio8_avireadseq, nor pxio8_aviread requires, or forces, any specific suffix.[6] If the file pathname has a palette which is required for interpretation of pathname's pixels, the palette is optionally loaded into the image referenced by paldip; which should have 3 pixies per pixel, an ''image'' height of 1, and a width equal to the number of palette entries.

BMP and AVI format files may be uncompressed or utilize various compression techniques (i.e. codecs). The pxio8_bmpread, pxio8_avireadseq, and pxio8_aviread are not intended to load and view all BMP or AVI format files, but will, of course, load files previously saved by pxio8_bmpwrite, pxio8_aviwriteseq, as well as other files using similar options.

To allow the most convenient loading of BMP and AVI files, pxio8_bmpread, pxio8_avireadseq, and pxio8_aviread provide dimensional conversions (i.e. width and height), color conversions (i.e. RGB to intensity, or index+palette to RGB), and pixel precision conversions (e.g. 1 bit per pixie to 8 bits per pixie, or vice versa). Similar conversions allow convenient loading of the file's palette into the provided paldip.

Each AVI file may contain multiple images. For pxio8_avireadseq the subfile is loaded into the first image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z), the subfile+1, is loaded into the second image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z+1), etc. For pxio8_aviread the subfile is loaded into the image referenced by dip. For pxio8_avireadseq and pxio8_aviread all images within the file are expected to be of the same dimensions.


Dimensional Conversions. The windp references a ''struct pxywindow'' which defines an AOI within the image file; the image file's AOI is loaded into the image area of interest referenced by dip. If windp=NULL, the entire image file is loaded into the image area of interest referenced by dip. In either case, if the dimensions of the file AOI being loaded differ from the dimensions of the area of interest referenced by dip, the image is resized as it is loaded; if (mode&0xFF)='n', image resizing is done by nearest neighbor, if (mode&0xFF)='b', image resizing is done by bilinear interpolation. Resizing of the palette, if required, is always done by nearest neighbor.


Color Conversions. BMP or AVI files can have 24 bit RGB 3-valued pixels, or 1, 4, or 8 bit 1-valued pixel indices into a palette of 24 bit RGB pixels. If the image referenced by dip has three pixies per pixel and the BMP or AVI file has pixel indices plus a palette, the pixels are converted via the palette to RGB values and loaded into dip. If the image referenced by dip has one pixie per pixel and the BMP or AVI file has 24 bit RGB pixels, the pixels are converted to intensity values and loaded into dip. If mode&0x100 and dip->d.pixelhint!=PXHINTNONE, the pixels are converted to the dip->d.pixelhint color space and loaded into dip. The paldip is loaded only when the image referenced by dip has one pixie per pixel and the BMP or AVI file has pixel indices plus a palette.

Preferably, the dip and/or paldip should be of type PXHINTBGR; if of type PXHINTRGB the pixels are converted from BGR format used in the BMP or AVI file. Other color types are not converted, the pixels are loaded as if they were BGR values.


Precision Conversions. Each pixie, of both the image and the palette, if used, is converted by conserving the most significant bits if the pixie has excessive bits, or adding least significant bits of zero if pixie has insufficient bits (i.e. most significant bit alignment).

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

1
Image and palette loaded.

0
Image loaded, no palette loaded.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File can't be found.

PXERFILEFORM
File not valid BMP format.

PXERNOMODE
BMP or AVI option, such as compression, not currently supported.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_bmpload or the XCLIB's pxd_loadBmp provides an easy method of loading an frame grabber's frame buffer and the associated lookup table (if any) without having to construct the paldip. The dimensions of an image in a file, useful for the optional windp, can be obtained with pxio8_fileinfo.

BMP File, Save Image --- pxio8_bmpwrite
AVI 1.0 File, Save Image Sequence --- pxio8_aviwriteseq
AVI 1.0 File, Save Image Sequence --- pxio8_aviwriteseq2
AVI 2.0 File, Save Image Sequence --- pxio8_aviodmlwriteseq
AVI 1.0 File, Save Sequence - Init --- pxio8_aviwriteseqinit
AVI 2.0 File, Save Sequence - Init --- pxio8_aviodmlwriteseqinit
AVI x.0 File, Save Sequence - Add Image --- pxio8_aviwriteseqadd
AVI x.0 File, Save Sequence - Done --- pxio8_aviwriteseqdone



Summary 
int pxio8_bmpwrite(abortp, sip, palsip, pathname, nbits, parmp);
int pxio8_aviwriteseq(abortp, sip3, palsip, pathname, nbits, parmp);
int pxio8_aviodmlwriteseq(abortp, sip3, palsip, pathname, nbits, parmp);
int pxio8_aviwriteseq2(abortp, sip3, palsip, pathname, nbits,
                       framecnt, framesecs, biXPelsPerMeter, biYPelsPerMeter,
                       rsvd1, rsvd2, rsvd3, rsvd4);


int pxio8_aviwriteseqinit    (abortp, handlep, pathname, sip, palsip, nbits, parmp, nimages);
int pxio8_aviodmlwriteseqinit(abortp, handlep, pathname, sip, palsip, nbits, parmp, nimages);
int pxio8_aviwriteseqadd     (abortp, handlep, filename, sip, palsip, nbits, parmp);
int pxio8_aviwriteseqdone    (abortp, handlep, filename);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage3     *sip3;          // Image sequence & AOI to save
struct pximage      *palsip;        // Palette to save, or NULL
const char          *pathname;      // File path name
int                 nbits;          // Bits per pixie to save: 1, 4, 8
                                    // ignored if sip or sip3 is RGB
struct pximfileinfo *parmp;         // Additional parms, or for pxio8_bmpwrite
                                    // only may be NULL for default


uint                framecnt;       // See pximfileinfo.fi.bmp.framecnt
uint                framesecs;      // See pximfileinfo.fi.bmp.framesecs
long                biXPelsPerMeter;// See pximfileinfo.fi.bmp.biXPelsPerMeter
long                biYPelsPerMeter;// See pximfileinfo.fi.bmp.biYPelsPerMeter
int                 rsvd1;          // Reserved, should be 0
int                 rsvd2;          // Reserved, should be 0
int                 rsvd3;          // Reserved, should be 0
int                 rsvd4;          // Reserved, should be 0




long                nimages;        // Number of images to be saved
void                **handlep;      // *NULL, becomes *handle to mapping state




struct  pximfileinfo {              // only members used in this context shown
    union {
      struct {
        uint    framecnt;           // frame period is ...
        uint    framesecs;          // ... framesecs/framecnt (AVI only)
        ...
        ulong   compress;           // 0 or FOURCC('D','I','B',' '): bitmap codec
                                    // FOURCC('M','J','P','G'): JPEG codec (AVI only)
        ...
        long    biXPelsPerMeter;    // x resolution
        long    biYPelsPerMeter;    // y resolution
        ...
        uint16  aviEncodeMode;      // 'f': float mode; 'i': int mode (AVI MJPG only)
                                    // 0: same as 'f' for compatibility
        int     aviQuality;         // quality, percentage*10         (AVI MJPG only)
      } bmp;
    } fi;
    union {
      struct {                      // AVI only:
        char    *creationdate;      // creation date, "1553-05-3" format, or NULL
        char    *software;          // name of creating pgm, or NULL
        char    *comments;          // general comments, or NULL
        char    *copyright;         // copyright notice, or NULL
      } avi;
    } fs;
};



Description

For pxio8_bmpwrite, the content of the image referenced by sip is saved to file pathname in the Windows Device Independent Bitmap File format. For pxio8_aviwriteseq and pxio8_aviwriteseq2 the content of the image sequence referenced by sip3 is saved to file pathname in the Windows Video File format (AVI 1.0). For pxio8_aviodmlwriteseq the content of the image sequence referenced by sip3 is saved to file pathname in the Windows Video File format (AVI 2.0). Windows Device Independent Bitmap files typically have a ''.bmp'' or ''.dib'' suffix, Windows Video files typically have a ''.avi'' suffix, although neither pxio8_bmpwrite, pxio8_aviwriteseq, pxio8_aviwriteseq2 pxio8_aviodmlwriteseq, pxio8_aviodmlwriteseqinit nor pxio8_aviwriteseqinit requires, or forces, any specific suffix.[7] Any existing file pathname is deleted and a new file pathname created.

The pxio8_aviwriteseqinit, pxio8_aviwriteseqadd, and pxio8_aviwriteseqdone also allow saving an image sequence, allowing incremental addition of the content of the image referenced by sip to file pathname in the Windows Video File format (AVI 1.0); the pxio8_aviwriteseqinit initializing the feature, deleting any existing file pathname and creating a new file pathname, each invocation of the pxio8_aviwriteseqadd adding a single image, and the pxio8_aviwriteseqdone terminating the feature. The pxio8_aviodmlwriteseqinit, pxio8_aviwriteseqadd, and pxio8_aviwriteseqdone also allow saving an image sequence, allowing incremental addition of the content of the image referenced by sip to file pathname in the Windows Video File format (AVI 2.0). The nimages parameter to pxio8_aviwriteseqinit predicts the number of images to be added; an accurate prediction, or a prediction slightly higher, is marginally more efficient. The nimages parameter to pxio8_aviodmlwriteseqinit specifies a number greater than or equal to the number of images to be added; an error may occur if more than nimages is added.

If the image referenced by sip (or sip3) has three pixies (pixel value components) per pixel, a BMP (or AVI) file of RGB 24 bit pixels is created. Each pixie of sip (or sip3) is converted to 8 bits, conserving the most significant bits if pixies have more than 8 bits, or adding least significant bits of zero if pixies have less than 8 bits (i.e. most significant bit alignment). Preferably, the sip (or sip3) should be of type PXHINTBGR; if of type PXHINTRGB the pixels are converted to the BGR format required in the BMP file. Other color types are not converted, the pixels are saved as if they were BGR values. The palsip is ignored.

If the image referenced by sip (or sip3) has one pixie (pixel value components) per pixel, a BMP (or AVI) file of 1, 4, or 8 bit pixel indices, with a palette of 24 bit RGB colors, is created. Each pixie of sip (or sip3) is converted to nbits bits, where nbits is 1, 4, or 8, by most significant bit alignment. If palsip is NULL, an identity palette is saved (e.g. pixel value 45 is paletted to RGB color [45,45,45]). Otherwise palsip is expected to represent a palette for sip (or sip3); having 3 pixies per pixel, 8 bits per pixie, an ''image'' width of 2sip->d.u.i.bitsused and an ''image'' height of 1. A palsip with other than 8 bits per pixie is converted by most significant bit alignment, a palsip with different dimensions is resized by nearest neighbor. Preferably, the palsip should be of type PXHINTBGR; if of type PXHINTRGB the pixels are converted to the BGR format required in the BMP (or AVI) file. Other color types are not converted, the pixel values are saved as if they were BGR values.

The parmp may (for pxio8_bmpwrite), or must (for pxio8_aviwriteseq, pxio8_aviodmlwriteseq, pxio8_aviwriteseqinit, pxio8_aviodmlwriteseqinit), provide additional parameters. The parmp->fi.bmp.biXPelsPerMeter and parmp->fi.bmp.biYPelsPerMeter specify the image's size and/or aspect ratio. For pxio8_aviwriteseq, pxio8_aviodmlwriteseq, pxio8_aviwriteseqinit, pxio8_aviodmlwriteseqinit, and pxio8_aviwriteseqadd, the parmp->fi.bmp.framecnt divided by parmp->fi.bmp.framesecs should be the approximate frame rate of the sip3 sequence; this information may be used by a multi-media player to control the playback rate. For pxio8_aviwriteseq, pxio8_aviodmlwriteseq, pxio8_aviwriteseqinit, pxio8_aviodmlwriteseqinit, and pxio8_aviwriteseqadd, the parmp->fi.bmp.compress selects the coding; a value of 0 or FOURCC('D','I','B',' ') selects uncompressed Bitmap coding, a value of FOURCC('M','J','P','G') selects lossy JPEG coding. For JPEG coding, the parmp->fi.bmp.aviEncodeMode and parmp->fi.bmp.aviQuality selects the relative quality of the reconstructed image and the relative speed of coding; see pxio8_jpegwrite for further discussion of these options. For pxio8_aviwriteseq, pxio8_aviodmlwriteseq, pxio8_aviwriteseqinit, and pxio8_aviodmlwriteseqinit the parmp->fs.avi.software, parmp->fs.avi.description, parmp->fs.avi.creationdate, and/or parmp->fs.avi.copyright may reference NULL terminated textual strings to be stored with the image; any of these references may be NULL if inclusion of the textual string is not required.

The pxio8_aviwriteseq2 provides the same effect as pxio8_aviwriteseq, but allows the required fields of parmp to be passed as simple atomic parameters rather than a structure.

For pxio8_aviwriteseq, pxio8_aviwriteseq2, and pxio8_aviwriteseqinit, the saved file size may be as large as 4 GiByte. However, other programs may not be able to read AVI 1.0 files larger than 2 GiByte, depending upon which Microsoft API was chosen by that program. For pxio8_aviodmlwriteseq and pxio8_aviodmlwriteseqinit, the file size may be larger than 4 GiByte, if supported by the current operating system.

For pxio8_aviwriteseqinit, pxio8_aviodmlwriteseqinit, pxio8_aviwriteseqadd, and pxio8_aviwriteseqdone, the *handlep must initially be NULL; the handle to an internal state is ''returned'' at *handlep by pxio8_aviwriteseqinit or pxio8_aviodmlwriteseqinit, utilized by pxio8_aviwriteseqadd, and reset back to NULL by pxio8_aviwriteseqdone. The sip provided to pxio8_aviwriteseqinit or pxio8_aviodmlwriteseqinit is NOT saved, but rather provides information about the type of images to be later saved via pxio8_aviwriteseqadd. Each image provided via pxio8_aviwriteseqadd must have the same attributes: resolution, bit depth, color space, etc.

The sip (or sip3) can be a full image or an area of interest. The images referenced by sip (or sip3) and palsip are not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_bmpsave or the XCLIB's pxd_saveBmp provides an easy method of saving an frame grabber's frame buffer and the associated lookup table (if any) without having to construct the palsip.

Load Image from File, Unpacked Binary --- pxio8_binread
Load Image Sequence from File, Unpacked Binary --- pxio8_binreadseq
Save Image to File, Unpacked Binary --- pxio8_binwrite
Save Image Sequence to File, Unpacked Binary --- pxio8_binwriteseq



Summary 
int pxio8_binread(abortp, ip, pathname, skip);
int pxio8_binwrite(abortp, ip, pathname);
int pxio8_binreadseq(abortp, ip3, pathname, mode, skip, skip2);
int pxio8_binwriteseq(abortp, ip3, pathname, mode);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *ip;            // Image and area of interest
struct pximage3     *ip3;           // Image sequence and area of interest
const char          *pathname;      // File path name
int                 mode;           // Reserved, should be 0
off_t               skip;           // Initial offset, or 0
off_t               skip2           // Inter-image offset, or 0



Description

The content of the image referenced by ip (or image sequence referenced by ip3) is saved to, or loaded from, the file pathname as pixel data bytes in simple, binary, unpacked, format. For pxio8_binread (and pxio8_binreadseq) the image (sequence) is loaded; the file pathname is not modified. For pxio8_binwrite (and pxio8_binwriteseq) the image (sequence) is saved; any existing file pathname is deleted and a new file pathname written.[8]

For pxio8_binread and pxio8_binreadseq, the skip specifies an initial offset into the file; reading starts at the skip'th byte of the file. For pxio8_binreadseq, the skip2 specifies a recurring byte offset in the file between the the end of one image's data and the start of the next image's data.

The dimensions of the image area of interest are not saved or loaded, it is the user's responsibility to load an image file into the correctly sized area of interest.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


File Format. Pixels of the image area of interest are saved or loaded in the order of left to right and top to bottom. For pxio8_binwriteseq and pxio8_binreadseq, pixels of the image area of interest are saved or loaded in the order of left to right, top to bottom, and first image to last. Each pixel is saved or loaded using an integer number of bytes; for pixels with multiple component values, each component is saved or loaded using an integer number of bytes. For integer valued component values using fewer bits than the number of bytes would otherwise suggest, the significant bits are always right justified and higher order bits are zero. For multi-byte component values, the byte order is dependent upon the host architecture.

For example, for 8 bit ''uchar'' pixel monochrome images, each pixel is saved or loaded as a single byte, from left to right and top to bottom, the number of bytes saved or loaded to/from the file is the same as the number of pixels in the image area of interest referenced by ip. For 8 bit ''uchar'' pixel YCrCb images, each pixel is saved or loaded as a three bytes, with pixels saved or loaded from left to right and top to bottom.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels. Multi-byte values are stored in little-endian order (least significant byte first).



Returns

1
Operation complete.

0
Operation complete, but file read is larger than image area of interest.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File doesn't exist (read).

PXERNEWFILE
File can't be created (write).

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

PXERFILEFORM
File read is smaller than image area of interest.



Example

The first image frame buffer is saved to file ''xx.bin''. 

int     i;


i = pxio8_binwrite(NULL,
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1, 0, 0, -1, -1),
                   #endif
                   "xx.bin");
if (i < 0)
    printf("Error: %s", pxerrnomesg(i));
Load Image from File, Packed Binary --- pxio8_bin1read
Load Image Sequence from File, Packed Binary --- pxio8_bin1readseq
Save Image to File, Packed Binary --- pxio8_bin1write
Save Image Sequence to File, Packed Binary --- pxio8_bin1writeseq



Summary 
int pxio8_bin1read(abortp, ip, pathname, mode, skip);
int pxio8_bin1write(abortp, ip, pathname, mode);
int pxio8_bin1readseq(abortp, ip3, pathname, mode, skip, skip2);
int pxio8_bin1writeseq(abortp, ip3, pathname, mode);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *ip;            // Image and area of interest
struct pximage3     *ip3;           // Image sequence and area of interest
const char          *pathname;      // File path name
int                 mode;           // Bit 0: 0: pack lsb->msb
                                    //        1: pack msb->lsb
                                    // Bit 1: 0: r/w just 1 msb of pixel
                                    //        1: r/w all bits of pixel
off_t               skip;           // Initial offset, or 0
off_t               skip2           // Inter-image offset, or 0



Description

The content of the image referenced by ip (or image sequence referenced by ip3) is saved to, or loaded from, the file pathname as pixel data bytes in simple, binary, packed, format. For pxio8_bin1read (and pxio8_bin1readseq) the image (sequence) is loaded; the file pathname is not modified. For pxio8_bin1write (and pxio8_bin1writeseq) the image (sequence) is saved; any existing file pathname is deleted and a new file pathname written.[9]

For pxio8_bin1read and pxio8_bin1readseq, the skip specifies an initial offset into the file; reading starts at the skip'th byte of the file. For pxio8_bin1readseq, the skip2 specifies a recurring byte offset in the file between the the end of one image's data and the start of the next image's data.

The dimensions of the image area of interest are not saved or loaded, it is the user's responsibility to load an image file into the correctly sized area of interest.

If (mode&2)==0, only the most significant bit of each pixel component value is saved or loaded, when loading other bits are set to 0 (e.g. after loading, 8 bit monochrome pixels will have values of 0 or 128). If (mode&2)==1, all bits of each pixel value component are saved or loaded.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


File Format. Pixels of the image area of interest are saved or loaded in the order of left to right and top to bottom. For pxio8_bin1writeseq and pxio8_bin1readseq, pixels of the image area of interest are saved or loaded in the order of left to right, top to bottom, and first image to last. If (mode&1)==0, the bits of each pixel value component are packed into data bytes ordered from the least significant to the most significant bits; i.e. the bits of pixel 1 are to the ''left'' of the bits of pixel 0 (assuming both fit in one byte). If (mode&1)==1, the bits of each pixel value component are packed into data bytes ordered from the most significant to the least significant bits; i.e. the bits of pixel 1 are to the ''right'' of the bits of pixel 0 (assuming both fit in one byte). Each line of the image area of interest is saved or loaded as an integer number of bytes; pad bits are saved as necessary, or ignored upon loading.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.



Returns

1
Operation complete.

0
Operation complete, but file read is larger than image area of interest.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File doesn't exist (read).

PXERNEWFILE
File can't be created (write).

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

PXERFILEFORM
File read is smaller than image area of interest.
Binary File, Save Sequence - Init --- pxio8_binwriteseqinit
Binary File, Save Sequence - Add Image --- pxio8_binwriteseqadd
Binary File, Save Sequence - Done --- pxio8_binwriteseqdone



Summary 
int pxio8_binwriteseqinit(abortp, handlep, pathname, ip, mode, rsvd1, rsvd2, nimages);
int pxio8_binwriteseqadd (abortp, handlep, pathname, ip);
int pxio8_binwriteseqdone(abortp, handlep, pathname);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *ip;            // Image and area of interest
const char          *pathname;      // File path name
int                 mode;           // Bit 8: 0: unpacked
                                    //        1: packed
                                    // Bit 0: 0: pack lsb->msb
                                    //        1: pack msb->lsb
                                    // Bit 1: 0: pack just 1 msb of pixel
                                    //        1: pack all bits of pixel
int                 rsvd1;          // Reserved, should be 0
int                 rsvd2;          // Reserved, should be 0
long                nimages;        // Reserved, should be 0
void                **handlep;      // *NULL, becomes *handle to mapping state



Description

The pxio8_binwriteseqinit, pxio8_binwriteseqadd, and pxio8_binwriteseqdone allow saving an image sequence by incremental addition of the content of the image referenced by ip to file pathname in a packed or unpacked binary format; the pxio8_binwriteseqinit initializing the feature, deleting any existing file pathname and creating a new file pathname, each invocation of the pxio8_binwriteseqadd adding a single image, and the pxio8_binwriteseqdone terminating the feature.

The *handlep must initially be NULL; the handle to an internal state is ''returned'' at *handlep by pxio8_binwriteseqinit, utilized by pxio8_binwriteseqadd, and reset back to NULL by pxio8_binwriteseqdone.

If (mode&0x100)==0, the file format is the same as pxio8_binwriteseq. If (mode&0x100)!=0, the file format is the same as pxio8_bin1writeseq, as per the two least significant bits of mode.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.



Returns

1
Operation complete.

0
Operation complete, but file read is larger than image area of interest.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created (write).

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

PXERFILEFORM
File read is smaller than image area of interest.
FITS File, Load Image --- pxio8_fitsread
FITS File, Load Image Sequence --- pxio8_fitsreadseq



Summary 
int pxio8_fitsread(abortp, dip, rsvd1, pathname, rsvd2, rsvd3, windp, mode);
int pxio8_fitsreadseq(abortp, dip3, rsvd1, pathname, subfile, rsvd3, windp, mode);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *dip;           // Image & AOI to be loaded
struct pximage3     *dip3;          // Image sequence & AOI to be loaded
struct pximage      *rsvd1;         // Reserved, should be NULL
const char          *pathname;      // File path name
long                rsvd2;          // Reserved, should be 0
long                rsvd3;          // Reserved, should be 0
long                subfile;        // Sub image index within file
struct pxywindow    *windp;         // Aoi of file to load, or NULL
int                 mode;           // 'n': Nearest neighbor, 'b': Bilinear
                                    // 0x100: convert to color space



Description

The file pathname, in the Flexible Image Transport System format, is loaded into the image referenced by dip (or image sequence referenced by dip3). Such files typically have a ''.fts'' suffix, although pxio8_fitsread and pxio8_fitsreadseq does not require, or force, any specific suffix.[10]

Some FITS format files may not contain a simple image, or may contain nonimage data; the general FITS format allows storage and retrieval of data arrays with up to 999 dimensions. The pxio8_fitsread and pxio8_fitsreadseq is not intended to load and view all FITS format files, but will, of course, load files previously saved by pxio8_fitswrite and pxio8_fitswriteseq as well as other files with a similar design.

To allow the most convenient loading of FITS image files, pxio8_fitsread and pxio8_fitsreadseq provides dimensional conversions (i.e. image width and height), color conversions (e.g. RGB to monochrome, or vice versa), and pixel precision conversions (e.g. 1 bit per pixie to 8 bits per pixie, or vice versa).

Each FITS file may contain multiple images. For pxio8_pgmreadseq, the subfile, is loaded into the first image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z), the subfile+1, is loaded into the second image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z+1), etc.


Dimensional Conversions. The windp references a ''struct pxywindow'' which defines an AOI within the image file; the image file's AOI is loaded into the image area of interest referenced by dip. If windp=NULL, the entire image file is loaded into the image area of interest referenced by dip. In either case, if the dimensions of the file AOI being loaded differ from the dimensions of the area of interest referenced by dip, the image is resized as it is loaded; if (mode&0xFF)='n', image resizing is done by nearest neighbor, if (mode&0xFF)='b', image resizing is done by bilinear interpolation.

For pxio8_fitsreadseq, the windp represents an a two-dimensional AOI within one such image. Each image in the file is loaded into one ''z-slice''[11] of the three-dimensional area of interest referenced by dip3, resized as described above. There is no resizing from image to image (i.e. along the Z axis).


Color & Grey Level Conversions. The FITS file may specify the image's color space, via non-standard extensions supported by pxio8_fitsread, pxio8_fitsreadseq, pxio8_fitswrite, and pxio8_fitswriteseq.

If the FITS file does not specify the image's color space, then the dip or dip3 is expected to have the same number of pixies per pixel as the FITS image; the FITS pixies are loaded into dip pixies in the order presented, and without regard to the stated image type (i.e. the PXHINT*) of dip.

Otherwise, if the image referenced by dip or dip3 has one pixie per pixel the pixels are converted to intensity values and loaded into dip or dip3. If mode&0x100 and dip->d.pixelhint!=PXHINTNONE, the pixels are converted to the dip->d.pixelhint color space and loaded into dip or dip3.


Precision Conversions. Each pixie is converted by conserving the most significant bits if the pixie has excessive bits, or adding least significant bits of zero if pixie has insufficient bits (i.e. most significant bit alignment).

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image loaded.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File can't be found.

PXERFILEFORM
File not valid FITS format.

PXERNOMODE
FITS option, such as data organization, not currently supported.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The dimensions of an image in a file, useful for the optional windp, can be obtained with pxio8_fileinfo.

FITS File, Save Image --- pxio8_fitswrite
FITS File, Save Image Sequence --- pxio8_fitswriteseq
FITS File, Save Sequence - Init --- pxio8_fitswriteseqinit
FITS File, Save Sequence - Add Image --- pxio8_fitswriteseqadd
FITS File, Save Sequence - Done --- pxio8_fitswriteseqdone



Summary 
int pxio8_fitswrite(abortp, sip, rsvd1, pathname, nbits, rsvd2, rsvd3, rsvd4, parmp);
int pxio8_fitswriteseq(abortp,sip3, pathname, nbits, subfile, parmp);


int pxio8_fitswriteseqinit(abortp, handlep, pathname, sip3, bits, subfile, parmp, nimages);
int pxio8_fitswriteseqadd(abortp, handlep, pathname, sip, bits, parmp);
int pxio8_fitswriteseqdone(abortp, handlep, pathname);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage      *rsvd1;         // Reserved, should be NULL
const char          *pathname;      // File path name
int                 nbits;          // Bits per pixie to save
int                 rsvd2;          // Reserved, should be 0
long                rsvd3;          // Reserved, should be 0
long                rsvd4;          // Reserved, should be 0
long                subfile;        // Reserved, should be 0
struct pximfileinfo *parmp;         // Additional parms, or NULL for default
long                nimages;        // Reserved, should be 0
void                **handlep;      // *NULL, becomes *handle to mapping state




struct  pximfileinfo {              // only members used in this context shown
    union {
      struct {
        uchar   colorpacked;        // bit0=1: color saved packed, not planar
                                    // bit1=1: mono data saved as 2-d, not 3-d
      } fits;
    } fi;
    union {
      struct {
        char    *date;              // .. or current date used if NULL
        char    *observer;          // .. or NULL
        char    *object;            // .. or NULL
        char    *origin;            // .. or NULL
        char    *date_obs;          // .. or NULL
        char    *comment;           // .. multiline - with \n's, or NULL
        char    *history;           // .. multiline - with \n's, or NULL
      } fits;
    } fs;
};



Description

For pxio8_fitswrite, the contents of the image referenced by sip is saved to file pathname in the Flexible Image Transport System format. For pxio8_fitswriteseq, the content of the image sequence referenced by sip3 is saved to file pathname in the Flexible Image Transport System format. FITS files typically have a ''.fts'' suffix, although pxio8_fitswrite and pxio8_fitswriteseq does not require, or force, any specific suffix.[12] Any existing file pathname is deleted and a new file pathname created.

The pxio8_fitswriteseqinit, pxio8_fitswriteseqadd, and pxio8_fitswriteseqdone also allow saving an image sequence, allowing incremental addition of the content of the image referenced by sip to file pathname in the Flexible Image Transport System format; the pxio8_fitswriteseqinit initializing the feature, deleting any existing file pathname and creating a new file pathname, each invocation of the pxio8_fitswriteseqadd adding a single image, and the pxio8_fitswriteseqdone terminating the feature.

The pixies (pixel value component) of sip are converted to nbits bits, where 1<=nbits<=16, conserving the most significant bits if pixies have more than nbits bits, or adding least significant bits of zero if pixies have less than nbits bits (i.e. most significant bit alignment). Alternately, nbits may be negative, -16<=nbits<=-1, adding most significant bits of zero if pixies have less than -nbits bits (i.e. least significant bit alignment).

The pixels of the image referenced by sip or sip3 are saved without conversion to a different color space.

If sip->d.pixelhint!=PXHINTNONE, that color space specification is saved. If sip->h.widthunits!=PXUNITUNKNOWN and sip->h.heightunits!=PXUNITUNKNOWN, those pixel width, height, and units are saved. The FITS standard does not provide card types for this information — this information is saved as ''BLANK'' flagged, comment cards.

The parmp may provide additional parameters. If parmp->fi.fits.colorpacked&1≠0, the image is saved as a data array in packed format with dimensions of PxWxH, or PxWxHxZ for sequence (number of pixies per pixel, number of pixels per line, number of pixels per column, number of images); otherwise the image is saved as a data array in planar format with dimensions of WxHxP or WxHxPxZ for sequence. For images with more than one pixie per pixel, saving in packed format may be quicker, but saving in planar format is more typical of FITS files. If parmp->fi.fits.colorpacked&2≠0, and pixels have a single component value, the image is saved as a data array with dimensions of WxH or WxHxZ for sequence, otherwise the image is saved as a data array in planar format (WxHx1 or WxHx1xZ) or packed format (1xWxH or 1xWxHxZ). All choices result in a valid FITS format file.

If parmp->fs.fits.date is NULL, the current data and time are saved as a FITS ''DATE'' card. Otherwise the specified parmp->fs.fits.date is saved as the image's date and time of creation; use of the standard FITS date and time format for parmp->fs.fits.date is strongly recommended.

The parmp->fs.fits.observer, parmp->fs.fits.object, parmp->fs.fits.origin, parmp->fs.fits.date_obs, parmp->fs.fits.comment and/or parmp->fs.fits.history may reference NULL terminated textual strings to be saved with the image as FITS ''OBSERVER'', ''OBJECT'', ''ORIGIN'', ''DATE-OBS'', ''COMMENT'' and ''HISTORY'' cards, respectively. Any of these references may be NULL if inclusion of the textual string is not required. The parmp->fs.fits.comment and parmp->fs.fits.history string may include newline ('\n') characters, each portion of the string delimited by a newline is saved as a separate FITS ''COMMENT'' or ''HISTORY'' card, respectively.

For pxio8_fitswriteseqinit, pxio8_fitswriteseqadd, and pxio8_fitswriteseqdone, the *handlep must initially be NULL; the handle to an internal state is ''returned'' at *handlep by pxio8_fitswriteseqinit, utilized by pxio8_fitswriteseqadd, and reset back to NULL by pxio8_fitswriteseqdone. The sip3 provided to pxio8_fitswriteseqinit is NOT saved, but rather provides information about the type of images to be later saved via pxio8_fitswriteseqadd. Each image provided via pxio8_fitswriteseqadd should have the same attributes: resolution, bit depth, color space, etc. The parmp->fs.fits.date_obs may differ for each image; the FITS standard does not provide card types for this information — they are saved as ''BLANK'' flagged, comment cards. The nimages parameter to pxio8_fitswriteseqinit is a ''soft''limit on the number of images to be added; an accurate prediction, or a prediction slightly higher, may be marginally more efficient. The nimages is a ''hard'' limit on the number of unique parmp->fs.fits.date_obs that can be saved.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Image File, Obtain Information --- pxio8_fileinfo
Image File, Release Information --- pxio8_fileinfodone



Summary 
int  pxio8_fileinfo(pathname, infop, subfile, mode);
void pxio8_fileinfodone(infop);


const char          *pathname;      // File path name
struct pximfileinfo *infop;         // Result information
long                subfile;        // For TIFF: sub image within file
int                 mode;           // Reserved, should be 0




struct  pximfileinfo {
    //
    // Common Info.
    //                              // cold: only reported as file info
    struct  pxywindow  imdim;       // as in a pximage struct
    struct  pxyzwindow imdim3;      // as in a pximage struct
    struct  pximagedata d;          // as in a pximage struct
    struct  pximagehints h;         // as in a pximage struct


    //
    // Format specific info
    //
    char    type[4];                // "tif", "bmp", "avi", "jpg", "fts",
                                    // "pgm", "ppm", "pbm", etc.


    union {
      //
      // Info for TIFF and BigTIFF files
      //
      struct {                      // hot: values used on file create
        int     xresolution[2];     // x resolution ratio. 0/0 if unused
        int     yresolution[2];     // y resolution ratio  0/0 if unused
        int     resolutionunit;     // as per defines, iff xres, yres used
        int     compression;        // PXIMTIFF_Compress_NONE, PACKBITS, etc
        ulong   maxstripsize;       // advisory, 0: default (create only)


                                    // cold: only reported as file info
        int     bitspersample[4];   // as per tiff spec
        int     sampleformat[4];    // as per tiff spec
        int     palette;            // !0: there is a color palette
        long    subfiles;           // number of images in file
        long    subfile;            // of which this is # ..


                                    // hot: values used on file create
        int     version;            // PXIMTIFF_Version_* or 0 for classic
      } tiff;


      //
      // Info for BMP files and AVI files
      //
      struct {                      // hot: values used on file create
        uint    framecnt;           // frame period is ...
        uint    framesecs;          // ... framesecs/framecnt (AVI only)


                                    // cold: only reported as file info
        int     biPlanes;           // as per bmp spec
        int     biBitCount;         // as per bmp spec
        int     palette;            // !0: pixels are indexes into lut
                                    //  0: pixels are RGB data


                                    // BMP cold: only reported as file info
        ulong   compress;           //  0: uncompressed
                                    // !0: compressed
                                    // AVI hot: values used on file create
                                    //                       0: DIB codec
                                    // FOURCC('D','I','B',' '): DIB codec
                                    // FOURCC('M','J','P','G'): MJPG codec


                                    // hot: values used on file create
        long    biXPelsPerMeter;    // x resolution
        long    biYPelsPerMeter;    // y resolution


                                    // cold: only reported as file info
        ulong   aviTotalFrames;     // number of images in file (AVI only)
        ulong   aviVersion;         // AVI Version (AVI only)
                                    //  1000: 1.0
                                    //  2000: 2.0 (OpenDML)


                                    // hot: values used on file create
        uint16  aviEncodeMode;      // see jpeg.encodeMode (AVI MJPG only)
        int     aviQuality;         // see jpeg.quality    (AVI MJPG only)
      } bmp;


      //
      // Info for JPEG files
      //
      struct {                      // hot: values used on file create
        int     quality;            // quality, percentage*10. Not reported
        uint16  dotsPerHUnit;       // x resolution
        uint16  dotsPerVUnit;       // y resolution
        uint16  dotsUnits;          // resolution: 0: ratio, 1: inch, 2: cm
        uint16  encodeMode;         // hot: 'f', float mode; 'i', int mode,
                                    //      0, same as 'f' for compatibility
      } jpeg;
      //
      // Info for FITS files
      //
      struct {                      // cold: only reported as file info
        double  datamin, datamax;   // no default, NaN if not specified
        double  bzero, bscale;
        uint16  naxis[5];           // # of dimensions and dimensions
        uint16  naxishi[5];         // ditto, high 16 bits
        short   bitpix;


                                    // hot: values used on file create
        uchar   colorpacked;        // bit0=1: color saved packed, not planar
                                    // bit1=1: mono data saved as 2-d, not 3-d
                                    // cold: only reported as file info
        long    subfiles;           // number of images in file
      } fits;
      //
      // Info for PBM/PGM/PPM files
      //
      struct {                      // cold: only reported as file info
        long    subfiles;           // number of images in file
        long    subfile;            // of which this is # ..
                                    // 'subfile' is not used


                                    // hot: values used on file create
        uchar   magic;              // '4', '5', '6' to select pbm/pgm/ppm
                                    // or 0 for default
                                    // (only 0 currently supported)
      } pgm;
        ...
    } fi;


    union {
      struct {                      // hot: values used on file create
        char    *datetime;          // date/time, tiff format, or NULL
        char    *software;          // name of creating pgm, or NULL
        char    *description;       // description of image, or NULL
        char    *copyright;         // copyright notice, or NULL
      } tiff;


      struct {                      // hot: values used on file create
        char    *comments[3];       // comments, or NULLs
      } jpeg;


      struct {                      // hot: values used on file create
        char    *date;              // .. or current date used if NULL
        char    *observer;          // .. or NULL
        char    *object;            // .. or NULL
        char    *origin;            // .. or NULL
        char    *date_obs;          // .. or NULL
        char    *comment;           // .. multiline - with \n's, or NULL
        char    *history;           // .. multiline - with \n's, or NULL
      } fits;                       // all w/out enclosing single quotes


      struct {                      // hot: values used on file create
        char    *creationdate;      // creation date, "1553-05-3" format, or NULL
        char    *software;          // name of creating pgm, or NULL
        char    *comments;          // general comments, or NULL
        char    *copyright;         // copyright notice, or NULL
      } avi;


      struct {                      // hot: values used on file create
        char    *comments[4];       // comments
      } pgm;
        ...
    } fs;
};



Description

The pxio8_fileinfo obtains the image dimensions and auxiliary information about an image stored in file pathname, returning the information in the structure referenced by infop. The pxio8_fileinfo currently supports TIFF, BigTIFF, JPEG/JFIF, BMP, AVI, FITS, and Portable Map image file formats. The subfile, for subfile≥0, selects the subfile, or subimage, within pathname for which information is to be obtained; each subfile of TIFF and BigTIFF could have different image dimensions, pixels, compression, and time stamps; each subfile of FITS could have different image time stamps; the subfile should be 0 for other format files.

The pxio8_fileinfo does not depend upon the file pathname's suffix for identification of different file formats. It will correctly identify BMP images with a ''.tif'' suffix, or TIFF images with a ''.txt'' suffix, etc.

If the file pathname is a valid, supported, image file: The infop->imdim, infop->d, and infop->h describe the image file's dimensions, pixels, and aspect ratio in the same manner as the pximage.imdim, pximage.d and pximage.h. Specifically, the file's image is infop->imdim.se.x pixels wide and infop->imdim.se.y pixels high. Each pixel has infop->d.pixies color components, each of which is of data type infop->d.pixietype (a PXDAT* value), has infop->d.u.i.bitsused bits used (for integer valued pixels), interpreted as per the infop->d.pixiehint color gamut (a PXHINT* value). See pximage for a description of the PXDAT* and PXHINT* values.


TIFF. For image files in TIFF and BigTIFF format, the infop->type will be "tif", and the infop->fi.tiff and infop->fs.tiff provide additional information peculiar to TIFF files. Familiarity with the TIFF file formats is helpful in understanding the interpretation of the additional information.

The infop->fi.tiff.version is PXIMTIFF_Version_Tiff for TIFF or PXIMTIFF_Version_BigTiff for BigTIFF. The infop->fi.tiff.xresolution and infop->fi.tiff.yresolution provides the image's horizontal and vertical resolution, each as a ratio and in units of infop->fi.tiff.resolutionunit (a PXIMTIFF_ResUnit_* value); or these members will be zero if the TIFF file doesn't specify resolution. The infop->fi.tiff.compression is PXIMTIFF_Compress_NONE or other PXIMTIFF_Compress_* value if the image data is uncompressed, or compressed, respectively. See pxio8_tifwrite for a description of the PXIMTIFF_ResUnit_* and PXIMTIFF_Compress_* values.

The infop->fi.tiff.palette is 0 if no palette is attached to the image, otherwise infop->fi.tiff.palette is a nonzero value. The infop->fi.tiff.subfiles is the number of subfiles, or images, contained within file pathname. The infop->fi.tiff.bitspersample[] is the number of bits per pixel value component of the image[13] (the infop->d.u.i.bitsused is the maximum of the infop->fi.tiff.bitspersample[]).

The infop->fs.tiff.datetime, infop->fs.tiff.software, infop->fs.tiff.description, and infop->fs.tiff.copyright each provide the stated information from the TIFF file, or will be NULL if unspecified within the TIFF file.


BMP or AVI. For image files in BMP or AVI format, the infop->type will be "bmp" or "avi", respectively, and the infop->fi.bmp provides additional information peculiar to BMP and AVI files. Familiarity with the BMP file format is helpful in understanding the interpretation of the additional information.

The infop->fi.bmp.biPlanes and infop->fi.bmp.biBitCount are the values of the same named fields in the BMP header. The infop->fi.bmp.compression is 0 if the image data is uncompressed, otherwise infop->fi.bmp.compression is a nonzero value. The infop->fi.bmp.palette is 0 if no palette is attached to the image, otherwise infop->fi.tiff.palette is a nonzero value and pixels are RGB values. The infop->fi.bmp.biXPelsPerMeter and infop->fi.bmp.biYPelsPerMeter are the values of the same named fields in the BMP header.

For AVI format files, the ratio of infop->fi.bmp.framecnt and infop->fi.bmp.framesecs specify the frame period, in seconds. The infop->aviTotalFrames specifies the number frames, or images, contained within file pathname.


JPEG/JFIF. For image file in JPEG/JFIF format, the infop->type will be "jpg" and the infop->fi.jpeg and infop->fs.jpeg provides additional information peculiar to JPEG/JFIF files. Familiarity with the JPEG/JFIF file format is helpful in understanding the interpretation of the additional information.

The infop->fi.jpeg.dotsPerHUnit and infop->fi.jpeg.dotsPerVUnit specify the horizontal and vertical resolution, with the units specified by infop->fi.jpeg.dotsUnits. Values for infop->fi.jpeg.dotsUnits follow JPEG/JFIF conventions: 0 for unitless ratio, 1 for inches, and 2 for centimeters.

The infop->fs.jpeg.comments[0], infop->fs.jpeg.comments[1], etc. provides the stated information from the JPEG/JFIF file, or will be NULL if unspecified within the JPEG/JFIF file.


FITS. For image file in FITS format, the infop->type will be "fts" and the infop->fi.fits and infop->fs.fits provides additional information peculiar to FITS files. Familiarity with the FITS file format is helpful in understanding the interpretation of the additional information.

The infop->fi.fits.naxis[0] is the number of dimensions of the data array (FITS ''NAXIS''); infop->fi.fits.naxis[1] and infop->fi.fits.naxishi[1] through infop->fi.fits.naxis[5] and infop->fi.fits.naxishi[5] are the first 5 dimensions (FITS ''NAXIS1'' through ''NAXIS5''). The infop->fi.fits.bitpix is the value specified in the FITS ''BITPIX'' card. The infop->fi.fits.datamin and infop->fi.fits.datamax are the values specified in the FITS ''DATAMIN'' and ''DATAMAX'' cards, respectively; if no such cards exist their values are NaN (i.e. eight bytes of 0xFF). The infop->fi.fits.bzero and infop->fi.fits.bscale are the values specified in the FITS ''BZERO'' and ''BSCALE'' cards, respectively; if no such cards exist their values are 0.0 and 1.0, respectively. The infop->fi.fits.colorpacked&1 describes whether the overall interpretation of the data array is that of packed format or planar format (e.g. 3x256x256 versus 256x256x3 for a RGB 256x256 image). The infop->fi.fits.colorpacked&2 describes whether the overall interpretation of a monochrome data array is that of 2-D data, or of 3-D ''color'' with one color component. The infop->fi.fits.subfiles is the number of subfiles, or images, contained within file pathname.

The infop->fs.fits.date, infop->fs.fits.date_obs, infop->fs.fits.observer, infop->fs.fits.object, infop->fs.fits.origin, infop->fs.fits.comment, and infop->fs.fits.history, each provides the stated information from the FITS file, or will be NULL if unspecified within the FITS file. The infop->fs.fits.comment is a concatenation of all FITS ''COMMENT'' cards with newline characters ('\n') added to delimit the end of one card and the start of the next. The infop->fs.fits.history is a concatenation of all FITS ''HISTORY'' cards with newline characters ('\n') added to delimit the end of one card and the start of the next.


PortableMap. For image file in Portable Map format, the infop->type will be "pgm", "ppm", or "pbm" for Portable Gray Map, Portable Pixel Map, or Portable Bit Map, respectively. The infop->fi.pgm.subfiles is the number of subfiles, or images, contained within file pathname. The infop->fs.pgm.comments[0], infop->fs.pgm.comments[1], etc. provides the stated information from the Portable Map file, or will be NULL if unspecified within the Portable Map file.


All Formats. The infop->fs strings, if any, are malloc'ed. The pxio8_fileinfodone should be invoked after pxio8_fileinfo, using the same infop to free the memory which pxio8_fileinfo has malloc'ed; any infop->fs pointers are set to NULL. The pxio8_fileinfodone is safe to use with an infop for which pxio8_fileinfo returned an error.


Supports


80x86
Any pixel type and precision.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERDOSIO
DOS/Windows/Linux I/O read error.

PXERNOFILE
File pathname doesn't exist.

PXERFILEFORM
File format invalid, or the subfile doesn't exist.

PXERNOMODE
File pathname is not a known, valid format.



Example

Information about an image file is obtained and displayed. 

struct  pximfileinfo info;
int     i;


if ((i = pxio8_fileinfo("xyz.xxx", &info, 0, 0)) < 0) {
    printf("Error: %s", pxerrnomesg(i));
} else {
    printf("File Name:\t%s\n", "xyz.xxx");
    printf(" File Format:\t%.4s\n", info.type);
    printf(" Image Width:\t%d\n", info.imdim.se.x);
    printf(" Image Height:\t%d\n", info.imdim.se.y);
    printf(" Pixies per Pixel:\t%d\n", info.d.pixies);
    printf(" Bits per Pixie:\t%d\n", info.d.u.i.bitsused);
    pxio8_fileinfodone(&info);
}
Image File, Obtain Information on Subfiles --- pxio8_fileinfoN



Summary 
int  pxio8_fileinfoN(pathname, info, infoN, subfile, mode);


const char          *pathname;      // File path name
struct pximfileinfo info[];         // Result information
size_t              infoN;          // dimension of 'info'
long                subfile;        // For TIFF, BigTIFF, FITS:
                                    // sub image within file
int                 mode;           // Reserved, should be 0




Description

The pxio8_fileinfoN obtains the image dimensions and auxiliary information about multiple images stored in file pathname, returning the information in the structures referenced by info. The information returned per image is identical to, and described by, pxio8_fileinfo.

The pxio8_fileinfoN currently supports the multiple images in TIFF, BigTIFF, and FITS image file formats. The subfile, for subfile≥0, selects the subfile, or subimage, within pathname for the first image for which information is to be obtained; information is obtained on images subfile+0, subfile+1, through subfile+infoN-1 filling info[0], info[1], through info[infoN-1], respectively.

For other file formats, pxio8_fileinfoN has the same effect as pxio8_fileinfo, returning information in info[0].

The pxio8_fileinfodone should be invoked after pxio8_fileinfoN, on each of info[0] through info[infoN-1], to free the memory which pxio8_fileinfoN has malloc'ed; any infop->fs pointers are set to NULL. The pxio8_fileinfodone is safe to use with an info for which pxio8_fileinfoN returned an error.


Supports


80x86
Any pixel type and precision.



Returns

≥0
The number of images for which information is returned. Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERDOSIO
DOS/Windows/Linux I/O read error.

PXERNOFILE
File pathname doesn't exist.

PXERFILEFORM
File format invalid, or the subfile doesn't exist.

PXERNOMODE
File pathname is not a known, valid format.
Load Image from File, Hex ASCII --- pxio8_hexread
Save Image to File, Hex ASCII --- pxio8_hexwrite



Summary 
int pxio8_hexread(abortp, ip, pathname);
int pxio8_hexwrite(abortp, ip, pathname, linedelim);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct  pximage     *ip;            // Image and area of interest
const char          *pathname;      // File path name
char                linedelim;      // Character written after each line, or 0



Description

The content of the image referenced by ip is saved (for pxio8_hexwrite) or loaded (for pxio8_hexread) to/from the file pathname as hexadecimal coded ASCII characters, in X/Y format. For pxio8_hexread, the file pathname is not modified; for pxio8_hexwrite any existing file pathname is deleted and a new file pathname written.[14]

The dimensions of the image area of interest are not saved or loaded, it is the user's responsibility to load an image file into the correctly sized area of interest.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


File Format. Pixels of the image area of interest are saved or loaded in the order of left to right and top to bottom. Each pixel is saved or loaded using a multiple of two hexadecimal characters; for pixels with multiple pixies, each pixie is saved or loaded using a multiple of two hexadecimal characters. For each byte of a pixie, from the most significant byte to the least significant byte, the hexadecimal character representing the bytes's upper 4 bits is saved or loaded followed by the hexadecimal character for the bytes's lower 4 bits. The number of bytes used per pixie and pixel is defined by ip's data type. For integer valued pixels using fewer bits than the number of bytes would otherwise suggest, the significant bits are always right justified and higher order bits are zero.

For pxio8_hexwrite, if linedelim≠0, the character linedelim is written after each line of pixels. The linedelim should not be a valid hexadecimal character.

For pxio8_hexread, any invalid hexadecimal characters between pixels is ignored; an invalid hexadecimal character within the group of characters representing a pixel's value is an error.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.



Returns

1
Operation complete.

0
Operation complete, but file read is larger than image area of interest.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File doesn't exist (read).

PXERNEWFILE
File can't be created (write).

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

PXERFILEFORM
File read is smaller than image area of interest, or characters other than hexadecimal ASCII present within a pixel.
JPEG File, Load Image --- pxio8_jpegread



Summary 
int pxio8_jpegread(abortp, dip, rsvdp, pathname, windp, mode);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *dip;           // Image & AOI to be loaded
void                *rsvdp;         // Reserved, must be NULL
const char          *pathname;      // File path name
struct pxywindow    *windp;         // Aoi of file to load, or NULL
int                 mode;           // 'n': Nearest neighbor, 'b': Bilinear
                                    // 0x100: convert to color space



Description

The file pathname, in the JPEG/JFIF (Joint Photographic Experts Group / JPEG File Interchange Format) format is loaded into the image referenced by dip. Such files typically have a ''.jpg'' suffix, although pxio8_jpegread does not require, or force, any specific suffix.[15]

JPEG/JFIF format files may be uncompressed or utilize various compression techniques. The pxio8_jpegread is not intended to load and view all JPEG/JFIF format files, but will, of course, load files previously saved by pxio8_jpegwrite as well as other files using similar options.

To allow the most convenient loading of JPEG files, pxio8_jpegread provides dimensional conversions (i.e. width and height), color conversions (i.e. RGB to monochrome, or vice versa), and pixel precision conversions (e.g. 8 bit per pixie to 10 bits per pixie).


Dimensional Conversions. The windp references a ''struct pxywindow'' which defines an AOI within the image file; the image file's AOI is loaded into the image area of interest referenced by dip. If windp=NULL, the entire image file is loaded into the image area of interest referenced by dip. In either case, if the dimensions of the file AOI being loaded differ from the dimensions of the area of interest referenced by dip, the image is resized as it is loaded; if (mode&0xFF)='n', image resizing is done by nearest neighbor, if (mode&0xFF)='b', image resizing is done by bilinear interpolation.


Color Conversions. JPEG/JFIF files can have color or monochrome pixels, at 8 or 12 bits per pixel component. If the image referenced by dip has three pixies per pixel and the JPEG/JFIF file is monochrome, the monochrome pixels are converted to color and loaded into dip. If the image referenced by dip has one pixie per pixel and the JPEG/JFIF file is color, the pixels are converted to intensity values and loaded into dip. If mode&0x100 and dip->d.pixelhint!=PXHINTNONE, the pixels are converted to the dip->d.pixelhint color space and loaded into dip.


Precision Conversions. Each pixie is converted by conserving the most significant bits if the pixie has excessive bits, or adding least significant bits of zero if pixie has insufficient bits (i.e. most significant bit alignment).

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image loaded.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File can't be found.

PXERFILEFORM
File is not valid JPEG/JFIF format.

PXERNOMODE
File uses a JPEG option which is not currently supported.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
JPEG File, Save Image --- pxio8_jpegwrite



Summary 
int pxio8_jpegwrite(abortp, sip, rsvdp, pathname, bits, parmp);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
void                *rsvdp;         // Reserved, must be NULL
const char          *pathname;      // File path name
int                 nbits;          // Bits per pixie to save. Must be 8
struct pximfileinfo *parmp;         // Additional parms, or NULL for default




struct  pximfileinfo {              // only members used in this context shown
    union {
      struct {
        int     quality;            // quality, percentage*10.
        uint16  dotsPerHUnit;       // x resolution
        uint16  dotsPerVUnit;       // y resolution
        uint16  dotsUnits;          // resolution: 0: ratio, 1: inch, 2: cm
        uint16  encodeMode;         // 'f': float mode; 'i': int mode,
                                    // 0: same as 'f' for compatibility
      } jpeg;
    } fi;
    union {
      struct {
        char    *comments[3];       // comments, or NULLs
      } jpeg;
    } fs;
};



Description

The content of the image referenced by sip is saved to file pathname in the JPEG/JFIF (Joint Photographic Experts Group / JPEG File Interchange Format) format with lossy compression. Using JPEG terminology, the file format is Baseline, DCT, Sequential, Huffman coding, with identical sampling factors for all components. JPEG/JFIF files typically have a ''.jpg'' suffix, although pxio8_jpegwrite does not require, or force, any specific suffix.[16] Any existing file pathname is deleted and a new file pathname created.

If the image referenced by sip has three pixies (pixel value components) per pixel, a color JPEG/JFIF file is created. Each pixie of sip is converted to 8 bits, conserving the most significant bits if pixies have more than 8 bits, or adding least significant bits of zero if pixies have less than 8 bits (i.e. most significant bit alignment). Preferably, the sip should be of type PXHINTRGB; if of any other type the pixels are converted to the RGB format required. As per JPEG/JFIF specifications, the pixels are then converted to, and stored as, YCbCr CCIR 601-256 format.

If the image referenced by sip has one pixie (pixel value components) per pixel, a monochrome JPEG/JFIF file is created. Each pixie of sip is converted to 8 bits, by most significant bit alignment.

The parmp may provide additional parameters. The parmp->fi.jpeg.quality, ranging from 1 to 1000 (i.e. .1% to 100.0%) specifies the relative quality of the reconstructed image, and inversely the amount of compression. The visual effect of a given value of parmp->fi.jpeg.quality, and the compression rate achieved, depends upon image content. If parmp->fi.jpeg.encodeMode='i', encoding is done by use of integer code (i.e. instructions); parmp->fi.jpeg.encodeMode='f' or parmp->fi.jpeg.encodeMode=0 encoding is done by use of floating point code (i.e. instructions). Use of integer code yields slightly lower quality images, but, on some computers, is faster.

The parmp->fi.jpeg.dotsPerHUnit, parmp->fi.jpeg.dotsPerVUnit, parmp->fi.jpeg.dotsUnits, specify the image's size and/or aspect ratio.

If parmp->fs.jpeg.comments[0], parmp->fs.jpeg.comments[1], etc. is not NULL, the specified comment is stored in a COM(MENT) field within the file.

If parmp=NULL, a parmp->fi.jpeg.quality of 500 (50.0%), a parmp->fi.jpeg.dotsPerHUnit and parmp->fi.jpeg.dotsPerVUnit of 1, and a parmp->fi.jpeg.dotsUnits of 0 are used, yielding mid-level quality and a 1 to 1 aspect ratio.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
PCX File, Save Image --- pxio8_pcxwrite



Summary 
int pxio8_pcxwrite(abortp, sip, palsip, pathname, bits, rsvd);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage      *palsip;        // Palette to save, or NULL
const char          *pathname;      // File path name
int                 nbits;          // Bits per pixie to save: 1, 2, 4, 8
int                 rsvd;           // Reserved, should be 0



Description

The content of the image referenced by sip is saved to file pathname in the PCX file format. Such files typically have a ''.pcx'' suffix, although pxio8_pcxwrite does not require, or force, any specific suffix.[17] Any existing file pathname is deleted and a new file pathname created.

If the image referenced by sip has three pixies (pixel value components) per pixel, a PCX file of RGB 1*3, 2*3, 4*3, or 8*3 bit pixels is created. Each pixie of sip is converted to nbits bits, where nbits is 1, 2, 4, or 8, conserving the most significant bits if pixies have more than nbits, or adding least significant bits of zero if pixies have less than nbits (i.e. most significant bit alignment). Preferably, the sip should be of type PXHINTRGB; if of type PXHINTBGR the pixels are converted to the RGB format required in the PCX file. Other color types are not converted, the pixels are saved as if they were RGB values. The palsip is ignored.

If the image referenced by sip has one pixie (pixel value components) per pixel, a PCX file of 1, 2, 4, or 8 bit pixel values, with an optional palette of 24 bit RGB colors, is created. Each pixie of sip is converted to nbits bits, where nbits is 1, 2, 4, or 8, by most significant bit alignment.

If palsip is NULL, no palette is saved. Otherwise, palsip is expected to represent a palette for sip; having 3 pixies per pixel, 8 bits per pixie, an ''image'' width of 2sip->d.u.i.bitsused and an ''image'' height of 1. A palsip with other than 8 bits per pixie is converted by most significant bit alignment, a palsip with different dimensions is resized by nearest neighbor. Preferably, the palsip should be of type PXHINTRGB; if of type PXHINTBGR the pixels are converted to the RGB format required in the PCX file. Other color types are not converted, the pixel values are saved as if they were RGB values.

The sip can be a full image or an area of interest. The images referenced by sip and palsip are not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_pcxsave or the XCLIB's pxd_savePcx provides an easy method of saving an frame grabber's buffer and the associated lookup table (if any) without having to construct the palsip.

Targa File, Save Image --- pxio8_tgawrite



Summary 
int pxio8_tgawrite(abortp, sip, palsip, pathname, bits, rsvd);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage      *palsip;        // Palette to save, or NULL
const char          *pathname;      // File path name
int                 nbits;          // Reserved, should be 8
int                 rsvd;           // Reserved, should be 0



Description

The content of the image referenced by sip is saved to file pathname in the Targa file format. Such files typically have a ''.tga'' suffix, although pxio8_tgawrite does not require, or force, any specific suffix.[18] Any existing file pathname is deleted and a new file pathname created.

If the image referenced by sip has three pixies (pixel value components) per pixel, a Targa file of RGB 24 bit pixels is created. Each pixie of sip is converted to 8 bits, conserving the most significant bits if pixies have more than 8 bits, or adding least significant bits of zero if pixies have less than 8 bits (i.e. most significant bit alignment). Preferably, the sip should be of type PXHINTRGB; if of type PXHINTBGR the pixels are converted to the RGB format required in the Targa file. Other color types are not converted, the pixels are saved as if they were RGB values. The palsip is ignored.

If the image referenced by sip has one pixie (pixel value components) per pixel, a Targa file of 8 bit pixel values, with an optional palette of 24 bit RGB colors, is created. Each pixie of sip is converted to 8 bits by most significant bit alignment.

If palsip is NULL, no palette is saved. Otherwise, palsip is expected to represent a palette for sip; having 3 pixies per pixel, 8 bits per pixie, an ''image'' width of 2sip->d.u.i.bitsused and an ''image'' height of 1. A palsip with other than 8 bits per pixie is converted by most significant bit alignment, a palsip with different dimensions is resized by nearest neighbor. Preferably, the palsip should be of type PXHINTRGB; if of type PXHINTBGR the pixels are converted to the RGB format required in the Targa file. Other color types are not converted, the pixel values are saved as if they were RGB values.

The sip can be a full image or an area of interest. The images referenced by sip and palsip are not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_tgasave or the XCLIB's pxd_saveTga provides an easy method of saving an frame grabber's buffer and the associated lookup table (if any) without having to construct the palsip.

TIFF File, Load Image --- pxio8_tifread
TIFF File, Load Image Sequence --- pxio8_tifreadseq



Summary 
int pxio8_tifread(abortp, dip, paldip, pathname, subfile, windp, mode);
int pxio8_tifreadseq(abortp, dip3, paldip, pathname, subfile, windp, mode);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *dip;           // Image & AOI to be loaded
struct pximage3     *dip3;          // Image sequence & AOI to load
struct pximage      *paldip;        // Palette to load, or NULL
const char          *pathname;      // File path name
long                subfile;        // Sub image index within TIFF file
struct pxywindow    *windp;         // Aoi of file to load, or NULL
int                 mode;           // 'n': Nearest neighbor, 'b': Bilinear
                                    // 0x100: convert to color space



Description

The file pathname, in the Tagged Image File Format (TIFF) or BigTIFF format, is loaded into the image referenced by dip (or image sequence referenced by dip3). Such files typically have a ''.tif'' suffix (for TIFF) or ''.btf'' suffix (for BigTIFF), although pxio8_tifread and pxio8_tifreadseq do not require, or force, any specific suffix.[19]

If the file pathname has a palette which is required for interpretation of pathname's pixels, the palette is optionally loaded into the image referenced by paldip; which should have 3 pixies per pixel, an ''image'' height of 1, and a width equal to the number of palette entries.

TIFF format files may be uncompressed or utilize various compression techniques. The pxio8_tifread is not intended to load and view all TIFF format files, but will, of course, load files previously saved by pxio8_tifwrite as well as other files using similar options.

To allow the most convenient loading of TIFF files, pxio8_tifread and pxio8_tifreadseq provide dimensional conversions (i.e. width and height), color conversions (i.e. RGB to intensity, or index+palette to RGB), and pixel precision conversions (e.g. 1 bit per pixie to 8 bits per pixie, or vice versa). Similar conversions allow convenient loading of the file's palette into the provided paldip.

Each TIFF file may contain multiple images. For pxio8_tifread, the subfile, subfile≥0, image of the file pathname is loaded. For pxio8_tifreadseq, the subfile, is loaded into the first image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z), the subfile+1, is loaded into the second image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z+1), etc. For pxio8_tifreadseq, all images within the file are expected to be of the same dimensions.


Dimensional Conversions. The windp references a ''struct pxywindow'' which defines an AOI within the image file; the image file's AOI is loaded into the image area of interest referenced by dip. If windp=NULL, the entire image file is loaded into the image area of interest referenced by dip. In either case, if the dimensions of the file AOI being loaded differ from the dimensions of the area of interest referenced by dip, the image is resized as it is loaded; if (mode&0xFF)='n', image resizing is done by nearest neighbor, if (mode&0xFF)='b', image resizing is done by bilinear interpolation. Resizing of the palette, if required, is always done by nearest neighbor.

For pxio8_tifreadseq, the windp represents an a two-dimensional AOI within one such image. Each image in the file is loaded into one ''z-slice''[20] of the three-dimensional area of interest referenced by dip3, resized as described above. There is no resizing from image to image (i.e. along the Z axis).


Color & Grey Level Conversions. If the image referenced by dip (or dip3) has three pixies per pixel and the TIFF image has pixel indices plus a palette, the pixels are converted via the palette to RGB values and loaded into dip (or dip3). If the image referenced by dip (or dip3) has one pixie per pixel and the TIFF image has RGB or YCbCr pixels, the pixels are converted to intensity values and loaded into dip (or dip3). If mode&0x100 and dip->d.pixelhint!=PXHINTNONE (or dip3->d.pixelhint!=PXHINTNONE), the pixels are converted to the dip->d.pixelhint (or dip3->d.pixelhint) color space and loaded into dip (or dip3).

If the TIFF image has a Photo Interpretation of ''WhiteIsZero'', pixel values are complemented. If the TIFF image has a Photo Interpretation of ''YCbCr'', pixel values are reordered to the PXHINTYCRCB order.

The paldip is loaded only when the image referenced by dip (or dip3) has one pixie per pixel and the TIFF file has pixel indices plus a palette.

Other than the cases described above, the image referenced by dip (or dip3) is expected to have the same number of pixies per pixel as the TIFF image; the TIFF pixies are loaded into dip (or dip3) pixies in the order presented, and without regard to the stated image type (i.e. the PXHINT*) of dip (or dip3).

For images with floating point pixels: The paldip must be NULL.


Precision Conversions. For images with unsigned integer pixels: Each pixie, of both the image and the palette, if used, is converted by conserving the most significant bits if the pixie has excessive bits, or adding least significant bits of zero if pixie has insufficient bits (i.e. most significant bit alignment).

For images with floating point pixels: Float values are converted to double values, or vice versa, as required.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels. Note that loading unsigned integer pixels into a dip (or dip3) with floating point pixels, or vice versa, is not supported.



Returns

1
Image and palette loaded.

0
Image loaded, no palette loaded.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File can't be found.

PXERFILEFORM
File not valid TIFF format, or the subfile is invalid.

PXERNOMODE
TIFF option, such as compression, not currently supported.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_tiffload or the XCLIB's pxd_loadTiff provides an easy method of loading an frame grabber's frame buffer and the associated lookup table (if any) without having to construct the paldip.

The dimensions of an image in a file, useful for the optional windp, the number of pixies per pixel, and whether the pixels are unsigned integer or floating point can be obtained with pxio8_fileinfo.

TIFF File, Save Image --- pxio8_tifwrite
TIFF File, Save Image Sequence --- pxio8_tifwriteseq
TIFF File, Save Sequence - Init --- pxio8_tifwriteseqinit
TIFF File, Save Sequence - Add Image --- pxio8_tifwriteseqadd
TIFF File, Save Sequence - Done --- pxio8_tifwriteseqdone



Summary 
int pxio8_tifwrite(abortp, sip, palsip, pathname, nbits, npalbits, subfile, parmp);
int pxio8_tifwriteseq(abortp, sip3, palsip, pathname, nbits, npalbits, subfile, parmp);


int pxio8_tifwriteseqinit(abortp, handlep, pathname, sip, palsip, nbits, npalbits, parmp, nimages);
int pxio8_tifwriteseqadd (abortp, handlep, pathname, sip, palsip, nbits, npalbits, parmp);
int pxio8_tifwriteseqdone(abortp, handlep, pathname);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage3     *sip3;          // Image sequence & AOI to save
struct pximage      *palsip;        // Palette to save, or NULL
const char          *pathname;      // File path name
int                 nbits;          // Bits per pixie to save
int                 npalbits;       // Bits per palette pixie to save
long                subfile;        // Sub image index within TIFF file
struct pximfileinfo *parmp;         // Additional parms, or NULL for default
long                nimages;        // Reserved, should be 0
void                **handlep;      // *NULL, becomes *handle to mapping state




struct  pximfileinfo {              // only members used in this context shown
    union {
      struct {
        int     xresolution[2];     // x resolution ratio. 0/0 if unused
        int     yresolution[2];     // y resolution ratio  0/0 if unused
        int     resolutionunit;     // as per defines, iff xres, yres used
        int     compression;        // PXIMTIFF_Compress_NONE
                                    // PXIMTIFF_Compress_LZW
                                    // PXIMTIFF_Compress_LZW_HP
                                    // PXIMTIFF_Compress_PackBits
                                    // PXIMTIFF_Compress_EPIX_LsLs
                                    // PXIMTIFF_Compress_EPIX_LsLsHP
        ulong   maxstripsize;       // advisory, 0: default
        ...
        int     version;            // PXIMTIFF_Version_* or 0 for classic
      } tiff;
    } fi;
    union {
      struct {
        char    *datetime;          // date/time, tiff format, or NULL
        char    *software;          // name of creating pgm, or NULL
        char    *description;       // description of image, or NULL
        char    *copyright;         // copyright notice, or NULL
      } tiff;
    } fs;
};



Description

For pxio8_tifwrite, the content of the image referenced by sip is saved to file pathname in the Tagged Image File Format (TIFF) or BigTIFF format. For pxio8_tifwriteseq, the content of the image sequence referenced by sip3 is saved to file pathname in the Tagged Image File Format (TIFF) or BigTIFF format. Such files typically have a ''.tif'' suffix (for TIFF) or ''.btf'' suffix (for BigTIFF), although pxio8_tifwrite and pxio8_tifwriteseq do not require, or force, any specific suffix.[21] For pxio8_tifwrite and pxio8_tifwriteseq, if subfile=0, any existing file pathname is deleted and a new file pathname written, if subfile≠0 the new image is appended to the file pathname. Each TIFF file may contain multiple images; the subfile≥0 image of the file pathname is written. The various subfile's must be added in monotonically increasing order; overwriting or deleting a subfile is not supported. For pxio8_pgmwriteseq, the first image of the sequence is written to subfile, the next to subfile+1, etc.

The pxio8_tifwriteseqinit, pxio8_tifwriteseqadd, and pxio8_tifwriteseqdone also allow saving an image sequence, allowing incremental addition of the content of the image referenced by sip to file pathname in the Tagged Image File Format (TIFF); the pxio8_tifwriteseqinit initializing the feature, deleting any existing file pathname and creating a new file pathname, each invocation of the pxio8_tifwriteseqadd adding a single image, and the pxio8_tifwriteseqdone terminating the feature.


Image with Unsigned Integer Pixel Values. The pixies (pixel value component) of sip (or sip3) are converted to nbits bits, where 1<=nbits<=32, conserving the most significant bits if pixies have more than nbits bits, or adding least significant bits of zero if pixies have less than nbits bits (i.e. most significant bit alignment). Alternately, nbits may be negative, -32<=nbits<=-1, adding most significant bits of zero if pixies have less than -nbits bits (i.e. least significant bit alignment).

If sip (or sip3) has one pixie per pixel, the palsip may reference a palette for sip (or sip3); having 3 pixies per pixel, an ''image'' width of 2sip->d.u.i.bitsused and an ''image'' height of 1. The pixies of palsip are converted to npalbits by most significant bit alignment, a palsip with different dimensions is resized by nearest neighbor.


Image with Floating Point Pixel Values. The palsip, nbits, and npalbits are not used and should be NULL or 0, respectively.

Certain image types are recognized and handled specially, as follows. For images of type PXHINTRGB or PXHINTBGR, the TIFF file is marked as having a ''Photo Interpretation'' of ''RGB'', and the PXHINTBGR pixels are reordered to RGB. For images of type PXHINTYCRCB, the TIFF file is marked as having a Photo Interpretation of ''YCbCr'', the PXHINTYCRCB pixels are reordered to YCbCr. For images with one pixie per pixel with a provided palsip, the TIFF file is marked as having a Photo Interpretation of ''RGBPalette'' and the palette referenced by palsip is saved with the image. For other image types, the TIFF file is marked as having a Photo Interpretation of ''BlackIsZero''.

The parmp may provide additional, optional, parameters. If subfile\(>0 and parmp->fi.tiff.version is PXIMTIFF_Version_BigTiff a BigTIFF format file is created, if parmp->fi.tiff.version is PXIMTIFF_Version_Tiff or 0 a TIFF format file is created. The parmp->fs.tiff.software, parmp->fs.tiff.description, and/or parmp->fs.tiff.copyright may reference NULL terminated textual strings to be stored with the image; any of these references may be NULL if inclusion of the textual string is not required. If parmp->fs.tiff.datetime is NULL, the current date and time are stored as the image's date and time of creation. Otherwise the specified parmp->fs.tiff.datetime is stored as the image's date and time of creation; use of the standard TIFF date and time format for parmp->fs.tiff.datetime is strongly recommended.

The parmp->fi.tiff.maxstripsize allows control over the file's internal format; namely the strip size. This parameter is useful when expecting to import the files into other programs which do not support the standard TIFF strip size. A stripsize=0 indicates use of the standard, default, TIFF strip size. If the saved image can't be loaded, a file written with maxstripsize=1 (i.e. minimum strip size), and a file written with maxstripsize=99999999 (i.e. maximum strip size) should be tried. The maxstripsize doesn't impact later reading of the file by pxio8_tifread or pxio8_tifreadseq which support all strip sizes.

The parmp->fi.tiff.xresolution and parmp->fi.tiff.yresolution allows specifying the image's horizontal and vertical resolution, each as a ratio and in units of parmp->fi.tiff.resolutionunit; each of these members may be zero if to be left unspecified. Valid values for parmp->fi.tiff.resolutionunit are PXIMTIFF_ResUnit_ratio if the resolution is an unscaled aspect ratio, PXIMTIFF_ResUnit_in if the resolution is in inches, or PXIMTIFF_ResUnit_cm if the resolution is in centimeters.

The parmp->fi.tiff.compression allows specifying optional compression. Valid values are PXIMTIFF_Compress_None or 0 for no compression, PXIMTIFF_Compress_PackBits for ''Pack Bits'' compression (primarily intended for unsigned integer pixies with 1, 2, 4, or 8 bits, and one pixie per pixel), PXIMTIFF_Compress_EPIX_LsLs or PXIMTIFF_Compress_EPIX_LsLsHP for private, lossless, compression methods (only for unsigned integer pixies with no more than 12 bits),[22] or PXIMTIFF_Compress_LZW for LZW (Lempel-Ziv-Welch) compression without predictors, or PXIMTIFF_Compress_LZW_HP for LZW (Lempel-Ziv-Welch) compression with horizontal predictors.

If parmp=NULL, a date and time are stored, a default strip size is used, no resolution is stored, and no compression is used.

Note that other programs may not support multiple images in a single TIFF file; storing one image per file will help assure file compatibility.

For pxio8_tifwriteseqinit, pxio8_tifwriteseqadd, and pxio8_tifwriteseqdone, the *handlep must initially be NULL; the handle to an internal state is ''returned'' at *handlep by pxio8_tifwriteseqinit, utilized by pxio8_tifwriteseqadd, and reset back to NULL by pxio8_tifwriteseqdone. The sip provided to pxio8_tifwriteseqinit is NOT saved, but rather provides information about the type of images to be later saved via pxio8_tifwriteseqadd. Each image provided via pxio8_tifwriteseqadd should have the same attributes: resolution, bit depth, color space, etc. The parmp->fs.tiff.software, parmp->fs.tiff.description, parmp->fs.tiff.copyright, and parmp->fs.tiff.datetime may differ from image to image

The sip (or sip3) can be a full image or an area of interest. The images referenced by sip (or sip3) and palsip are not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERNOFILE
File doesn't exist (for subfile≥1).

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERFILEFORM
The subfile was invalid, such as a subfile≥1 and the existing TIFF file does not have exactly subfile subfiles.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The SVOBJ, 4MOBJ, or XCOBJ's pxd_tiffsave, or XCLIB's pxd_saveTiff, provides an easy method of saving an frame grabber's frame buffer and the associated lookup table (if any) without having to construct the palsip.

Portable Map File, Load Image --- pxio8_pgmread
Portable Map File, Load Image Sequence --- pxio8_pgmreadseq



Summary 
int pxio8_pgmgread(abortp, dip, pathname, subfile, windp, mode);
int pxio8_pgmreadseq(abortp, dip3, pathname, subfile, windp, mode);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *dip;           // Image & AOI to be loaded
struct pximage3     *dip3;          // Image sequence & AOI to be loaded
const char          *pathname;      // File path name
long                subfile;        // Sub image index within file
struct pxywindow    *windp;         // Aoi of file to load, or NULL
int                 mode;           // 'n': Nearest neighbor, 'b': Bilinear
                                    // 0x100: convert to color space



Description

The file pathname, in the Portable Bit Map, Portable Gray Map, or Portable Pixel Map format is loaded into the image referenced by dip (or image sequence referenced by dip3). Such files typically have a ''.pbm'', ''.pgm'', or ''.ppm'' suffix, although pxio8_pgmread and pxio8_pgmreadseq does not require, or force, any specific suffix.[23]

To allow the most convenient loading of Portable Map files, pxio8_pgmread and pxio8_pgmreadseq provide dimensional conversions (i.e. width and height), color conversions (i.e. RGB to monochrome, or vice versa), and pixel precision conversions (e.g. 8 bit per pixie to 10 bits per pixie).

Each Portable Map file may contain multiple images. For pxio8_pgmread, the subfile, subfile≥0, image of the file pathname is loaded. For pxio8_pgmreadseq, the subfile, is loaded into the first image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z), the subfile+1, is loaded into the second image of the sequence referenced by dip3 (i.e. the two-dimensional image slice having Z coordinate equal to dip3->wind.nw.z+1), etc.


Dimensional Conversions. The windp references a ''struct pxywindow'' which defines an AOI within the image file; the image file's AOI is loaded into the image area of interest referenced by dip. If windp=NULL, the entire image file is loaded into the image area of interest referenced by dip. In either case, if the dimensions of the file AOI being loaded differ from the dimensions of the area of interest referenced by dip, the image is resized as it is loaded; if (mode&0xFF)='n', image resizing is done by nearest neighbor, if (mode&0xFF)='b', image resizing is done by bilinear interpolation.

For pxio8_pgmreadseq, the windp represents an a two-dimensional AOI within one such image. Each image in the file is loaded into one ''z-slice''[24] of the three-dimensional area of interest referenced by dip3, resized as described above. There is no resizing from image to image (i.e. along the Z axis).


Color & Grey Level Conversions. Portable Map files can have color or monochrome pixels. If the image referenced by dip has three or four pixies per pixel and the Portable Map file is monochrome, the monochrome pixels are converted to color and loaded into dip (or dip3). If the image referenced by dip (or dip3) has one pixie per pixel and the Portable Map file is color, the pixels are converted to intensity values and loaded into dip (or dip3). If mode&0x100 and dip->d.pixelhint!=PXHINTNONE, the pixels are converted to the dip->d.pixelhint color space and loaded into dip (or dip3).


Precision Conversions. Each pixie is converted by conserving the most significant bits if the pixie has excessive bits, or adding least significant bits of zero if pixie has insufficient bits (i.e. most significant bit alignment).

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image loaded.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNOFILE
File can't be found.

PXERFILEFORM
File is not valid Portable Map format, or the subfile is invalid.

PXERNOMODE
File uses a Portable Map option which is not currently supported.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Portable Map File, Save Image --- pxio8_pgmgwrite
Portable Map File, Save Image Sequence --- pxio8_pgmwriteseq
Portable Map File, Save Sequence - Init --- pxio8_pgmwriteseqinit
Portable Map File, Save Sequence - Add Image --- pxio8_pgmwriteseqadd
Portable Map File, Save Sequence - Done --- pxio8_pgmwriteseqdone



Summary 
int pxio8_pgmwrite(abortp, sip, pathname, bits, subfile, parmp);
int pxio8_pgmwriteseq(abortp, sip3, pathname, bits, subfile, parmp);


int pxio8_pgmwriteseqinit(abortp, handlep, pathname, sip, bits, subfile, parmp, nimages);
int pxio8_pgmwriteseqadd(abortp, handlep, pathname, sip, bits, parmp);
int pxio8_pgmwriteseqdone(abortp, handlep, pathname);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image & AOI to save
struct pximage3     *sip3;          // Image sequence & AOI to save
const char          *pathname;      // File path name
int                 bits;           // Bits per pixie to save
long                subfile;        // Sub image index within file
struct pximfileinfo *parmp;         // Additional parms, or NULL for default
long                nimages;        // Number of images to be saved
void                **handlep;      // *NULL, becomes *handle to mapping state




struct  pximfileinfo {              // only members used in this context shown
    union {
      struct {
        uchar   magic;              // '4', '5', '6' to select pbm/pgm/ppm
                                    // or 0 for default
                                    // (only 0 currently supported)
    union {
      struct {
        char    *comments[4];       // comments, or NULLs
      } pgm;
    } fs;
};



Description

For pxio8_pgmwrite, the content of the image referenced by sip is saved to file pathname in the Portable Bit Map, Portable Gray Map, or Portable Pixel Map format. For pxio8_pgmwriteseq, the content of the image sequence referenced by sip3 is saved to file pathname in the Portable Bit Map, Portable Gray Map, or Portable Pixel Map format. Portable Map files typically have a ''.pbm'', ''.pgm'', or ''.ppm'' suffix, although pxio8_pgmwrite and pxio8_pgmwriteseq does not require, or force, any specific suffix.[25] For pxio8_pgmwrite and pxio8_pgmwriteseq, if subfile=0, any existing file pathname is deleted and a new file pathname written, if subfile≠0 the new image is appended to the file pathname. Each Portable Map file may contain multiple images; the subfile≥0 image of the file pathname is written. The various subfile's must be added in monotonically increasing order; overwriting or deleting a subfile is not supported. For pxio8_pgmwriteseq, the first image of the sequence is written to subfile, the next to subfile+1, etc.

The pxio8_pgmwriteseqinit, pxio8_pgmwriteseqadd, and pxio8_pgmwriteseqdone also allow saving an image sequence, allowing incremental addition of the content of the image referenced by sip to file pathname in the Portable Bit Map, Portable Gray Map, or Portable Pixel Map file format; the pxio8_pgmwriteseqinit initializing the feature, deleting any existing file pathname and creating a new file pathname, each invocation of the pxio8_pgmwriteseqadd adding a single image, and the pxio8_pgmwriteseqdone terminating the feature.

If the image referenced by sip has three pixies or four (pixel value components) per pixel, a color Portable Pixel Map file is created. Preferably, the sip should be of type PXHINTRGB; if of any other type the pixels are converted to the RGB format required. If the image referenced by sip has one pixie (pixel value components) per pixel and more than one bit per pixie, a monochrome Portable Gray Map file is created. If the image referenced by sip has one pixie (pixel value components) per pixel and one bit per pixie, a monochrome Portable Bit Map file is created.

The parmp may provide additional parameters. If parmp->fs.pgm.comments[0], parmp->fs.pgm.comments[1], etc. is not NULL, the specified comment is stored as a comment within the file.

Note that other programs may not support multiple images in a single Program Map file; storing one image per file will help assure file compatibility.

For pxio8_pgmwriteseqinit, pxio8_pgmwriteseqadd, and pxio8_pgmwriteseqdone, the *handlep must initially be NULL; the handle to an internal state is ''returned'' at *handlep by pxio8_pgmwriteseqinit, utilized by pxio8_pgmwriteseqadd, and reset back to NULL by pxio8_pgmwriteseqdone. The sip provided to pxio8_pgmwriteseqinit is NOT saved, but rather provides information about the type of images to be later saved via pxio8_pgmwriteseqadd. Each image provided via pxio8_pgmwriteseqadd should have the same attributes: resolution, bit depth, color space, etc. The parmp->fs.pgm.comments may not differ from image to image; only one copy of the parmp->fs.pgm.comments is stored.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or 3-color, of unsigned integer pixels, of 1 to 16 bits.



Returns

0
Image saved.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERNEWFILE
File can't be created.

PXERDOSIO
DOS/Windows/Linux I/O read or write error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

14. NxN Neighborhood Operations

NxN Convolution, Integer --- pxip8_NxNconvolve
NxN Convolution, Real --- pxip8_NxNconvolvef



Summary 
int pxip8_NxNconvolve(abortp,sip,dip,N,coefficient,offset,divisor,mode);
int pxip8_NxNconvolvef(abortp,sip,dip,N,fcoefficient,foffset,fdivisor,mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 N;              // 3, 5, 7, 9, 11, ...
int                 coefficient[];  // NxN convolution mask coefficients
int                 offset;         // add to sum of product before div.
int                 divisor;        // divisor. 0 for sum of coefficients
float               fcoefficient[]; // NxN convolution mask coefficients
double              foffset;        // add to sum of product before div.
double              fdivisor;       // divisor. 0 for sum of coefficients
int                 mode;           // 0: new = convolve(old)
                                    // 1: new = abs(convolve(old)
                                    // 2: new = old - convolve(old)
                                    // 3: new = old - Abs(convolve(old))



Description

An NxN convolution, where N≥3 and odd, is applied to the NxN neighborhood of each pixel in the image referenced by sip with the result placed in the image referenced by dip. The value of each pixel in the neighborhood is multiplied by the corresponding coefficients given by coefficient or fcoefficient the NxN products summed, the offset or foffset added, and the sum divided by the divisor or fdivisor. The pxip8_NxNconvolve uses integer valued coefficients, offset, and divisor, the pxip8_NxNconvolvef allows use of real valued coefficients, offset, and divisor.

If mode=0, each pixel is replaced with the result of the computation, bounded by 0 and the maximum pixel value (255 for 8 bit pixels). If mode=1, each pixel is replaced with the absolute value of the result of the computation, bounded by 0 and the maximum pixel value If mode=2, the result of the computation is subtracted from each pixel, and the result bounded by 0 and the maximum pixel value. If mode=3, the absolute value of the result of the computation is subtracted from each pixel, and the result bounded by 0 and the maximum pixel value.

Boundary conditions (pixels lacking all NxN neighbors) are treated as follows. If mode<=1 and the sum of the coefficient or fcoefficient is zero, or mode≥2 and the sum of the coefficient or fcoefficient is not zero (i.e. various forms of edge detectors with zero result when applied over a monotone region), then boundary pixels are set, in dip, to 0. Otherwise, boundary pixels, in dip, are set by duplicating the adjacent result pixels.

The convolution mask coefficients are defined by the NxN array coefficient or fcoefficient interpreted as: 

coefficient[Y][X]
For example, the spatial definition of the 3x3 coefficients would be: 
coefficient[0]   coefficient[1]  coefficient[2]
coefficient[3]   coefficient[4]  coefficient[5]
coefficient[6]   coefficient[7]  coefficient[8]

If divisor=0 (fdivisor=0), the sum of the coefficients is used as the divisor. Using offset=0 (foffset=0), divisor=0 (fdivisor=0), and mode=0 results in the standard ''plain'' convolution operation.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Esoterica. The single pxip8_NxNconvolve function identifies various special cases based upon the parameters used, and optimizes accordingly. Thus, there is no need for a separate function to execute the popular 3x3 convolution efficiently.

The maximum N which can be used is limited only by the availability of memory and the user's patience; the latter because execution time increases in proportion to the square of N.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. For pxip8_NxNconvolvef, a math coprocessor is recommended.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

An 11x11 low-pass filter is applied to the first image frame buffer. 

int     coef[11x11], i;


/*
 * Set coefficients. This simple filter uses a
 * matrix of 1 coefficients.
 */
for (i = 0; i < 11*11; i++)
    coef[i] = 1;


/*
 * Execute.
 */
pxip8_NxNconvolve(NULL,
                  #if 1         // w. if XCLIB
                    pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                    pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                  #else         // w. SVOBJ,4MOBJ,XCOBJ
                    pxd_defimage(1,0,0,-1,-1),
                    pxd_defimage(1,0,0,-1,-1),
                  #endif
                  11, coef, 0, 0, 0);
NxN Dynamic Threshold --- pxip8_NxNdynthreshold



Summary 
int pxip8_NxNdynthreshold(abortp, sip, dip, N, low, high, npv);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 N;              // 3, 5, 7, 9, 11, ...
int                 low;            // low bound, percentile of NxN mean
int                 high;           // high bound, percentile of NxN mean
uint                npv;            // new pixel value



Description

A dynamic threshold is applied to the image referenced by sip with the result placed in the image referenced by dip. The value of each source pixel is compared to the mean of the values of source pixels in the NxN neighborhood, for odd N≥3. If the pixel's value is between low and high percent of the mean, the corresponding result pixel's value is set to npv, otherwise the pixel's value is set to the maximum pixel value (255 for 8 bit pixels) minus npv. Boundary conditions (pixels lacking all NxN neighbors) are treated by comparing the pixels to the mean of the closest NxN neighborhood.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
NxN Inverse Contrast Ratio Mapping --- pxip8_NxNcontrastinvert



Summary 
int pxip8_NxNcontrastinvert(abortp, sip, dip, N);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 N;              // 3, 5, 7, 9, 11, ...



Description

An inverse contrast ratio mapping is applied to the image referenced by sip with the result placed in the image referenced by dip. Each result pixel is set to the ratio of the mean and standard deviation of the NxN neighborhood of the corresponding original pixel. The operation's result has low contrast where the original image's contrast was high, and vice versa. The N must be odd and N≥3. Boundary conditions (pixels lacking all NxN neighbors) are treated by duplicating, in dip, the adjacent result pixels.

For color pixels, each component (i.e. ''pixie'') of the pixel is independently modified, as described above.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

Jain, A.K., FUNDAMENTALS OF IMAGE PROCESSING, 1989, pp. 252-253.

 

 

 

15. Image Copy & Resize

Copy Image Buffer --- pxip8_copy



Summary 
int pxip8_copy(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

The content of the image referenced by sip is copied without modification to the image referenced by dip.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy & Convert Data Types --- pxip8_copyconvert



Summary 
int pxip8_copyconvert(abortp, ip1, ip2, xsb, xflt, rsvd1, rsvd2);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *ip1;           // image 1
struct  pximage     *ip2;           // image 2
int                 xsb;            // 'm': MSB align uint types
                                    // 'l': LSB align uint types
                                    //  0 : Don't align uint types
int                 xflt;           // 's': scale uint<->float
                                    //  0 : don't scale uint<->float
int                 rsvd1;          // reserved. should be 0
int                 rsvd2;          // reserved. should be 0



Description

The content of the image referenced by ip1 is copied to the image referenced by ip2. Unlike pxip8_copy most other PXIPL functions, the pxip8_copyconvert allows copying between images of different data types, bit depths, and precision.

If converting between uint8, uint16, or uint32 pixels: If xsb='m', pixel values are shifted so as to maintain most significant bit alignment. If xsb='l', pixel values are shifted so as to maintain least significant bit alignment. If xsb=0, pixel values are not shifted.

If converting to/from uint8, uint16, or uint32 pixels and from/to float or double pixels: If xflt='s' pixel values are scaled to maintain the customary minimum value and maximum values. For example, if converting from 8 bit pixels to float or double pixels with the customary range of 0.0 to 1.0, pixel values are scaled by 1.0/255. If xflt=0, pixel values are not scaled.

The ip1 and ip2 areas of interest must be of identical dimensions, and can reference the same image.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy & Exchange Image Buffers --- pxip8_copyexchange



Summary 
int pxip8_copyexchange(abortp, ip1, ip2);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *ip1;           // image 1
struct  pximage     *ip2;           // image 2



Description

The content of the image referenced by ip1 is exchanged with the content of the image referenced by ip2.

The ip1 and ip2 areas of interest must be of identical dimensions, and can reference the same image.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy Image Buffer with Reversal --- pxip8_copyreverse



Summary 
int pxip8_copyreverse(abortp, sip, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // 1: left/right flip
                                    // 2: top/bottom flip
                                    // 3: l/r & t/b  flip



Description

The content of the image referenced by sip is copied with a left/right reversal and/or a top/bottom reversal to the image referenced by dip. If mode&0xFF=1, the image is reversed left-to-right about the vertical axis (center). If mode&0xFF=2, the image is reversed top-to-bottom about the horizontal axis (center). If mode&0xFF=3, the image is reversed both left-to-right and top-to-bottom about the center axis. If mode&0xFF=0, the image is copied without modification.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy Image Buffer with Shift --- pxip8_copyshift



Summary 
int pxip8_copyshift(abortp, sip, dip, xshift, yshift);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 xshift;         // left/right shift
int                 yshift;         // up/down shift



Description

The content of the image referenced by sip is copied with a left/right shift and/or an up/down shift to the image referenced by dip. The image is shifted xshift pixels to the right and yshift pixels downward; negative values of xshift or yshift reverse the corresponding shift direction. The area of the result image from which image data was ''shifted-out'' is set to pixel value(s) 0 in dip. If the absolute value of xshift or the absolute value of yshift exceeds the corresponding dimension of the image referenced by sip, then the entire dip is set to pixel value(s) 0.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy Slice of Image Buffer --- pxip8_copyslice



Summary 
int pxip8_copyslice(abortp, sip, dip, sslice, dslice);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 sslice;         // pixie of sip
int                 dslice;         // pixie of dip



Description

One pixie (pixel value component) of the image referenced by sip is copied to one pixie of the image referenced by dip. The pixie of sip to be copied is specified by 0<=sslice<sip->d.pixies. The pixie of dip to be copied is specified by 0<=dslice<dip->d.pixies.

Need of using pxip8_copyslice is rare; the pximage_colorslice allows adding a filter which extracts one pixie slice to a pximage, and thus allows incorporating ''pixie slicing'' into the use of other PXIPL functions.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy & Convert Color Space --- pxip8_copycolorconvert



Summary 
int pxip8_copycolorconvert(abortp, ip1, rsvd1, newhint, rsvd2, rsvd3);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *ip1;           // image 1
struct  pximage     *ip2;           // image 2
int                 rsvd1;          // reserved. should be 0
int                 newhint;        // color space, PXHINT*
int                 rsvd2;          // reserved. should be 0
int                 rsvd3;          // reserved. should be 0



Description

The content of the image referenced by ip1 is copied to the image referenced by ip2, converting from the color space specified by sip->d.pixelhint, to the color space specified by newhint. The color space specified by dip->d.pixelhint, if any, is ignored.

The ip1 and ip2 areas of interest must be of identical dimensions, and can reference the same image.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy & Bilinear Interpolation w. Orientation --- pxip8_copyinterpbilinear
Copy & Nearest Neighbor Interpolation w. Orientation --- pxip8_copyinterpnearest



Summary 
int pxip8_copyinterpbilinear(abortp, sip, dip, bmode, orient);
int pxip8_copyinterpnearest(abortp, sip, dip, nmode, orient);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 bmode;          // 'b': bilinear
int                 nmode;          // 'n' or 0: nearest neighbor
                                    // 'n'^1: near neighbor deflicker
int                 orient;         // 'u', 'd', 'l', or 'r'
                                    // 'u'^'M', 'd'^'M', 'l'^'M', or 'r'^'M'



Description

The source image referenced by sip is copied to the destination image buffer referenced by dip, with optional change of orientation, using interpolation to adjust for differences in the dimensions of the source and destination. The pxip8_copyinterpbilinear performs bilinear value interpolation, the pxip8_copyinterpnearest performs nearest neighbor interpolation. The horizontal and vertical dimensions of the destination can be larger, smaller or identical to the source; thus the image can be reduced, enlarged or reduced in one dimension while enlarged in the other dimension. The image may be copied with any of 8 orientations, providing rotations of 0°, 90°, 180°, and 270°, each of which may be reflected about the (original) vertical center (i.e. mirror image flipped).

For pxip8_copyinterpbilinear the bmode should always be 'b'. For pxip8_copyinterpnearest, nmode='n' or nmode=0 selects nearest neighbor interpolation, nmode='n'^1 selects a near neighbor interpolation which reduces display artifacts due to the image being interlaced (horizontally and/or vertically).

The orient specifies the rotation and reflection to be performed. If orient='u' or orient=0 no rotation is performed. For orient='l', orient='d', and orient='r' the top of the source image becomes oriented left, down, or right, respectively. If orient='u'^'M', orient='l'^'M', orient='d'^'M', or orient='r'^'M', the image is first reflected about the vertical center and the top becomes oriented up, left, down, or right, respectively. 'ne 1i Graphically, a source image of: 

           .  .  .
        .  .  .  .
        .  .  .  .
'ne 1i becomes (ignoring resizing): 
 'u'       .  .  .          'u'^'M'     .  .  .
        .  .  .  .                      .  .  .  .
        .  .  .  .                      .  .  .  .


 'l'    .  .  .             'l'^'M'        .  .
        .  .  .                         .  .  .
        .  .  .                         .  .  .
           .  .                         .  .  .


 'd'    .  .  .  .          'd'^'M'     .  .  .  .
        .  .  .  .                      .  .  .  .
        .  .  .                            .  .  .


 'r'    .  .                'r'^'M'     .  .  .
        .  .  .                         .  .  .
        .  .  .                         .  .  .
        .  .  .                         .  .

As a special case, pxip8_copyinterpbilinear executes significantly faster when the vertical source and destination dimensions are identical and orient='u'.

For backward compatibility with previous versions of these functions, orient='u'|0x80, orient='l'|0x80, orient='d'|0x80, and orient='r'|0x80, are accepted as synonyms for orient='u'^'M', orient='l'^'M', orient='d'^'M', and orient='r'^'M', respectively.

The sip and dip areas of interest may be of different dimensions, and reference different image buffers or areas of interest in the same image buffer, however the effect of the operation when sip and dip overlap is undefined. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels of 1 to 16 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters. Note that source or destination dimensions of one are invalid for this operation.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

The pxip8_copy is more efficient than pxip8_copyinterpbilinear or pxip8_copyinterpnearest when copying between images or areas of interest of identical dimensions without reorientation.

Copy & Area Interpolation --- pxip8_copyinterpolate



Summary 
int pxip8_copyinterpolate(abortp, sip, dip, xsupport, ysupport, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
double              xsupport;       // x dim extra area of support. -1 default
double              ysupport;       // y dim extra area of support. -1 default
int                 mode;           // 'l': linear, 'g': gaussian



Description

The source image referenced by sip is copied to the destination image referenced by dip, using pixel value area interpolation to adjust for differences in the dimensions of the source and destination. The horizontal and vertical dimensions of the destination can be larger, smaller or identical to the source; thus the image can be reduced, enlarged or reduced in one dimension while enlarged in the other dimension.

The pixel values of the destination image are computed by interpolation over the corresponding area of support in the source image. The area of support in the source image, in either the horizontal or vertical dimension can be extended by xsupport or ysupport pixels, respectively. This is most useful when enlarging an image, in order to reduce ''blockiness'' at the expense of blurring. For example, using only the horizontal dimension for simplicity, in interpolating 32 pixels to 64 pixels with xsupport=0.0, destination pixel 1 takes on the value of source pixels between coordinates 0.5 and 1.0. With xsupport=0.25, destination pixel 1 takes on the value of source pixels between coordinates 0.25 and 1.25, an extra 0.25 in each direction. If xsupport=-1, default values are chosen according to the relative horizontal dimensions of the source and destination, similarly if ysupport=-1 default values are chosen according to the relative vertical dimensions of the source and destination.

If mode='l', interpolation over the area of support is linear. If mode='g', interpolation over the area of support is Gaussian weighted; this option yields improved results when significantly enlarging an image, at the expense of increased execution time.

The sip and dip areas of interest may be of different dimensions, and reference different image buffers or areas of interest in the same image buffer, however the effect of the operation when sip and dip overlap is undefined. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. A math coprocessor is recommended.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

PXERLOGIC
Internal error, notify Technical Support.
Copy Image with Rotation --- pxip8_geotranrotate
Copy Image with Rotation & Offset --- pxip8_geotranrotate2



Summary 
int pxip8_geotranrotate (abortp, sip, dip, angle, saspect, daspect, origin, mode);
int pxip8_geotranrotate2(abortp, sip, dip, angle, saspect, daspect, origind,
                         xoffset, yoffset, rsvd1, rsvd2, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
double              angle;          // rotation in degrees
double              saspect;        // source aspect ratio: X/Y
double              daspect;        // destination aspect ratio: X/Y
struct  pxy         *origin;        // center of rotation
struct  pxyd        *origind;       // center of rotation
int                 mode;           // 'n': nearest neighbor,
                                    // 'b': bilinear interpolation
double              xoffset;        // horizontal offset
double              yoffset;        // vertical offset
int                 rsvd1;          // reserved. should be 0
int                 rsvd2;          // reserved. should be 0



Description

The content of the image referenced by sip is copied with rotation around a specified origin to the image referenced by dip. The image is rotated angle degrees clockwise about the origin defined by the x and y coordinates in the pxy structure referenced by origin, or the pxyd structure referenced by origind. The aspect ratio of the original image is specified by saspect (x/y), the aspect ratio of the result image is specified by daspect (x/y); if saspect and daspect are both 1 the rotation is computed strictly upon the numeric x, y coordinates. The saspect should be the same as daspect for common applications in which the original and result image are displayed under the same video format and resolution. For pxip8_geotranrotate2, the origin within sip is also offset by xoffset and yoffset.

If mode='n', result pixels are taken from the nearest original pixel at the rotated coordinates. If mode='b', result pixel values are computed by bilinear interpolation from the four nearest original pixels at the rotated coordinates.

The sip and dip areas of interest must be of identical dimensions, and reference different image buffers or areas of interest in the same image buffer, however the effect of the operation when sip and dip overlap is undefined. The image referenced by sip is not modified, except by overlap with dip. If an area of interest is used, note that the origin coordinates are relative to the sip area of interest.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. A math coprocessor is recommended.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

The first image frame buffer is rotated 45 degrees about its center, and stored in the second image frame buffer. Note that the origin coordinates are relative to the area of interest. 

struct  pxy     origin;


origin.x = pxd_xdim() / 2;                  // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
origin.y = (pxd_ydim()<<pxd_ylace())/2;     // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
origin.x = pxd_imageXdim()/2;               // starting coordinate  w. XCLIB
origin.y = pxd_imageYdim()/2;               // starting coordinate  w. XCLIB


pxip8_geotranrotate(NULL,
                    #if 1       // w. XCLIB
                      pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                      pxd_defineImage(1,2,0,0,-1,-1,"Default"),
                    #else       // w. SVOBJ,4MOBJ,XCOBJ
                      pxd_defimage(1,0,0,-1,-1),
                      pxd_defimage(2,0,0,-1,-1),
                    #endif
                    45.0, 1.3, 1.3, &origin, 'b');
The first image frame buffer is rotated 15 degrees about its upper left corner, and stored in the second image frame buffer. 
origin.x = origin.y = 0;
pxip8_geotranrotate(NULL,
                    #if 1       // w. XCLIB
                      pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                      pxd_defineImage(1,2,0,0,-1,-1,"Default"),
                    #else       // w. SVOBJ,4MOBJ,XCOBJ
                      pxd_defimage(1,0,0,-1,-1),
                      pxd_defimage(2,0,0,-1,-1),
                    #endif
                    15.0, 1.3, 1.3, &origin, 'b');
Copy Image with Warping --- pxip8_geotranwarp
Copy Image with Warping --- pxip8_geotranwarp2



Summary 
int pxip8_geotranwarp(abortp, sip, dip, nfiduc, sfiduc, dfiduc, mode);
int pxip8_geotranwarp2(abortp, sip, dip, nfiduc, sdfiduc, ddfiduc, mode, rsvd1, rsvd2);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // source
struct pximage      *dip;           // destination
size_t              nfiduc;         // # of fiducials, >= 4
struct pxy          sfiduc[];       // n source image fiducials
struct pxy          dfiduc[];       // matching dest image fiducials
struct pxyd         sdfiduc[];      // n source image fiducials
struct pxyd         ddfiduc[];      // matching dest image fiducials
int                 mode;           // 'n': nearest neighbor,
                                    // 'b': bilinear interpolation
int                 rsvd1;          // reserved. should be 0
int                 rsvd2;          // reserved. should be 0



Description

The content of the image referenced by sip is copied with geometric warping to the image referenced by dip. The sfiduc and dfiduc (or sdfiduc and ddfiduc) define the nfiduc fiducial points within sip and dip; the sip image is warped so that each sfiduc[i] (or sdfiduc[i]) coordinate is mapped to the corresponding dfiduc[i] (or ddfiduc[i]) coordinate, for 4<=i<=nfiduc. The sfiduc and dfiduc (or sdfiduc and ddfiduc) coordinates are interpreted as absolute image coordinates, and not relative to any area of interest.

If mode='n', result pixels are taken from the nearest original pixel at the warped coordinates. If mode='b', result pixel values are computed by bilinear interpolation from the four nearest original pixels at the warped coordinates.

The pxip8_geotranwarp partitions the image into quadrilaterals, each fiducial defining a vertex of one or more quadrilaterals. Within each quadrilateral two second order polynomial equations are fitted to the vertex coordinates; the polynomials are used to compute coordinates for each pixel within the quadrilateral. Any pixels of dip that are outside of any quadrilateral are set to value 0; the four corners of dip must be fiducials if this is to be avoided. Each sfiduc[i] coordinate is mapped exactly to the corresponding dfiduc[i], but there may be discontinuities in dip at the edges of each quadrilateral.

The pxip8_geotranwarp2 fits a single set of polynomial equations to the entire set of fiducials; the polynomials are used to compute coordinates for each pixel. Any pixels of dip for which the polynomials evaluate to coordinates out of the image are set to value 0. As a single set of polynomials is used for all pixels, there are no discontinuities in dip at the edge of each quadrilateral, however sfiduc[i] coordinate may not map exactly to the corresponding dfiduc[i] coordinate.

The sip and dip areas of interest may be of different dimensions, and reference different image buffers or areas of interest in the same image buffer, however the effect of the operation when sip and dip overlap is undefined. The image referenced by sip is not modified, except by overlap with dip. If an area of interest is used, note that the origin coordinates are relative to the sip area of interest.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. A math coprocessor is recommended.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Copy Image with Pincushion/Barrel Warping --- pxip8_geotranpincushion2



Summary 
int pxip8_geotranpincushion2(abortp, sip, dip, order, coef, aspect, origin, mode, scalex, scaley);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // source
struct pximage      *dip;           // destination
int                 order;          // 3: 3rd order
                                    // 5: fifth order
                                    // 7: seventh order
                                    // 0x100: quick option w. shortcuts
                                    // 0x200: horizontal warp only
double              coef[];         // coefficients
double              aspect;         // pixel aspect ratio
pxyd_s              *origin;        // optical center of distortion
int                 mode;           // 'n': nearest neighbor,
                                    // 'b': bilinear interpolation
double              scalex;         // x scale result
double              scaley;         // y scale result






Description


The content of the image referenced by
sip
is copied with pincushion or barrel warping to
the image referenced by
dip.
Applying barrel warping corrects for the lens'
pincushion distortion, and vice versa.


If
order=3,
a third order equation is used for barrel distortion; the
coef
array of coefficients is:



    0,
    0,
    0,
    3rd_order_coefficient




with an implied 1st order coefficient of 1.0 .
If
order=5,
a fifth order equation is used for barrel distortion; the
coef
array of coefficients is:



    0,
    1st_order_coefficient,
    2nd_order_coefficient,
    3rd_order_coefficient,
    4th_order_coefficient,
    5th_order_coefficient




If
order=7,
a seventh order equation is used for barrel distortion; the
coef
array of coefficients is:



    0,
    1st_order_coefficient,
    2nd_order_coefficient,
    3rd_order_coefficient,
    4th_order_coefficient,
    5th_order_coefficient
    6th_order_coefficient,
    7th_order_coefficient




A polynomial with the specified coefficients
is evaluated to map old coordinates
to new coordinates relative to the
origin
optical center;
for the purpose of polynomial
evaluation, pixel coordinates range from -1 thru 1.


If
order&0x100,
computational shortcuts are used
to speed up the processing;
this may cause pixels on the borderline of two adjacent locations
to be shifted.
If
order&0x200,
only horizontal warping is applied, as would be
useful with a line scan camera;
the
''computational shortcut''
option, above, is currently ignored
in horizontal warping mode.
If
order
is negative
then barrel distortion is performed;
the absolute value
of
order
is used to select third, fifth, or seventh order
and to select computational shortcuts and horizontal mode.


The
origin->xd
and
origin->yd
specify the optical center of the distortion and warping;
processing may be slightly faster
when using the image center as the optical center.


The
aspect
specifies the aspect ratio (x/y) of the pixels,
and allows the same non-linear warping equations to be applied
and have the same visual effect
both vertically and horizontally, even though the
image dimensionality differs.


If
mode='n',
result pixels are taken from the nearest original pixel at the warped coordinates.
If
mode='b',
result pixel values are computed by bilinear interpolation from the four
nearest original pixels at the warped coordinates.


The
scalex
and
scaley
specify post-warp scaling
and
allows the (nonrectangular) warped image to be enlarged, or shrunk,
before truncation to fit into the (rectangular)
dip.
The scaling
allows choosing whether
''bulges''
along the image boundary will be visible along with black areas,
or whether black areas along the image boundary will be
''clipped''
along with bulging areas of the original image.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Copy & Skew Image Left/Right   ---   pxip8_copyskewlr







Copy & Skew Image Up/Down   ---   pxip8_copyskewud







Summary



int pxip8_copyskewlr(abortp, sip, dip, mode, skewtop, skewbot);
int pxip8_copyskewud(abortp, sip, dip, mode, skewleft, skewright);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // 'n': nearest neighbor
int                 skewtop;        // pixels of left/right skew at top edge
int                 skewbot;        // pixels of left/right skew at bottom edge
int                 skewleft;       // pixels of up/down skew at left edge
int                 skewright;      // pixels of up/down skew at right edge










Description


The source image
referenced by
sip
is copied with skew to the destination image
buffer
referenced by
dip.


The
pxip8_copyskewlr
skews the image lines left or right.
The
skewtop
specifies the number of pixels the top line should be skewed;
towards the right is positive, towards the left is negative.
Similarly,
skewbot
specifies the number of pixels the bottom line should be skewed.
Image lines between the top and bottom are skewed
proportionally to their distance from the top and bottom lines.
Lines are skewed an integer number of pixels;
i.e. using nearest neighbor rather than (for example) a bilinear interpolation.


The
pxip8_copyskewud
skews the image columns up or down.
The
skewleft
specifies the number of pixels the left column should be skewed;
towards the bottom is positive, towards the top is negative.
Similarly,
skewright
specifies the number of pixels the right column should be skewed.
Image columns between the left and right are skewed
proportionally to their distance from the left and right columns.
Lines are skewed an integer number of pixels;
i.e. using nearest neighbor rather than (for example) a bilinear interpolation.


The
pxip8_copyskewlr
and
pxip8_copyskewud
can be used to approximate small degrees of image rotation,
and would be significantly faster
than using the more general and powerful
pxip8_geotranrotate.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Copy & Spatial Replicate/Decimation   ---   pxip8_copyreplic







Summary



int pxip8_copyreplic(abortp, sip, dip, xfactor, yfactor, mode);
int pxip8_copyreplicate(abortp, sip, dip, xfactor, yfactor, mode, orient);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 xfactor;        // >0: x replicate factor,
                                    // <0: x decimate factor
int                 yfactor;        // >0: y replicate factor,
                                    // <0: y decimate factor
int                 mode;           // reserved. should be 0
int                 orient;         // 'u', 'd', 'l', or 'r'
                                    // 'u'^'M', 'd'^'M', 'l'^'M', or 'r'^'M'










Description


Pixels of the image referenced by
sip
are spatially replicated or decimated with the result placed in
the image referenced by
dip.
For
pxip8_copyreplicate,
the image may be copied with any of 8 orientations,
providing rotations of
0°, 90°, 180°, and 270°,
each of which may be reflected about the (original) vertical
center (i.e. mirror image flipped).



Pixels of
sip
are processed left to right and top to bottom.
Each pixel is replicated
xfactor
times horizontally, where
xfactor>0;
or pixels are decimated (subsampled) horizontally by a factor of
-xfactor,where
xfactor<0.
Each pixel is replicated
yfactor
times vertically, where
yfactor>0;
or pixels are decimated (subsampled) vertically by a factor of
-yfactor,where
yfactor<0.
Thus, for
xfactor>0
and
yfactor>0,
the upper left block of
xfactor
by
yfactor
pixels of
dip
are set to the value of the upper left pixel of
sip,
the block of
dip
immediately to the right
set to the value
of the pixel of
sip
immediately to the right,
and the block of
dip
immediately below set to the value of the pixel of
sip
immediately below.


Should the
sip
after replication or decimation by
xfactor
and
yfactor
be larger than
dip,
excess pixels along the right and/or bottom edge of
sip
are ignored.
Should the
sip
after replication or decimation by
xfactor
and
yfactor
be smaller than
dip,
excess pixels along the right and/or bottom edge of
dip
are set to value 0.


The
orient
specifies the rotation and reflection to be performed.
If
orient='u'
or
orient=0
no rotation is performed.
For
orient='l',
orient='d',
and
orient='r'
the top of the source image becomes
oriented left, down, or right,
respectively.
If
orient='u'^'M',
orient='l'^'M',
orient='d'^'M',
or
orient='r'^'M',
the image is first reflected about the vertical center and the top
becomes oriented up, left, down, or right,
respectively.
'ne 1i
Graphically, a source image of:



           .  .  .
        .  .  .  .
        .  .  .  .




'ne 1i
becomes (ignoring resizing):



 'u'       .  .  .          'u'^'M'     .  .  .
        .  .  .  .                      .  .  .  .
        .  .  .  .                      .  .  .  .


 'l'    .  .  .             'l'^'M'        .  .
        .  .  .                         .  .  .
        .  .  .                         .  .  .
           .  .                         .  .  .


 'd'    .  .  .  .          'd'^'M'     .  .  .  .
        .  .  .  .                      .  .  .  .
        .  .  .                            .  .  .


 'r'    .  .                'r'^'M'     .  .  .
        .  .  .                         .  .  .
        .  .  .                         .  .  .
        .  .  .                         .  .






The
pxip8_copyreplic
and
pxip8_copyreplicate
effectively performs image enlargement, or zoom.
While
pxip8_copyinterpbilinear
can also be used for enlargement,
providing smooth transitions from pixel to pixel,
the
pxip8_copyreplic
or
pxip8_copyreplicate
is significantly quicker, albeit with a blockier result.


The
sip
and
dip
areas of interest may be of different dimensions,
and reference different image buffers
or areas of interest in the same image buffer,
however the effect of the operation when
sip
and
dip
overlap is undefined.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels of 1 to 16 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.
Note that source or destination dimensions of unity are considered
invalid for this operation.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



16.  Transform Operations









FFT: Transform Image   ---   pxip8_fft







Summary



int pxip8_fft(abortp, gip, cip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *gip;           // spatial domain image, source
struct  pximage     *cip;           // frequency domain, complex, image, result










Description


A Discrete or Fast Fourier Transform is applied
to the spatial domain image in the image referenced by
gip,
and the frequency domain result put in the complex image referenced by
cip.
The frequency domain coefficients are shifted so that low
frequencies are in the center of
cip.


As symmetry considerations are used to reduce the size
of the frequency domain representation, the dimensions of
cip
are not identical to
gip.
Nor is the relationship of pixels in
gip
to complex numbers in
cip
obvious.
The
pxip8_fftsizes
should be used to obtain the
required dimensions and pixie type of
cip.
The
pxip8_fftcimage
may be used to provide access to the frequency domain's complex numbers,
without concern for the rules of symmetry, reflections, and complex conjugants.


The operation will perform upon arbitrary image dimensions,
but will be significantly faster for image dimensions
that are a power of 2.


The image referenced by
gip
is not modified, except by overlap with
cip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome spatial images, of any type and precision pixel.
A math coprocessor is recommended.


COC40

Monochrome spatial images, of any type and precision pixel.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








Example



struct  pximage cimage;
struct  pxy     xy;
int             type, r;


pxip8_fftsizes(
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Default"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               &xy, &type);                     // get size of complex, freq, image


#if 0
    //
    // Version 1: Use upper portion of image memory for the complex image.
    // Most suitable for frame grabbers with on-board memory, and
    // PC's with little memory. This ASSUMES sufficient image memory!
    // This assumes use of SVOBJ or 4MOBJ.
    //
    pxdrvsetpximage(&cimage,0,&xy,type,0,2);    // find size of pixel of 'type'
    pxdrvsetpximage(&cimage,                    // place complex image at back of image memory.
                    pxd_imsize()*1024-(ulong)xy.x*xy.y*cimage.f.pixelsize,
                    &xy, type, 0, 2);
    pxip8_fft(NULL, pxd_defimage(1,0,0,-1,-1), &cimage);     // do FFT/DFT
#else
{   //
    // Version 2: Use PC memory for the complex image,
    // which must be freed when done. Most suitable for
    // 32 bit (or larger) programming environments where there is
    // sufficient PC memory for the complex image.
    //
    void _far16p *bufp = NULL;  // handle to image buffer
    r = pximage_memmalloc(&cimage, &bufp, &xy, type, 0, 2, 0);
    if (r >= 0) {
        pxip8_fft(NULL,
                  #if 1       // w. XCLIB
                    pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                  #else       // w. SVOBJ,4MOBJ,XCOBJ
                    pxd_defimage(1,0,0,-1,-1),
                  #endif
                  &cimage); // do FFT/DFT
        ..
        pximage_memfree(&cimage, &bufp);        // when done with complex image
    }
}
#endif












FFT: Inverse Transform Image   ---   pxip8_ffti







Summary



int pxip8_ffti(abortp, cip, gip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *cip;           // frequency domain, complex, image, source
struct  pximage     *gip;           // spatial domain image, result
int                 mode;           // 0:   pixel = real
                                    // 's': pixel = scaled real










Description


An inverse
Discrete or Fast Fourier Transform is applied to the
frequency domain complex image referenced by
cip,
and the spatial domain result placed in the
image referenced by
gip.
The frequency domain image is destroyed.


If
mode=0,
each spatial domain pixel is set to the
real value of the corresponding complex coefficient.
Real coefficients less than 0 or greater than the maximum
gip
pixel value (255 for 8 bit pixels)
are respectively limited to spatial domain values of 0 and the maximum
gip
pixel value.
If
mode='s',
each spatial domain pixel is set to the
scaled real value of the corresponding complex coefficient,
with the scale factor chosen so that the
complex coefficient's real values are scaled to the maximum
gip
pixel value (255 for 8 bit pixels),
and values less than 0 limited to 0.


The operation will perform upon arbitrary image dimensions,
but will be significantly faster for image dimensions
that are a power of 2.


The
cip
should be of the type and size described under
pxip8_fft.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome spatial images, of any type and precision pixel.
A math coprocessor is recommended.


COC40

Monochrome spatial images, of any type and precision pixel.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










FFT: Log Magnitude Plot of Freq. Domain   ---   pxip8_fftlogmag







Summary



int pxip8_fftlogmag(abortp, cip, gip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *cip;           // frequency domain, complex, image, source
struct  pximage     *gip;           // spatial domain image, result










Description


A log magnitude plot of the frequency domain complex image referenced by
cip
is placed in the image referenced by
gip.
The maximum coefficient magnitude of the frequency domain
is mapped to ½ of the maximum
gip
grey level value (e.g. ½ of 255 for 8 bit pixels).
The low frequencies are placed in the center of the log magnitude plot.


The
cip
should be of the type and size described under
pxip8_fft.
The image referenced by
cip
is not modified, except by overlap with
gip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome spatial images, of any type and precision pixel.
A math coprocessor is recommended.


COC40

Monochrome spatial images, of any type and precision pixel.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










FFT: Scale Freq. Domain by Log Magnitude Plot   ---   pxip8_fftlmagscale







Summary



int pxip8_fftlmagscale(abortp, gip, cip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *gip;           // spatial domain image, source
struct  pximage     *cip;           // frequency domain, complex, image, result










Description


Each real and imaginary coefficient of the
frequency domain complex image referenced by
cip
is scaled in proportion to
the ratio of the corresponding pixel value in
the spatial image referenced by
gip
and the log magnitude,
scaled to ½ of the maximum
gip
pixel value,
of the coefficient.


This operation supports simple filtering of the frequency domain
produced by
pxip8_fft
by using spatial domain operations.
A typical sequence of operations, assuming
an FFT has already been performed is:



struct  pximage cimage;                                     // assume already set,


pxip8_fftlogmag(NULL, &cimage,                              // make logmag image
                #if 1       // w. XCLIB
                  pxd_defineImage(1,1,0,0,-1,-1,"Grey"));
                #else       // w. SVOBJ,4MOBJ,XCOBJ
                  pxd_defimage(1,0,0,-1,-1));
                #endif
gimage.wind.nw.x += gimage.wind.se.x/4;                     // define AOI
gimage.wind.nw.y += gimage.wind.se.y/4;                     // which is the
gimage.wind.se.x -= gimage.wind.se.x/4;                     // central quarter
gimage.wind.se.y -= gimage.wind.se.y/4;
pxip8_pixscale(&gimage, &gimage, 3, 2);                     // intensify
pxip8_fftlmagscale(NULL, &gimage, &cimage);                 // modify frequency domain
pxip8_ffti(NULL, &cimage, gimadrs, 's');                    // inverse FFT




The
pxip8_fftlogmag
sets each pixel to the log magnitude of the corresponding complex coefficients.
The
pxip8_pixscale
scales some of the pixels containing the log magnitude of the frequency.
The
pxip8_fftlmagscale
then
scales each complex coefficient in proportion to the ratio
of the corresponding new log magnitude value,
versus the original log magnitude value.
In the example above,
all complex coefficients in the center
would be increased by exp(1.5),
and all other coefficients unchanged.
(This is not intended to be a useful frequency domain filter,
just a simple example!).


The
cip
should be of the type and size described under
pxip8_fft.
The image referenced by
gip
is not modified, except by overlap with
cip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome spatial images, of any type and precision pixel.
A math coprocessor is recommended.


COC40

Monochrome spatial images, of any type and precision pixel.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










FFT: Filter Frequency Domain   ---   pxip8_fftfilterz







Summary



int pxip8_fftfilterz(abortp, gip, cip, mode, arg);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *gip;           // spatial domain image, source
struct  pximage     *cip;           // frequency domain, complex, image, result
int                 mode;           // filter selection
double              parm;           // filter parameter










Description


A zero-memory
frequency domain filter is applied to the
frequency domain complex image referenced by
cip.
The
gip
image reference serves only to define the dimensions
of
cip.


If
mode='r',
a root filter, with the root specified by
parm,
is applied to the frequency domain;
i.e. the magnitude of each coefficient is replaced by its
parm
root, and the coefficient's phase unchanged.
On common images the effect is that of a high pass filter.
A value of
parm=.8
is suggested for initial experimentation.


If
mode='g',
a Gaussian filter
with a standard deviation proportional to
parm,
is applied to the frequency domain;
i.e. each coefficient is scaled by a Gaussian curve
centered at the lowest frequency.
The
parm
is the actual standard deviation when used with
image dimensions of 512x512;
for other image dimensions the
parm
is scaled so that a particular value of
parm
has (approximately) the same effect regardless of image size.
On common images the effect is that of a low pass filter.
A value of
parm=100.0
is suggested for initial experimentation.


If
mode='G',
an inverse Gaussian filter
with a standard deviation proportional to
parm,
is applied to the frequency domain representation;
i.e. each coefficient is scaled by an inverted Gaussian curve
centered at the highest frequency.
The
parm
is the actual standard deviation when used with
image dimensions of 512x512;
for other image dimensions the
parm
is scaled so that a particular value of
parm
has (approximately) the same effect regardless of image size.
On common images the effect is that of a high pass filter.
A value of
parm=200.0
is suggested for initial experimentation.


As the filter operations have the side effect of scaling the
overall magnitude (i.e. after the inverse transform
of the frequency domain) of the image,
following the filter operations by
pxip8_ffti
with its
's'
mode of operation is recommended.


The
cip
should be of the type and size described under
pxip8_fft.
The image referenced by
gip
is not modified, except by overlap with
cip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome spatial images, of any type and precision pixel.
A math coprocessor is recommended.


COC40

Monochrome spatial images, of any type and precision pixel.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








See Also


Jain, A.K.,
FUNDAMENTALS OF IMAGE PROCESSING,
1989,
pp. 256-263.








FFT: Get Dimensions of Freq. Domain Representation   ---   pxip8_fftsizes







Summary



int pxip8_fftsizes(gip, dimp, typep);
struct  pximage     *gip;           // spatial domain image
struct  pxy         *dimp;          // required dimensions, returned
int                 *typep;         // required pixie type: PXDAT*










Description


The dimensions of the complex image required
to contain the frequency domain representation of the image referenced by
gip
is
''returned''
at
*dimp,
and the pixie type expected of the complex image by the
pxip8_fft
series of functions is
''returned''
at
*typep.


The image referenced by
gip
is not modified.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.








See Also


See
pxip8_fft
for example of use.








Construct PXIMAGE: Access Freq. Domain Complex Image   ---   pxip8_fftcimage







Summary



int pxip8_fftcimage(fullcip, cip, dimp);
struct pximage      *fullcip;       // constructed
struct pximage      *cip;           // underlying complex image
struct pxy          *dimp;          // dimensions of spatial image










Description


A
pximage
referenced by
fullcip
is initialized, thereafter
allowing access to the frequency domain coefficients
in the complex image referenced by
cip,
which was previously created as described in
pxip8_fft
to be used with spatial images of the dimensions
referenced by
dimp.


Unlike
cip,
whose dimensions are smaller than described in
dimp,
the
fullcip
has the same dimensions as
dimp,
with a one-to-one correspondence
with complex pixels in
fullcip
and the original spatial pixels.
When coefficients of
fullcip
are read, any missing coefficients are recreated
according to the rules of symmetry governing
the frequency domain representation of a real spatial (or time)
domain image.
Coefficients of
fullcip
may also be written,
some coefficients will be thrown away, expecting that they
can be recreated by the rules of symmetry.


The
fullcip
does not support the
pximage.bxt*
member functions.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

The pixel type of
cip
is incorrect, or its dimensions are inconsistent
with spatial dimensions
*dimp.
The image
*fullcip
is set to an image with dimensions of 0.








Example



struct  pximage gimage;     // assume already set and the
struct  pximage cimage;     // FFT performed as per pxip8_fft(), then ...
struct  pximage fullcimage;
float   coef[2];
int     x;
struct  pxy xy;


xy.x = gimage.wind.se.x - gimage.wind.nw.x;
xy.y = gimage.wind.se.y - gimage.wind.nw.y;
pxip8_fftcimage(&fullcimage, &cimage, &xy);                   // create image
(fullcimage.ioset)(&fullximage, PXRXSCAN, PXDATFLOAT, 0x03);  // init access
for (x = 0; x < xy.x; x++) {
    (fullcimage.ioread)(&fullcimage, 0, &coef, 1, x, xy.y/2);
    printf("(%f,%f) ", coef[0], coef[1])                      // print coefficients
}                                                             // of middle line







 
 
 



17.  Correlation Operations









Correlation Profile   ---   pxip8_correlateprof







Correlation Peak   ---   pxip8_correlatefind







Summary



int pxip8_correlateprof(abortp, s1p, s2p, dip, xsubsam, ysubsam, mode);
int pxip8_correlatefind(abortp, s1p, s2p, xsubsam, ysubsam, mode, nrslt, rsltp);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1, mask
struct  pximage     *s2p;           // source 2, image
struct  pximage     *dip;           // destination
int                 xsubsam;        // subsample mask & image, horizontally
int                 ysubsam;        // subsample mask & image, vertically
int                 mode;           // 'n': normalized, 0: unnormalized
size_t              nrslt;          // dimension of rsltp[]
struct  pxip8corr   rsltp[];        // the best results




struct pxip8corr
{
    struct  pxyd    xy;             // coordinates
    double          r;              // correlation coefficient
};










Description


The
pxip8_correlateprof
performs a correlation of the
mask in the image referenced by
s1p
over the image referenced by
s2p,
and places a correlation profile in the image referenced by
dip.


The
pxip8_correlatefind
performs a correlation of the
mask in the image referenced by
s1p
over the image referenced by
s2p,
and reports the positions with highest correlation.


The
s1p
mask is scanned over the larger
s2p
image, at each position the correlation is computed,
and the pixel of
s2p
which corresponds to the center position of the mask
is set to the pixel's maximum value (255 for 8 bit pixels)
multiplied by the correlation coefficient;
higher values indicate a larger degree of correlation.


If
xsubsam=1
and
ysubsam=1,
every pixel of the mask, and every corresponding
pixel of the image, are used in the correlation.
Either
xsubsam
and/or
ysubsam
may be larger than 1; every
xsubsam'th
pixel in the horizontal direction
and every
ysubsam'th
pixel in the vertical direction
are used in the correlation.
Furthermore, the mask is repositioned over the
image at intervals of
xsubsam
and
ysubsam.
Use of
xsubsam>1
or
ysubsam>1
allows faster processing,
at the expense of accuracy.
For example, with
xsubsam=2
and
ysubsam=2,
processing is 16 times quicker;
at each location of the mask on the image
a factor of 22 fewer pixels are correlated,
and the mask is positioned at a factor of 22 fewer locations
on the image.


If
mode='n',
a normalized correlation is computed;
the normalized correlation is insensitive
to additive offsets and multiplicative scaling.
If
mode=0,
an unnormalized, or absolute value, correlation is computed.


The
pxip8_correlateprof
creates a profile image in
dip,
with pixels values proportional to the degree of correlation.
An unsigned integer pixel value of 0 indicating a correlation of 0.0,
and at its maximum value indicating a correlation of 1.0.
A float or double pixel value is equal to the correlation.
For pixels of
s2p
that are on the boundary, or
pixels skipped due to
xsubsam>1
or
ysubsam>1,
the corresponding pixels of
dip
are set to 0.


The
pxip8_correlatefind
returns the coordinates and correlation coefficient
of the
nrslt
coordinates with the highest correlation.
The
rsltp[0].r
and
rsltp[0].xy
is the highest coefficient and coordinates, the
rsltp[1].r
and
rsltp[1].xy
the second highest, etc.


The
s2p
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The
s1p
area of interest must be smaller than that of
s2p.
The image referenced by
s1p
and
s2p
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.
Monochrome, of float or double pixels.
The
pxip8_correlateprof
also supports using unsigned integer pixels for
s1p
and
s2p
along with float pixels
for
dip.
A math coprocessor is recommended.


COC40

Monochrome, of uchar pixels, of 1 to 8 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



18.  Interlace Shuffle Operations









Field Interlaced Image Line Shuffle   ---   pxip8_ilacelinetofield







Field Interlaced Image Line UnShuffle   ---   pxip8_ilacefieldtoline







Summary



int pxip8_ilacelinetofield(abortp, sip, dip);
int pxip8_ilacefieldtoline(abortp, sip, dip);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination










Description


The
pxip8_ilacelinetofield
and
pxip8_ilacefieldtoline
shuffle image lines, converting the image referenced by
sip
between the two common interlace image memory storage formats
(all lines consecutive, or all lines in each field consecutive),
with the result placed in the image referenced by
dip.
These functions
need
not
be used when capturing and then processing interlaced images;
any necessary line translations are done automatically.
These functions are useful in conjunction with file
format conversion,
or in special cases when digitizing in one video format (say noninterlaced)
while displaying in a different video format
(say interlaced, and where the
hardware, such as the SILICON VIDEO® frame grabber,
requires lines in each field to be consecutive).


Using an example image with 8 lines,
the effect of
pxip8_ilacelinetofield
is:







BEFORE 


 AFTER








Line 0 


 Line 0






Line 1 


 Line 2






Line 2 


 Line 4






Line 3 


 Line 6






Line 4 


 Line 1






Line 5 


 Line 3






Line 6 


 Line 5






Line 7 


 Line 7









putting all even lines in the first half of the image
and all odd lines in the second half of the image,
resulting in the
''lines of each field consecutive''
format.
'ne 1i
The effect of
pxip8_ilacefieldtoline
is:







BEFORE 


 AFTER








Line 0 


 Line 0






Line 1 


 Line 4






Line 2 


 Line 1






Line 3 


 Line 5






Line 4 


 Line 2






Line 5 


 Line 6






Line 6 


 Line 3






Line 7 


 Line 7









taking an image in
''lines of each field consecutive''
format and restoring it to
''all lines consecutive''
format.
The
pxip8_ilacelinetofield
and
pxip8_ilacefieldtoline
are inverse operations of each other.


Neither
pxip8_ilacelinetofield
nor
pxip8_ilacefieldtoline
have a proper definition if used upon an image with an odd number of lines.
In such cases, the last line of
sip
is copied to the last line of
dip,
and the operation proceeds with the remaining even number of lines.


If
pxip8_ilacelinetofield
or
pxip8_ilacefieldtoline
is performed while displaying the image,
unlike other operations which generally show a top-to-bottom
flow, these operations
will show an apparently random garbling of the image
which is then resolved into the correct result.
This is an expected side effect of the algorithm used,
which executes the shuffle in minimal time and (buffer) space, even when
sip
and
dip
are the same image.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters, including less than 2 image lines.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










De-Flicker Interlace: Modify Singularities   ---   pxip8_ilacemodsingular







Summary



int pxip8_ilacemodsingular(abortp,sip,dip,mode,threshold,midwt,endwt);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // always 't'
int                 threshold;      // significant pixel difference
int                 midwt;          // modify center by midwt/16
int                 endwt;          // modify ends by midwt/16










Description


Each vertical group of three pixels in the
image referenced by
sip
are examined, modified if the difference between the
end pixels and the
center pixel's value is greater than
threshold,
and the result placed in the destination image referenced by
dip.
This operation is intended to reduce interlace flicker caused by
fine line graphics, without reducing the resolution of grey scale imagery.


If the group's center pixel is greater than the end pixels
and
the minimum difference between the group's center pixel
and end pixels is greater than
threshold,
the center pixel's value is reduced by:



minimum_difference * midwt / 16




and the end pixels' values are increased by:



minimum_difference * endwt / 16




The opposite effect occurs if the group's center pixel is less than
the end pixels.


The overall effect is to
''smear''
high contrast single pixel horizontal lines into the
adjacent lines, without modifying grey level components
or edges of high contrast multiple line graphics.
Choices of
endwt
and
midwt
allow control of the smearing.
For example,
midwt=8
and
endwt=4
maintain the overall (sum) of the three pixel's intensities,
ignoring round off error,
performing:







10  


→


55






200 


→


110






20  


→


65









(a
threshold=128
is assumed).
This would maintain the same overall image display intensity,
if the image monitor's response was linear.
As another example,
midwt=0
and
endwt=16
set the end pixels to (almost) the same value as the middle pixel,
performing:







10  


→


190






200 


→


200






20  


→


200









Note that pixels representing a high contrast edge,
such as:







10






200






200









are not modified.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










De-Flicker Interlace: Line Pair Average   ---   pxip8_ilacepairave







Summary



int pxip8_ilacepairave(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination










Description


Corresponding pixels in each even/odd pair of lines in the
image referenced by
sip
are averaged together, the average replacing both pixels,
and the result placed in the destination image referenced by
dip.
For color pixels, each corresponding component (i.e.
''pixie'')
of each pixel are averaged together, the average replacing both pixies.
This operation eliminates image flicker when displaying
distinct fields in an interlaced video format,
but at the expense of a reduction in vertical resolution.


For example, an image of five pixels and four lines:







1 


 2


 3


 4


 5






10


10


10


10


10






20


20


20


20


20






 5


 4


 3


 2


 1









would be replaced by:







5 


 6


 6


 7


 7






5 


 6


 6


 7


 7






12


12


11


11


10






12


12


11


11


10











The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










De-Flicker Interlace: Line Pair Duplicate   ---   pxip8_ilacepairdup







Summary



int pxip8_ilacepairdup(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // 0: duplicate even lines, 1: duplicate odd lines










Description


Each even (or odd) numbered line of pixels of the image reference by
sip
is duplicated into
the odd (or even) numbered line of pixels immediately below (or above)
and the result placed in the destination image referenced by
dip.
If
mode=0,
even numbered lines are duplicated into odd numbered lines.
If
mode=1,
odd numbered lines are duplicated into even numbered lines.
This operation eliminates image flicker when displaying
distinct fields in an interlaced video format,
but at the expense of a reduction in vertical resolution.


For example, an image of five pixels and four lines:







1 


 2


 3


 4


 5






10


10


10


10


10






20


20


20


20


20






 5


 4


 3


 2


 1









and
mode=0
would be replaced by:







1 


 2


 3


 4


 5






1 


 2


 3


 4


 5






20


20


20


20


20






20


20


20


20


20











The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Swap Line or Column Pairs   ---   pxip8_ilacepairswap







Summary



int pxip8_ilacepairswap(abortp, sip, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // 0: swap lines 0<->1, 2<->3, ...
                                    // 1: swap lines 1<->2, 3<->4, ...
                                    // 2: swap columns 0<->1, 2<->3, ...
                                    // 3: swap columns 1<->2, 3<->4, ...










Description


Each even/odd pair of lines, or
each even/odd pair of columns,
in the image referenced by
sip
are copied to the destination image defined
dip,
with the position of the even and odd lines, or columns, interchanged.
Boundary lines with a swap partner are copied unchanged.
The effect with
mode=0
(showing the effect of the boundary condition caused by an odd number of lines)
is:







BEFORE 


 AFTER






Line 0 


 Line 1






Line 1 


 Line 0






Line 2 


 Line 3






Line 3 


 Line 2






Line 4 


 Line 4









The effect with:
mode=1
is:







BEFORE 


 AFTER






Line 0 


 Line 0






Line 1 


 Line 2






Line 2 


 Line 1






Line 3 


 Line 4






Line 4 


 Line 3






Line 5 


 Line 5











The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Shift Image One-Half Line Up or Down   ---   pxip8_ilacelineshift







Summary



int pxip8_ilacelineshift(abortp, sip, dip, direction, mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 direction;      // 'u': up, 'd': down
int                 mode;           // reserved. should be 0










Description


The
pxip8_ilacelineshift
copy and shifts the image referenced by
sip
one-half line up or down to
dip,
by interpolation of corresponding pixels
in adjacent lines.
The
pxip8_ilacelineshift
can be used to modify an image containing a single interlaced field
so as to better align with an image containing the opposite interlaced field.


If
direction='u',
the image is copied one-half line up;
the bottom-most line of the source
is copied unchanged to the bottom-most line of the destination.
If
direction='d',
the image is copied one-half line down;
the top-most line of the source
is copied unchanged to the top-most line of the destination.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters, including less than 2 image lines.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










N-Field Interlaced Image Line Shuffle   ---   pxip8_ilacelinetoNfield







N-Field Interlaced Image Line UnShuffle   ---   pxip8_ilaceNfieldtoline







Summary



int pxip8_ilacelinetoNfield(abortp, sip, dip, nfield);
int pxip8_ilaceNfieldtoline(abortp, sip, dip, nfield);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 nfield;         // number of fields, > 0










Description


The
pxip8_ilacelinetoNfield
shuffles image lines of the image referenced by
sip
from a consecutive line order
to a grouping into sections according to the remainder
of the line's coordinate after division by
nfield,
with the result placed in the image referenced by
dip.
The
pxip8_ilaceNfieldtoline
does the inverse.


The
pxip8_ilacelinetoNfield
and
pxip8_ilaceNfieldtoline
are generalizations of
pxip8_ilacelinetofield
and
pxip8_ilacefieldtoline,
respectively,
and have identical effect for
nfield=2.


Neither
pxip8_ilacelinetoNfield
nor
pxip8_ilaceNfieldtoline
have a proper definition if used upon an image with a number of lines
not divisible by
nfield.
In such cases, the bottom
''remainder''
lines of
sip
are copied to the corresponding lines of
dip.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Shuffle Column Order to Even-Odd Halves   ---   pxip8_xlacecolumntohalves







Shuffle Even-Odd Halves to Column Order   ---   pxip8_xlacehalvestocolumn







Summary



int pxip8_xlacecolumntohalves(abortp, sip, dip, mode);
int pxip8_xlacehalvestocolumn(abortp, sip, dip, mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0










Description


The
pxip8_xlacecolumntohalves
shuffles pixels within image lines of
the image referenced by
sip,
rearranging pixels at even locations to the left half
of the line and pixels at odd locations to the right
half of the line,
with the result placed in the image referenced by
dip.
Should
sip
have an odd number of pixels per line
the right-most odd pixel is copied unchanged.


Using an example image with 1 line, 8 pixels per line:



    A B C D E F G H




the result of
pxip8_xlacecolumntohalves
is



    A C E G B D F H






The
pxip8_xlacehalvestocolumn
is the inverse of
pxip8_xlacecolumntohalves,
shuffling pixels within image lines of
the image referenced by
sip,
rearranging pixels at the left half of the line to even locations
and pixels at the right half of the line to odd locations,
with the result placed in the image referenced by
dip.
Should
sip
have an odd number of pixels per line
the right-most odd pixel is copied unchanged.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.










Line Pair Pixel Shuffle   ---   pxip8_xlaceshuffle







Line Pair Pixel UnShuffle   ---   pxip8_xlaceunshuffle







Summary



int pxip8_xlaceshuffle(abortp, sip, dip, mode);
int pxip8_xlaceunshuffle(abortp, sip, dip, mode);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0










Description


The
pxip8_xlaceshuffle
and
pxip8_xlaceunshuffle
shuffle pixels within pairs of image lines of
the image referenced by
sip
with the result placed in the image referenced by
dip.


Using an example image with 4 lines, 8 pixels per line:



A B C D E F G H
I J K L M N O P
Q R S T U V W X
Y Z a b c d e f




the result of
pxip8_xlaceshuffle
is:



A I B J C K D L
E M F N G O H P
Q Y R Z S a T b
U c V d W e X f




The effect of
pxip8_xlaceunshuffle
is the exact inverse of
pxip8_xlaceshuffle.


The
pxip8_xlaceshuffle
and
pxip8_xlaceunshuffle
are defined, above, for images with an
even number of pixels per line and even number of lines.
Should the image referenced by
sip
have an odd number of pixels per line, or an odd number of lines,
the right odd pixel, and/or the bottom odd line, are copied unchanged;
with the shuffle operation performed on the remaining pixels and lines.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Shuffle Column Order to N Sections   ---   pxip8_xlacecolumntoNsection







Shuffle N Sections to Column Order   ---   pxip8_xlaceNsectiontocolumn







Summary



int pxip8_xlacecolumntoNsection(abortp, sip, dip, mode, nsection);
int pxip8_xlaceNsectiontocolumn(abortp, sip, dip, mode, nsection);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 mode;           // reserved. should be 0
int                 nsection;       // number of fields, > 0










Description


The
pxip8_xlacecolumntoNsection
shuffles image columns of the image referenced by
sip
from a consecutive column order
to a grouping into sections according to the remainder
of the column's coordinate after division by
nsection,
with the result placed in the image referenced by
dip.
The
pxip8_xlaceNsectiontocolumn
does the inverse.


The
pxip8_xlacecolumntoNsection
and
pxip8_xlaceNsectiontocolumn
are generalizations of
pxip8_xlacecolumntohalves
and
pxip8_xlacehalvestocolumn,
respectively,
and have identical effect for
nsection=2.


Neither
pxip8_xlacecolumntoNsection
nor
pxip8_xlaceNsectiontocolumn
have a proper definition if used upon an image with a number of columns
not divisible by
nsection.
In such cases, the rightmost
''remainder''
columns of
sip
are copied to the corresponding columns of
dip.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



19.  Nonrectangular Regions - Support Functions



Selected functions provide
image processing operations on image regions which need
not be rectangular and parallel to the axis.
These functions utilize the
pximregion
structure to define the image region to be operated upon.
Most of the image processing functions are, except for use of the
pximregion
structure,
identical to a similarly named function which uses a
pximage
structure and operates upon rectangular image areas parallel to the axis.


The
pximregion
version functions which specify both source and destination image regions
are defined for use with regions of identical size and shape.








PXIMREGION: NonRectangular Image Region Specification   ---   struct pximregion







Summary





struct pximregion
{
    struct  pximage image;          // image. the image.wind may
                                    // be interpreted as a clipping window


    int     regiontype;             // type as below
    uint    length;                 // byte length of this variable length struct
    struct  pxy origin;             // origin/offset of regions. not used ..
                                    // for PXIMREGWIND, PXIMREGSCANLIST(B)


    union pximregiondesc {


      /*
       * Window, defined by upper-left origin, width, height.
       * The origin or any part of the rectangle may extend beyond the image.wind.
       */
      struct  pximregwindow {
          int     width;
          int     height;
      } window;


      /*
       * Rectangle, defined by center/origin, width, height, rotation.
       * The origin or any part of the rectangle may extend beyond the image.wind.
       */
      struct  pximregrectangle {
          int     width;
          int     height;
          float   angle;
      } rectangle;
      struct  pximregrectanglef {
          pxyf_s  originf;      // added to integer origin
          float   width;
          float   height;
          float   angle;
      } rectanglef;




      /*
       * Ellipse defined by center/origin, width, height, rotation.
       * The origin or any part of the ellipse may extend beyond the image.wind.
       * Code may assume that this and pximregrectangle are identical.
       */
      struct  pximregellipse {
          int     width;
          int     height;
          float   angle;
      } ellipse;
      struct  pximregellipsef {
          pxyf_s  originf;        // added to integer origin
          float   width;
          float   height;
          float   angle;
      } ellipsef;


      /*
       * Frame defined by intersection of two rectangles,
       * each with width, height, rotation.
       * The origin or any part of the rectangle may
       * extend beyond the image.wind.
       */
      struct  pximregframe {
          int     outerwidth;
          int     outerheight;
          float   outerangle;
          int     innerwidth;
          int     innerheight;
          float   innerangle;
      } frame;
      struct  pximregframef {
          pxyf_s  originf;        // added to integer origin
          float   outerwidth;
          float   outerheight;
          float   outerangle;
          float   innerwidth;
          float   innerheight;
          float   innerangle;
      } framef;


      /*
       * Generalized annulus defined by intersection of two ellipses,
       * each with width, height, rotation.
       * The origin or any part of the ellipses may
       * extend beyond the image.wind. Code may assume that
       * this and pximregframe are identical.
       */
      struct  pximregannulus {
          int     outerwidth;
          int     outerheight;
          float   outerangle;
          int     innerwidth;
          int     innerheight;
          float   innerangle;
      } annulus;
      struct  pximregannulusf {
          pxyf_s  originf;        // added to integer origin
          float   outerwidth;
          float   outerheight;
          float   outerangle;
          float   innerwidth;
          float   innerheight;
          float   innerangle;
      } annulusf;


      /*
       * Arc of annulus defined by intersection of two ellipses,
       * each with width, height, rotation.
       * The origin or any part of the ellipses may
       * extend beyond the image.wind.
       */
      struct  pximregannulusarc {
          int     outerwidth;
          int     outerheight;
          float   outerangle;
          int     innerwidth;
          int     innerheight;
          float   innerangle;
          float   starta;
          float   enda;
      } annulusarc;
      struct  pximregannulusarcf {
          pxyf_s  originf;        // added to integer origin
          float   outerwidth;
          float   outerheight;
          float   outerangle;
          float   innerwidth;
          float   innerheight;
          float   innerangle;
          float   starta;
          float   enda;
      } annulusarcf;


      /*
       * Polygon, defined as N vertices. Any part of the polygon may extend beyond the
       * image.wind. The vertex[4] definition allows room for a PXIMREGRECTANGLE to be
       * easily translated to a 4'th order polygon. Each vertex is relative to the origin.
       */
      struct pximpolygon {
          int     N;                // number of vertices
          struct pxy vertex[4];     // actually N
      } polygon;


      /*
       * Scan list, defined as pixel runs at x, y coordinates. Coordinates & runs don't
       * extend beyond image.wind. The origin is reserved, and should be 0.
       *
       * Also, the bounded scan list; offset by the origin, and bounded by the image.wind.
       */
      struct  pximregscanlist {
          int     N;                // number of scans
          struct  pximregscanlists
          {
              struct  pxy coord;    // in order, y, y+1, y+2!
              pxcoord_t len;        // pixel length across x
          } scanlists[1];           // actually N
      } scanlist;


      /*
       * Pixel path list. Directions are nibble encoded (low then high) as:
       * If nibble's high bit set, low 3 bits are direction and    3  2  1
       * following nibble is replication factor-2. The origin is   4  *  0
       * the start pixel. The origin or any part of the path may   5  6  7
       * extend beyond the image.wind. Directions are absolute, not relative
       * to the last direction of travel; a 0 is always an increment of the
       * x coordinate.
       */
      struct  pximregpath {
          int     N;                // # of nibbles or nibble/rpt pairs
          struct  pxy txy;          // unused, handy for applic. pgms
          uchar   pathlist[1];      // direction nibbles
      } path;
    } region;
};










Description


The
pximregion
struct is used to define an image region which, unlike the
pximage's
area of interest need not be rectangular
and parallel to the image axis, or may be
''clipped''
by the image edge(s).
The
pximregion
struct is used to encode a variety of image region types;
interpretation of the fields varies from type to type.
All types are based upon a
pximage
structure to define an image,
and then, additionally, define a region within that image.


Ten region types are currently defined.




PXIMREGWIND.
The type
PXIMREGWIND
region area is rectangular and parallel to the axis.
The rectangular area's specification must be bounded
by image's dimensions;
it is simply a
pximage
and its
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGWIND;
imregion.length     = sizeof imregion;
imregion.image.wind.nw.x = 0;
imregion.image.wind.nw.y = 0;
imregion.image.wind.se.x = imregion.image.imdim.se.x/2;
imregion.image.wind.se.y = imregion.image.imdim.se.y/2;




defines the upper left quadrant of the first frame buffer.




PXIMREGWINDOW.
The type
PXIMREGWINDOW
region area is rectangular and parallel to the axis,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGWINDOW;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/4;
imregion.origin.x   = imregion.image.imdim.se.x/4;
imregion.region.window.width  = imregion.image.imdim.se.x/2;
imregion.region.window.height = imregion.image.imdim.se.y/2;




defines the middle half of the first frame buffer.
The type
PXIMREGWINDOW|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGWINDOW
region area, bounded by the
pximage.wind.




PXIMREGRECTANGLE.
The type
PXIMREGRECTANGLE
region area is rectangular, specified by its center, dimensions, and rotation,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGRECTANGLE;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.rectangle.width  = 20;
imregion.region.rectangle.height = 20;
imregion.region.rectangle.angle  = 3.14159265358979323846/4;




defines a rectangle at the center of the first frame buffer,
with a width and height of 20 pixels,
rotated by
pi/4
radians (counterclockwise).
The width and height are dimensions along the axis, prior to rotation.
The type
PXIMREGRECTANGLE|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGRECTANGLE,
region area, bounded by the
pximage.wind.




PXIMREGRECTANGLEF.
The type
PXIMREGRECTANGLEF
and
PXIMREGRECTANGLEF|PXIMREGNEGATIVE
is similar to
PXIMREGRECTANGLE
and
PXIMREGRECTANGLE|PXIMREGNEGATIVE
respectively,
allowing specification of the origin, width, and height
as non-integers.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype  = PXIMREGRECTANGLEF;
imregion.length      = sizeof imregion;
imregion.origin.x    = imregion.image.imdim.se.x/2;
imregion.origin.y    = imregion.image.imdim.se.y/2;
imregion.region.rectanglef.originf.xf = (imregion.image.imdim.se.x/2.0) - imregion.origin.x;
imregion.region.rectanglef.originf.yf = (imregion.image.imdim.se.y/2.0) - imregion.origin.y;
imregion.region.rectanglef.width      = 20.3;
imregion.region.rectanglef.height     = 20.3;
imregion.region.rectanglef.angle      = 3.14159265358979323846/4;








PXIMREGELLIPSE.
The type
PXIMREGELLIPSE
region area is elliptical specified by its center, dimensions, and angle of rotation,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGELLIPSE;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.ellipse.width  = 40;
imregion.region.ellipse.height = 20;
imregion.region.ellipse.angle  = 3.14159265358979323846/4;




defines an ellipse at the center of the first frame buffer,
with a width of 40 and height of 20 pixels,
rotated by
pi/4
radians (counterclockwise).
The width and height are dimensions along the axis, prior to rotation.
The type
PXIMREGELLIPSE|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGELLIPSE
region area, bounded by the
pximage.wind.




PXIMREGELIPSEF.
The type
PXIMREGELLIPSEF
and
PXIMREGELLIPSEF|PXIMREGNEGATIVE
is similar to
PXIMREGELLIPSE
and
PXIMREGELLIPSE|PXIMREGNEGATIVE
respectively,
allowing specification of the origin, width, and height
as non-integers.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype  = PXIMREGELLIPSEF;
imregion.length      = sizeof imregion;
imregion.origin.x    = 0;
imregion.origin.y    = 0;
imregion.region.ellipsef.originf.xf = imregion.image.imdim.se.x/2.0;
imregion.region.ellipsef.originf.yf = imregion.image.imdim.se.y/2.0;
imregion.region.ellipsef.width      = 20.3;
imregion.region.ellipsef.height     = 20.3;
imregion.region.ellipsef.angle      = 3.14159265358979323846/4;








PXIMREGFRAME.
The type
PXIMREGFRAME
region area is a rectangular frame, the intersection (i.e. difference) between two rectangular areas,
specified by its center, dimensions of its inner and outer
rectangles, and angle of rotation of its inner and outer rectangles,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGFRAME;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.frame.innerwidth  = 40;
imregion.region.frame.innerheight = 20;
imregion.region.frame.outerwidth  = 80;
imregion.region.frame.outerheight = 40;
imregion.region.frame.innerangle  = 3.14159265358979323846/4;
imregion.region.frame.outerangle  = 3.14159265358979323846/4;




defines a rectangular frame at the center of the first frame buffer,
with an outer width of 80 and height of 40 pixels,
with an inner width of 40 and height of 20 pixels,
rotated by
pi/4
radians (counterclockwise).
The widths and heights are dimensions along the axis, prior to rotation.
The type
PXIMREGFRAME|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGFRAME
region area, bounded by the
pximage.wind.




PXIMREGFRAMEF.
The type
PXIMREGFRAMEF
and
PXIMREGFRAMEF|PXIMREGNEGATIVE
is similar to
PXIMREGFRAME
and
PXIMREGFRAME|PXIMREGNEGATIVE
respectively,
allowing specification of the origin, widths, and heights
as non-integers.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGFRAMEF;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.framef.originf.xf = (imregion.image.imdim.se.x/2.0) - imregion.origin.x;
imregion.region.framef.originf.yf = (imregion.image.imdim.se.y/2.0) - imregion.origin.y;
imregion.region.framef.innerwidth  = 40.6;
imregion.region.framef.innerheight = 20.2;
imregion.region.framef.outerwidth  = 80.8;
imregion.region.framef.outerheight = 40.4;
imregion.region.framef.innerangle  = 3.14159265358979323846/4;
imregion.region.framef.outerangle  = 3.14159265358979323846/4;








PXIMREGANNULUS.
The type
PXIMREGANNULUS
region area is an annulus, the intersection (i.e. difference) between two ellipses,
specified by its center, dimensions of its inner and outer
ellipses, and angle of rotation of its inner and outer ellipses,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGANNULUS;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.annulus.innerwidth  = 40;
imregion.region.annulus.innerheight = 20;
imregion.region.annulus.outerwidth  = 80;
imregion.region.annulus.outerheight = 40;
imregion.region.annulus.innerangle  = 3.14159265358979323846/4;
imregion.region.annulus.outerangle  = 3.14159265358979323846/4;




defines an annulus at the center of the first frame buffer,
with an outer width of 80 and height of 40 pixels,
with an inner width of 40 and height of 20 pixels,
rotated by
pi/4
radians (counterclockwise).
The widths and heights are dimensions along the axis, prior to rotation.
The type
PXIMREGANNULUS|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGANNULUS
region area, bounded by the
pximage.wind.




PXIMREGANNULUSF.
The type
PXIMREGANNULUSF
and
PXIMREGANNULUSF|PXIMREGNEGATIVE
is similar to
PXIMREGANNULUS
and
PXIMREGANNULUS|PXIMREGNEGATIVE
respectively,
allowing specification of the origin, widths, and heights
as non-integers.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGANNULUSF;
imregion.length     = sizeof imregion;
imregion.origin.x   = 0;
imregion.origin.y   = 0;
imregion.region.annulusf.originf.xf = imregion.image.imdim.se.x/2.0;
imregion.region.annulusf.originf.yf = imregion.image.imdim.se.y/2.0;
imregion.region.annulusf.innerwidth  = 40.6;
imregion.region.annulusf.innerheight = 20.2;
imregion.region.annulusf.outerwidth  = 80.8;
imregion.region.annulusf.outerheight = 40.4;
imregion.region.annulusf.innerangle  = 3.14159265358979323846/4;
imregion.region.annulusf.outerangle  = 3.14159265358979323846/4;








PXIMREGANNULUSARC.
The type
PXIMREGANNULUSARC
region area is an arc of an annulus, the intersection (i.e. difference) between an annulus and a sector,
specified by its center, dimensions of its inner and outer
ellipses, angle of rotation of its inner and outer ellipses,
and a start and end angle,
clipped by the
pximage.wind.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGANNULUSARC;
imregion.length     = sizeof imregion;
imregion.origin.x   = imregion.image.imdim.se.x/2;
imregion.origin.y   = imregion.image.imdim.se.y/2;
imregion.region.annulusarc.innerwidth  = 40;
imregion.region.annulusarc.innerheight = 20;
imregion.region.annulusarc.outerwidth  = 80;
imregion.region.annulusarc.outerheight = 40;
imregion.region.annulusarc.innerangle  = 3.14159265358979323846/4;
imregion.region.annulusarc.outerangle  = 3.14159265358979323846/4;
imregion.region.annulusarc.starta      = 0.0;
imregion.region.annulusarc.enda        = 3.14159265358979323846;




defines one half (180 degrees) of the same annulus
as described in the PXIMREGANNULUS example
in the first frame buffer.
The type
PXIMREGANNULUSARC|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGANNULUSARC
region area, bounded by the
pximage.wind.




PXIMREGANNULUSARCF.
The type
PXIMREGANNULUSARCF
and
PXIMREGANNULUSARCF|PXIMREGNEGATIVE
is similar to
PXIMREGANNULUSARC
and
PXIMREGANNULUSARC|PXIMREGNEGATIVE
respectively,
allowing specification of the origin, width, and height
as non-integers.
For example:



struct  pximregion  imregion;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.regiontype = PXIMREGANNULUSARCF;
imregion.length     = sizeof imregion;
imregion.origin.x   = 0;
imregion.origin.y   = 0;
imregion.region.annulusarcf.originf.xf  = imregion.image.imdim.se.x/2.0;
imregion.region.annulusarcf.originf.yf  = imregion.image.imdim.se.y/2.0;
imregion.region.annulusarcf.innerwidth  = 40.2;
imregion.region.annulusarcf.innerheight = 20.6;
imregion.region.annulusarcf.outerwidth  = 80.3;
imregion.region.annulusarcf.outerheight = 40.7;
imregion.region.annulusarcf.innerangle  = 3.14159265358979323846/4;
imregion.region.annulusarcf.outerangle  = 3.14159265358979323846/4;
imregion.region.annulusarcf.starta      = 0.0;
imregion.region.annulusarcf.enda        = 3.14159265358979323846;








PXIMREGPOLYGON and PXIMREGPOLYGONX.
The type
PXIMREGPOLYGON
and
PXIMREGPOLYGONX
region areas are
N
sided polygons,
N≥3,
specified by a list of
N
coordinates of vertices relative to the origin,
clipped by the
pximage.wind.
A type of
PXIMREGPOLYGONX
is assumed to be a convex polygon, yielding more efficient processing.
Note that the basic
imregion
declaration provides space for up to 4 vertices,
and must be extended for additional vertices.
For example:



struct {
    struct  pximregion  imreg;
    struct  pxy         morevertex[2];
} imregion;
struct  pxy *xyp;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.imreg.regiontype       = PXIMREGPOLYGONX;
imregion.imreg.length           = sizeof imregion;
imregion.imreg.region.polygon.N = 6;
imregion.imreg.origin.x         = 0;
imregion.imreg.origin.y         = 0;
xyp = &imregion.imreg.region.polygon.vertex[0];
xyp[0].x = 20;  xyp[0].y = 0;
xyp[1].x = 40;  xyp[1].y = 0;
xyp[2].x = 60;  xyp[2].y = 20;
xyp[3].x = 40;  xyp[3].y = 40;
xyp[4].x = 20;  xyp[4].y = 40;
xyp[5].x = 0;   xyp[5].y = 20;




defines a regular 6 sided polygon in the first frame buffer.
The type
PXIMREGPOLYGON|PXIMREGNEGATIVE
and
PXIMREGPOLYGONX|PXIMREGNEGATIVE
region areas are the complement of the
PXIMREGPOLYGON
and
PXIMREGPOLYGONX
region areas, respectively, bounded by the
pximage.wind.


Note: The
morevertex
provides sufficient space for additional vertices, but must
not
be used to code the vertices; the example above should be followed.




PXIMREGSCANLIST and PXIMREGSCANLISTB.
The type
PXIMREGSCANLIST
and
PXIMREGSCANLISTB
region areas are of arbitrary shape,
defined by a list of x, y coordinates and scan length along x.
The type
PXIMREGSCANLISTB
is clipped by the
pximage.wind.
Unless specified otherwise for a particular operation,
the region defined by
PXIMREGSCANLIST
or
PXIMREGSCANLISTB
need not be connected.
Note that the basic
imregion
declaration provides space for a single scan,
and must be extended for additional scans.
For example:



struct {
    struct  pximregion          imreg;
    struct  pximregscanlists    morelists[6;
} imregion;
struct  pximregscanlists *lp;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.imreg.regiontype        = PXIMREGSCANLISTB;
imregion.imreg.length            = sizeof imregion;
imregion.imreg.region.scanlist.N = 7;
imregion.imreg.origin.x = 0;      // ignored for PXIMREGSCANLIST
imregion.imreg.origin.y = 0;      // ignored for PXIMREGSCANLIST
lp = &imregion.imreg.region.scanlist.scanlists[0];
lp[0].coord.x = 10; lp[0].coord.y = 0;  lp[0].len = 10;
lp[1].coord.x = 11; lp[1].coord.y = 1;  lp[1].len = 8;
lp[2].coord.x = 12; lp[2].coord.y = 2;  lp[2].len = 6;
lp[3].coord.x = 13; lp[3].coord.y = 3;  lp[3].len = 4;
lp[4].coord.x = 12; lp[4].coord.y = 4;  lp[4].len = 6;
lp[5].coord.x = 11; lp[5].coord.y = 5;  lp[5].len = 8;
lp[6].coord.x = 10; lp[6].coord.y = 6;  lp[6].len = 10;




defines an hourglass shape in the first frame buffer.


Note: The
morelists
provides sufficient space for additional scans, but must
not
be used to code the scans; the example above should be followed.
For more efficient processing, the PXIMREGSCANLIST is interpreted
as absolute scans; i.e. not relative to the origin
and not bounded (i.e. clipped) by the window.




PXIMREGPATH.
The type
PXIMREGPATH
region areas are of arbitrary shape,
defined by a starting coordinate and a path to
''walk''
around the area's boundary,
clipped by the
pximage.wind.
Some operations assume that the
PXIMREGPATH
defines a simple closed region;
i.e. that the path does not cross itself.
Each pixel step of the path is encoded as one of eight directions
by the convention:



3  2  1
4  *  0
5  6  7




where
''*''
represents the current position.
Each such step is encoded in a nibble[26],
under the convention that low nibbles precede high nibbles.
A single step is encoded as one of the eight directions
in the low order 3 bits of a nibble with the high order bit 0.
If the high order bit is 1, the low order 3 bits define a direction,
and the following nibble defines the replication factor-2.
Note that the basic
imregion
declaration provides space for only two nibbles[27],
and must be extended for additional steps.
For example, an region area of:



 . . . . . . . . .
 . x x x x x . . .
 . . x x x x x . .
 . . x x x x x x .
 . . . . . . . . .




where the upper left corner is coordinate 0, 0
is encoded by:[28]



struct {
    struct  pximregion          imreg;
    struct  pximregscanlists    morepaths[3];
} imregion;
uchar   *cp;


imregion.image = *pxd_defimage(1,0,0,-1,-1);    // w. SVOBJ,4MOBJ,XCOBJ
imregion.image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"); // w. XCLIB
imregion.imreg.regiontype    = PXIMREGPATH;
imregion.imreg.length        = sizeof imregion;
imregion.imreg.region.path.N = 6;
imregion.imreg.origin.x      = 1;
imregion.imreg.origin.y      = 1;
cp = &imregion.region.path.pathlist[0];
cp[0]  = 0|0x8;         // direction
cp[0] |= (4-2)<<4;      // replication
cp[1]  = 7;             // direction
cp[1] |= 7<<4;          // direction
cp[2]  = 4|0x8;         // direction
cp[2] |= (5-2)<<4;      // replication
cp[3]  = 2;             // direction
cp[3] |= 3<<4;          // direction




defines a shaped region in the first frame buffer.
The type
PXIMREGPATH|PXIMREGNEGATIVE
region area is the complement of the
PXIMREGPATH
region area, bounded by the
pximage.wind.


Note: The
morepaths
provides sufficient space for additional steps, but must
not
be used to code the additional steps; the example above should be followed.








Modify Region Definition: Rectangle to Polygon   ---   pxirp_xlaterecttopoly







Summary



int pxirp_xlaterecttopoly(rp);
struct  pximregion  *rp;










Description


The image region definition referenced by
rp
is transformed, in place, from type
PXIMREGRECTANGLE
or
PXIMREGRECTANGLE|PXIMREGNEGATIVE
to type
PXIMREGPOLYGON
or
PXIMREGPOLYGON|PXIMREGNEGATIVE,
respectively,
with four sides
describing the same image area.


Use of
pxirp_xlaterecttopoly
has no effect on any image buffer.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

The
pximregion
structure referenced by
rp
was not type
PXIMREGRECTANGLE
or
PXIMREGRECTANGLE|PXIMREGNEGATIVE
and was not modified.










Translate Region Definition to Scan List   ---   pxirp_xlatetoscanlist







Summary



int pxirp_xlatetoscanlist(abortp, rp, npp, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *rp;            // original
struct  pximregion  **npp;          // *NULL, becomes *result, malloc'ed!!
int                 mode            // ignored, use 0










Description


The image region definition referenced by
rp
is copied and transformed to type
PXIMREGSCANLIST,
describing the same image area.
The image region definition referenced by
rp
is not modified.
The
*npp
must initially be NULL;
the new image region definition is placed in
malloc'ed
memory and
''returned''
at
*npp.
The
mode
is not currently used and should be 0.


Note that most of the image processing functions which accept a
pximregion
internally use the
PXIMREGSCANLISTS
type.
All such functions transparently translate the
pximregion
provided, but do not alter the original
pximregion.
Any
pximregion
to be used multiple times may be explicitly converted with
pxirp_xlatetoscanlist,
thereby eliminating multiple internal, transparent, translations.


Use of
pxirp_xlatetoscanlist
has no effect on any image buffer.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








See Also


See
pxirp_regionfree
to free the region created by
pxirp_xlatetoscanlist.








Translate Region Definition to Path   ---   pxirp_xlatetopath







Summary



int pxirp_xlatetopath(abortp, rp, npp, mode);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximregion  *rp;            // original
struct  pximregion  **npp;          // *NULL, becomes *result, malloc'ed!!
int                 mode            // ignored, use 0










Description


The image region definition referenced by
rp
is copied and transformed to type
PXIMREGPATH,
describing the same image area with the path interpreted as the
inclusive, outer, boundary of the region.
The image region definition referenced by
rp
is not modified.
The
*npp
must initially be NULL;
the new image region definition is placed in
malloc'ed
memory and
''returned''
at
*npp.
The
mode
is not currently used and should be 0.


The
pxirp_xlatetopath
expects that the region referenced by
rp
is a single connected shape.
The effect of
pxirp_xlatetopath
on a region, particularly type
PXIMREGSCANLISTS,
which may represent two or more disconnected regions,
is undefined.


The path
''returned''
at
*npp
is not compressed, but may be so by invoking
pxirp_pathcompress.


Use of
pxirp_xlatetopath
has no effect on any image buffer.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.








See Also


See
pxirp_regionfree
to free the region created by
pxirp_xlatetopath.








Find Region's Enclosing Window   ---   pxirp_regionbounds







Summary



int pxirp_regionbounds(rp, wp, mode);
struct  pximregion  *rp;            // image region
struct  pxywindow   *wp;            // result enclosing window
int                 mode;           //  0:  ignore image dimensions
                                    // 'w': bound by rp->image.wind










Description


The coordinates of the smallest rectangle
which encloses the image region definition referenced by
rp
is
''returned''
at
*wp.
As customary, the
wp->nw
are inclusive coordinates
and the
wp->se
are exclusive coordinates.


Regions of types
using the
PXIMREGNEGATIVE
adjective are not supported by this operation.


If all or part of the region referenced by
rp
is beyond the basic image dimensions
(i.e. the
rp->image.imdim
or
rp->image.wind),
then if
mode=0
the enclosing rectangle coordinates will also be beyond the basic
image dimensions.
If
mode='w',
the enclosing window coordinate will be bounded by the
rp->image.wind.


Use of
pxirp_regionbounds
has no effect on any image buffer.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



1

Operation complete.


0

If
mode=0,
the region referenced by
rp
has neither height nor width.
If
mode='w',
the region referenced by
rp
has neither height nor width,
or no part of the region intersects the image window.
In either case, the
*wp
is unchanged.


PXERROR

Invalid parameters.










Find Region's Enclosed Area   ---   pxirp_regionarea







Summary



int pxirp_regionarea(rp, mode, areap);
struct  pximregion  *rp;            // image region
int                 mode;           // rsvd. use 'w'
pxim2size_t         *areap;         // returned !










Description


The area in pixels of the region referenced by
rp
is
''returned''
at
*areap.


If all or part of the region referenced by
rp
is beyond the basic image dimensions
(i.e. the
rp->image.imdim
or
rp->image.wind),
then the area returned is that portion of the region
bounded by the
rp->image.wind.


Use of
pxirp_regionarea
has no effect on any image buffer.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.










Free Region   ---   pxirp_regionfree







Summary



void pxirp_regionfree(regionpp);
struct pximregion   **regionpp      // *handle to region










Description


A
pximregion
created in
malloc'ed
memory by
pxirp8_connectregion,
pxirp8_connectregionv,
pxirp_pathcreate,
pxirp_xlatetopath,
pxirp_xlatetoscanlist,
or
pxirp8_followregionv
and referenced by
*regionpp
is released,
and all memory used is
free'ed.


After
pxirp_regionfree,
the
*regionpp
is invalid, set to NULL, and must not be used with any function.


Under
some
environments the application program can simply
free
the
pximregion
instead of using
pxirp_regionfree.
However, when the
pximregion
was
malloc'ed
by a library function inside a Windows DLL,
the
pximregion
must
be
free'ed
within the same DLL[29],
by using
pxirp_regionfree.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns


None.








Scan, Connect, Collect Region by Table   ---   pxirp8_connectregion







Scan, Connect, Collect Region by Value   ---   pxirp8_connectregionv







Summary



int pxirp8_connectregion(abortp, sip, xyp, testmap, nmap, testbit, npp, mode);
int pxirp8_connectregionv(abortp, sip, xyp, cond, value, npp, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // image w. boundary info
struct  pxy         *xyp;           // fill seed coordinate
struct  pximregion  **npp;          // *NULL, becomes *result, malloc'ed!!
int                 mode;           // 'e': boundary excluded from region
                                    // 'i': boundary pixels included into region
                                    // | PXIP8BLOB_CONVEX: assume convex region, seed on top line
                                    // | PXIP8BLOB_NOHOLE: assume region without holes


uchar               *testmap;       // defines boundary pixels
size_t              nmap,           // dimension of above
int                 testbit;        // .. by testmap[pixelvalue]&testbit


int                 cond;           // defines pixel values to be found
uint                value;          // by pixvalue>value, pixvalue<value, etc.










Description


A region of the image referenced by
sip
is scanned and coded as a
pximregion.
The region is referenced by a seed coordinate in
sip,
namely,
xyp,
with the region extended to
all connected pixels until an image boundary is reached.


For
pxirp8_connectregion,
the boundary condition is defined by
testmap
and
testbit;
pixel values such that
testmap[pixelvalue]&testbit
is nonzero are boundary pixels.


For
pxirp8_connectregionv,
the boundary condition is defined by
cond
and
value;
boundary pixels are those for which the comparison of the
pixel value and
value
is true.
The
cond
defines the comparison performed:







cond     


 comparison








'g'^'e'  


 pixel >= value






'l'^'t'  


 pixel <  value






'g'^'t'  


 pixel >  value






'l'^'e'  


 pixel <= value






'e'^'q'  


 pixel == value






'n'^'e'  


 pixel != value











Eight-way connectivity of the boundary is sufficient to stop connectivity,
i.e. for:



 .  B  .  .  .  .
 .  B  .  .  .  .
 .  .  B  .  .  .
 .  .  B  .  .  .




pixels
''B''
do define a boundary between the left and right parts.
If
mode='e',
the boundary pixels are not included in the region;
if
mode='i'
boundary pixels are included in the region.
If the
mode
is OR'ed with PXIP8BLOB_CONVEX, the region is assumed to be convex
and the
*xyp
assumed to be on the region's top line.
If the
mode
is OR'ed with PXIP8BLOB_NOHOLE, the region is assumed not to contain
any holes.[30]
With these assumptions, and use of the 'e' mode,
execution is, approximately, two or four times faster.
If
mode
is OR'ed with PXIP8BLOB_CONVEX or PXIP8BLOB_NOHOLE,
and the assumptions are not true, only part of
the region, or an excess beyond the region, may be scanned and coded.


The
*npp
must initially be NULL;
the
pximregion
representing the connected image region is placed in
malloc'ed
memory and
''returned''
at
*npp.
The
pximregion
is of type
PXIMREGSCANLIST.


The
sip
must be a full image.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








See Also


See
pxirp_regionfree
to free the region created by
pxirp8_connectregion
and
pxirp8_connectregionv.








Follow and Collect Region Boundary by Value   ---   pxirp8_followregionv







Summary



int pxirp8_followregionv(abortp, sip, rsvd, xyp, cond, value, mode, npp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image w. boundary info
void                *rsvd;          // reserved. must be NULL
struct pxy          *xyp;           // start coordinate
int                 cond;           // defines pixel values to be found
uint                value;          // by pixvalue>value, pixvalue<value, etc.
int                 mode;           // reserved. should be 0
struct pximregion   **npp           // *NULL, becomes *result, malloc'ed










Description


The perimeter of a region of the image referenced by
sip
is followed and coded as a
pximregion.
The region perimeter is defined by a start coordinate in
sip,
namely,
xyp,
with the perimeter followed clockwise until the start coordinate is
reached.
The coded path is inclusive,
i.e. of the region's outermost pixels, using 8-way
connectivity.


Pixels which belong to the region
are defined by
cond
and
value;
region pixels are those for which the comparison of the
pixel value and
value
is true.
The
cond
defines the comparison performed:







cond     


 comparison








'g'^'e'  


 pixel >= value






'l'^'t'  


 pixel <  value






'g'^'t'  


 pixel >  value






'l'^'e'  


 pixel <= value






'e'^'q'  


 pixel == value






'n'^'e'  


 pixel != value











The
pxirp8_followregionv
assumes that the start pixel,
*xyp,
is on the region's perimeter and satisfies the
cond
and
value
comparison,
and that the pixel left of the start pixel,
xyp->x-1,
xyp->y
is not on the region's perimeter and does not
satisfy the
cond
and
value
comparison
(alternately,
xyp->x-1,
xyp->y
may be outside of the image).


The
*npp
must initially be NULL;
the
pximregion
representing the connected image region is placed in
malloc'ed
memory and
''returned''
at
*npp.
The
pximregion
is of type
PXIMREGPATH,
or type PXIMREGSCANLIST if the region contains a single pixel
(the PXIMREGPATH can't describe a path which encloses a single pixel region).


The
sip
must be a full image.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).


PXERLOGIC

Internal error, notify Technical Support.








See Also


See
pxirp_regionfree
to free the region created by
pxirp8_followregionv.








Initialize Region Path   ---   pxirp_pathcreate







Extend Region Path   ---   pxirp_pathextend







Extend Region Path   ---   pxirp_pathextend1







Summary



int pxirp_pathcreate(rpp, start);
struct  pximregion  **rpp;          // *NULL, becomes *result, malloc'ed!
struct  pxy         *start;         // path start coordinate


int pxirp_pathextend(rpp, exy);
int pxirp_pathextend1(rpp, exy);
struct  pximregion  **rpp;          // *pximregion, may be re-malloc'ed!
struct  pxy         *exy;           // new end coordinate










Description


The
pxirp_pathcreate,
pxirp_pathextend,
and
pxirp_pathextend1
are utility functions to aid incremental building of a
PXIMREGPATH
type
pximregion
structure.
Neither function has any effect on any image buffer.


The
pxirp_pathcreate
creates a
pximregion
structure as type
PXIMREGPATH,
with starting coordinate
start,
and no pixel steps
(i.e. the
pximregion.region.path.N=0).
The
*rpp
must initially be NULL;
the
malloc'ed
structure is
''returned''
at
*rpp.
The
pximregion.image
is not set by
pxirp_pathcreate.


The
pxirp_pathextend
or
pxirp_pathextend1,
using the existing
pximregion
at
*rpp,
extends the path from its current end point to coordinate
exy.
The
pxirp_pathextend,
allows any arbitrary coordinate
exy;
the
pxirp_pathextend1
assumes coordinate
exy
is one pixel distant (8-way connectivity)
from the previous path end point.
The
pxirp_pathextend1
is more efficient than
pxirp_pathextend.
As the
pximregion
at
*rpp
may not have sufficient space to contain the longer path,
as needed the
*rpp
is
free'ed
and a new
malloc'ed
structure is
''returned''
at
*rpp.


The
pxirp_pathextend
and
pxirp_pathextend1
should not be used on arbitrary
pximregions
of type
PXIMREGPATH,
but only upon
pximregions
created by
pxirp_pathcreate
as extended by
pxirp_pathextend
or
pxirp_pathextend1.


The
pxirp_pathcreate,
pxirp_pathextend,
and
pxirp_pathextend1
utilize the
pximregion.region.path.txy
member for internal purposes.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.
For
pxirp_pathextend
or
pxirp_pathextend1
the
*rpp
still has the previous
malloc'ed
structure.
Thus, a
free
of
*rpp
is always safe.








Example



struct  pximregion  *rp;
struct  pxy xy;
int     r, r1;


xy.x = 5;
xy.y = 5;
rp = NULL;
r = pxirp_pathcreate(&rp, &xy);
xy.x = 80;
r1 = pxirp_pathextend(&rp, &xy);
r = min(r, r1);
xy.x = 50;
xy.y = 10;
r1 = pxirp_pathextend(&rp, &xy);
r = min(r, r1);
xy.x = 30;
xy.y = 25;
r1 = pxirp_pathextend(&rp, &xy);
r = min(r, r1);
xy.x = 5;
xy.y = 5;
r1 = pxirp_pathextend(&rp, &xy);
r = min(r, r1);
if (r < 0) {
    printf("Error\n");
    free(rp);
} else {
    #if 1       // w. XCLIB
      rp->image = *pxd_defineImage(1,1,0,0,-1,-1,"Default"),
    #else       // w. SVOBJ,4MOBJ,XCOBJ
      rp->image = *pxd_defimage(1, 0, 0, -1, -1);
    #endif
     ...
}










See Also


See
pxirp_regionfree
to free the region created by
pxirp_pathcreate.








Compress Region Path   ---   pxirp_pathcompress







Summary



int pxirp_pathcompress(rp, rpp);
struct  pximregion  *rp;            // original region path
struct  pximregion  **rpp;          // *NULL, becomes *result, malloc'ed!










Description


The
PXIMREGPATH
type
pximregion
referenced by
rp
is compressed, to the extent possible.
The
*rpp
must initially be NULL;
the compressed version of the
pximregion
is
''returned''
at
*rpp.
The
pximregion
referenced by
rp
is not modified.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.










Export Region to File   ---   pxirp_regionexport







Import Region from File   ---   pxirp_regionimport







Summary



int pxirp_regionexport(abortp, rp, pathname, filemode);
int pxirp_regionimport(abortp, np, pathname, filemode);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct  pximregion  *rp;            // Region
struct  pximregion  **npp;          // *NULL, becomes *result, malloc'ed!!
const char          *pathname;      // File path name
char                *filemode;      // Reserved, must be NULL










Description


The morphology of a
pximregion
is exported, for
pxirp_regionexport,
or imported, for
pxirp_regionimport,
to/from file
pathname.
Only the characteristics defined by the
pximregion
structure itself are exported or imported, such as the region type
(e.g. rectangle, ellipse, polygon, etc.),
region position (e.g. origin),
and region shape (e.g. width, height, angle, vertices, etc.).
Image characteristics and content, as described and referenced by the
pximage
component of a
pximregion
are neither exported nor imported.


For
pxirp_regionexport,
the region to be exported is specified by
rp.


For
pxirp_regionimport,
the
*npp
must initially be NULL;
the imported
pximregion
is placed in
malloc'ed
memory and
''returned''
at
*npp;
the
(*npp)->image
is initialized to a
NULL image with dimensions of 0.
The imported region should be
free'ed
with
pxirp_regionfree.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.




File Format.
The file format is readable ASCII text, listing each
pximregion
field of interest on an individual line.
For example:



[pximregion]
regiontype=PXIMREGRECTANGLE
origin.x=10
origin.y=10
region.rectangle.width=20
region.rectangle.height=20
region.rectangle.angle=0.000000










Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERFILEFORM

Invalid file format.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



20.  Nonrectangular Regions - Draw & Paint









Draw Region Boundary   ---   pxirp8_drawboundary







Summary



int pxirp8_drawboundary(abortp, rp, rsvd, dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximregion  *rp;            // image, region, ...
int                 rsvd;           // reserved. should be 0
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The boundary of the image region referenced by
rp
is drawn.
Regions of types
PXIMREGSCANLIST(B)
and types using the
PXIMREGNEGATIVE
adjective are not supported by this operation.


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the region boundary are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the region boundary.
If
mode='x',
the
value[]
is XORed with the pixels along the region boundary.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of
pixels along the region boundary are exchanged with the sequence of values in
bufip;
a second invocation of the operation
with identical parameters
restores the original pixel values.
If
mode='R',
the pixels along the region boundary are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0).


If
dotspace<=1,
then the drawn boundary is solid; every pixel
along the region boundary is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read.
Using
dotspace>1
increases the effective drawing speed
and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn arrow is 1 pixel thick.
Otherwise, the drawn arrow is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
mode='s'
or
mode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
mode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.










Paint within Region   ---   pxirp8_paintregion







Summary



int pxirp8_paintregion(abortp, rp, pattern, patparm, groundtype, background, foreground, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *rp;            // image, region, ...
int                 pattern;        // 'f': percentage fill, 'h': horizontal,
                                    // 'v': vertical,  'b': box, both h & v
                                    // 'l': diagonal, l-r, 'r': diagonal, r-l
                                    // 'c': cross-hatch, both l & r
                                    // 's': solid
int                 patparm[];      // dependent upon pattern
int                 groundtype;     // 0: fill background, -1 for no-fill
uint                background[];   // background grey level(s)
uint                foreground[];   // foreground grey level(s)
int                 mode;           // reserved. should be 0










Description


The image region referenced by
rp
is
''painted'',
i.e. filled with a two-tone pattern
where both the pattern and the two colors or two grey levels can be selected.
Regardless of the pattern and colors selected,
only pixels within the image region referenced by
rp
are potentially modified.


The
foreground[]
and
background[]
provide the pixel values to be used as the foreground
and, optionally, background;
each dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
foreground[0]
specifies the foreground grey level,
and
background[0]
specifies the (optionally used)
background grey level.
Each of the
foreground
and
background
values may range from 0 to the maximum pixel component value
(255 for 8 bit pixels).


For images composed of float or double pixels,
forevalue[]
and
backvalue[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.


If
groundtype=0,
painted
foreground
value(s) are drawn
against painted
background
value(s).
If
groundtype=-1,
then no background is painted;
any pixel covered by the background is left unmodified.


If
pattern='f',
a percentage fill pattern of foreground vs. background is painted,
where
patparm[2]
is the percentage.
For example,
patparm[2]=75
would yield a pattern which is 75% foreground and 25% background.
A
pattern='s',
is equivalent to
pattern='f',
and
patparm[2]=100.


If
pattern='h',
a horizontal bar pattern is painted.
Each horizontal bar is 1 pixel wide, repeated at vertical period of
patparm[1].
For example,
patparm[1]=3
would yield one line foreground, two lines background, repeated.


If
pattern='v',
a vertical bar pattern is painted.
Each vertical bar is 1 pixel wide, repeated at horizontal period of
patparm[0].
For example,
patparm[0]=2
would yield one line foreground, one line background, repeated.


If
pattern='b',
a box pattern composed of both vertical and horizontal bars,
each bar 1 pixel wide, is painted.
The
patparm[1]
specifies the vertical period, the
patparm[0]
specifies the horizontal period,
each interpreted as described for patterns 'h' and 'v'.


If
pattern='l',
a left (top) to right (bottom) diagonal line pattern at
45°
is painted.
Each diagonal bar is 1 pixel wide, repeated with period of
patparm[1].


If
pattern='r',
a right (top) to left (bottom) diagonal line pattern at
45°
is painted.
Each diagonal bar is 1 pixel wide, repeated with period of
patparm[0].


If
pattern='c',
a cross-hatch pattern which is a combination of patterns 'l' and 'r' is painted,
using a period of
patparm[1]
for the 'l' component and
patparm[0]
for the 'r' component.
In combining the 'l' and 'r' patterns,
a pixel is in the foreground of the 'c' pattern
if it is in either (or both) the foregrounds of the 'l' and 'r' patterns.


For a chosen value of
pattern
and
patparm,
the synchronization (i.e. phase) of the patterns painted is independent
of the image region type or size.
For example, with fixed
pattern
and
patparm,
painting an elliptical region followed by painting an
overlapping polygonal region produce
patterns that are synchronized and thus seamless.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



≥0

Number of pixels modified in region.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.










Draw Region Path   ---   pxirp8_drawpath







Summary



int pxirp8_drawpath(abortp, rp, skipN, drawN, fxy, exy, dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // NULL
struct  pximregion  *rp;            // image, region, type PXIMREGPATH
uint                skipN;          // don't draw first skipN pixel steps
uint                drawN;          // then draw only next drawN pixel steps
struct              pxy *fxy;       // returned! 1st pixel drawn, dotspacing ignored
struct              pxy *exy;       // returned! last pixel drawn, dotspacing ignored
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap buffer
                                    // 'R': buffer, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct  pximage     *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The boundary of the type
PXIMREGPATH
image region referenced by
rp
is drawn.
The first
skipN
pixel of the path are not drawn, thereafter only the next
drawN
pixels are drawn.
If
fxy≠NULL,
the coordinates of the first pixel drawn as per
skipN
is
''returned''
at
*fxy.
If
exy≠NULL,
the coordinates of the last pixel drawn as per
skipN
and
drawN
is
''returned''
at
*exy.
If
skipN=0,
drawN=UINT_MAX[31],
fxy=NULL,
and
exy=NULL,
then
pxirp8_drawpath
has the same effect as
pxirp8_drawboundary.


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the path are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the path.
If
mode='x',
the
value[]
is XORed with pixels along the path.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
are counted.


If
mode='b',
the sequence of pixels along the path are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels along the path are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn path is solid; every pixel
along the path is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read.
Using
dotspace>1
increases the effective drawing speed and for
mode='b'
or
mode='R'
decreases the necessary size of the
pixbuf.


If
thickness<=0
or
thickness<=1,
the drawn arrow is 1 pixel thick.
Otherwise, the drawn arrow is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


The
dotspace
neither affects nor is affected by
skipN,
drawN,
fxy,
and
exy.
The
skipN,
drawN,
fxy,
and
exy
are always in terms of pixels along the path,
rather than pixels actually modified or read.
For a given
dotspace,
the same pixels are modified or read as
skipN
is varied,
excepting, of course, those pixels skipped.
Likewise, the same coordinates are
''returned''
at
*fxy
and
*exy
independently of
dotspace.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters,
including a region type other than
PXIMREGPATH.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.





 
 
 



21.  Nonrectangular Regions - Contrast Enhancement & Threshold









Contrast Enhance Region   ---   pxirp8_pixcontrast







Summary



int pxirp8_pixcontrast(abortp, srp, drp, lowbound, highbound);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                lowbound;       // lowest useful grey level
uint                highbound;      // highest useful grey level










Description


The contrast of the image referenced by
srp
is enhanced, and the modified image
put in the image referenced by
drp.


The
pxirp8_pixcontrast
is identical to
pxip8_pixcontrast,
but allows operations upon image regions.
The
pxip8_pixcontrast
should be consulted for additional information
regarding parameters and effect.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Contrast Enhance Region Real Pixels   ---   pxirpf_pixcontrast







Summary



int pxirpf_pixcontrast(abortp, srp, drp, lowbound, highbound);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
double              lowbound;       // lowest useful grey level
double              highbound;      // highest useful grey level










Description


The contrast of the image referenced by
srp
is enhanced, and the modified image
put in the image referenced by
drp.


The
pxirpf_pixcontrast
is identical to
pxipf_pixcontrast,
but allows operations upon image regions.
The
pxipf_pixcontrast
should be consulted for additional information
regarding parameters and effect.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of float pixels.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Contrast Enhance Region By Percentile   ---   pxirp8_pixcontrastperc







Summary



int pxirp8_pixcontrastperc(abortp, srp, drp, lowperc, highperc, lobp, hibp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                lowperc;        // lowest useful percentile
uint                highperc;       // highest useful percentile
uint                *lobp;          // returned !
uint                *hibp;          // returned !










Description


The contrast of the image referenced by
srp
is enhanced, and the modified image
put in the image referenced by
drp.
The
pxirp8_pixcontrastperc
is identical to
pxip8_pixcontrastperc,
but allows operations upon image regions.
The
pxip8_pixcontrastperc
should be consulted for additional information
regarding parameters and effect.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Threshold Pixel Values in Region   ---   pxirp8_pixthreshold







Threshold Pixel Values in Region   ---   pxirp8_pixthreshold2







Summary



int pxirp8_pixthreshold(abortp,srp,drp,lowbound,highbound,newvalue);
int pxirp8_pixthreshold2(abortp,srp,drp,lowbound,highbound,newvalue,altvalue);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                lowbound;       // pixel w. value between
uint                highbound;      // low/highbounds, inclusive,
uint                newvalue;       // set to newvalue
uint                altvalue;       // otherwise to altvalue










Description


The numeric value of each pixel of the source image referenced by
srp
is compared to the
lowbound
and
highbound,
a new pixel value assigned,
and the result placed in the corresponding pixel of the destination image
referenced by
drp.


The
pxirp8_pixthreshold
and
pxirp8_pixthreshold2
are identical to
pxip8_pixthreshold
and
pxip8_pixthreshold2,
respectively,
but allow operations upon image regions.
The
pxip8_pixthreshold
and
pxip8_pixthreshold2
should be consulted for additional information
regarding parameters and effect.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Threshold Pixel Values in Region   ---   pxirp8_pixthreshold3







Summary



int pxip8_pixthreshold3(abortp, srp, drp, lowbound, highbound, invalue, outvalue, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                lowbound[];     // pixel w. value between
uint                highbound[];    // low/highbounds, inclusive,
uint                invalue[];      // set to invalue (if not NULL)
uint                outvalue[];     // otherwise to outvalue (if not NULL)
int                 rsvd;           // reserved. should be 0










Description


The numeric value of each pixel of the source image referenced by
srp
is compared to the
lowbound
and
highbound;
if between
lowbound
and
highbound,
inclusive, the
invalue,
otherwise the
outvalue,
is placed in the corresponding pixel of the destination image
referenced by
drp.


The
pxirp8_pixthreshold3
is identical to
pxip8_pixthreshold3,
but allows operations upon image regions.
The
pxip8_pixthreshold3
should be consulted for additional information
regarding parameters and effect.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or 3 color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or 3 color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



22.  Nonrectangular Regions - Simple Pixel & Copy Operations









Set Pixel Values in Region   ---   pxirp8_pixset







Summary



int pxirp8_pixset(abortp, drp, value);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *drp;           // destination
uint32              value;          // pixel value










Description


The numeric value of each pixel of the destination image referenced by
drp
is set to
value.
For color pixels, each component (i.e.
''pixie'')
of the pixel is set to
value.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Set Color Pixel Values in Region   ---   pxirp8_pixset







Summary



int pxirp8_pixset3(abortp, drp, values);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *drp;           // destination
uint                values[];       // pixel values










Description


The numeric value of the
i'th
component of each pixel of the destination image
referenced by
drp
is set to
values[i].


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










AND Pixels with Mask in Region   ---   pxirp8_pixand







OR Pixels with Mask in Region   ---   pxirp8_pixor







XOR Pixels with Mask in Region   ---   pxirp8_pixxor







Complement Pixel Values in Region   ---   pxirp8_pixneg







Left Shift Pixel Values in Region   ---   pxirp8_pixshl







Right Shift Pixel Values in Region   ---   pxirp8_pixshr







Left Rotate Pixel Values in Region   ---   pxirp8_pixrotl







Right Rotate Pixel Values in Region   ---   pxirp8_pixrotr







Bit Reverse Pixel Values in Region   ---   pxirp8_pixreverse







MSB Extend Pixel Values in Region   ---   pxirp8_pixmsb







Gray Code/Decode Pixel Values in Region   ---   pxirp8_pixgraycode







Set Pixel Components to Minimum in Region   ---   pxirp8_pixiemin







Set Pixel Components to Maximum in Region   ---   pxirp8_pixiemax







Set Pixel Components to Median in Region   ---   pxirp8_pixieave







Copy Pixel Components in Region   ---   pxirp8_pixiecopy







Summary



int pxirp8_pixand(abortp, srp, drp, mask);
int pxirp8_pixor(abortp, srp, drp, mask);
int pxirp8_pixxor(abortp, srp, drp, mask);
int pxirp8_pixneg(abortp, srp, drp);
int pxirp8_pixshl(abortp, sip, dip, cnt);
int pxirp8_pixshr(abortp, sip, dip, cnt);
int pxirp8_pixrotl(abortp, sip, dip, cnt);
int pxirp8_pixrotr(abortp, sip, dip, cnt);
int pxirp8_pixreverse(abortp, sip, dip, rsvd);
int pxirp8_pixmsb(abortp, sip, dip);
int pxirp8_pixgraycode(abortp, sip, dip, mode);
int pxirp8_pixiemin(abortp, sip, dip);
int pxirp8_pixiemax(abortp, sip, dip);
int pxirp8_pixieave(abortp, sip, dip);
int pxirp8_pixiecopy(abortp, sip, dip, pixiesrc, pixiedstmap);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                mask;           // and, or, xor mask
uint                cnt;            // shift/rotate count
uint                pixiesrc;       // index of source pixie
uint                pixiedstmap;    // bit map of destination pixies
int                 rsvd;           // reserved. should be 0
int                 mode;           // see below










Description


The numeric value of each pixel of the source image referenced by
srp
is numerically modified
and placed in the corresponding pixel of the destination
image referenced by
drp.
The
pxirp8_pixand
performs a bit-wise, boolean AND of the pixel value's binary representation  with the numeric
mask.
The
pxirp8_pixor
performs a bit-wise, boolean INCLUSIVE-OR of the pixel value's binary representation  with the numeric
mask.
The
pxirp8_pixxor
performs a bit-wise, boolean EXCLUSIVE-OR of the pixel value's binary representation  with the numeric
mask.
The
pxirp8_pixneg
performs a subtraction of each pixel value from the maximum pixel value
(255 for 8 bit pixels),
effectively forming the
''negative''
of the image.
The
pxirp8_pixshl
performs a left-shift of the pixel value's binary representation by
cnt
bits.
The
pxirp8_pixshr
performs a right-shift of the pixel value's binary representation by
cnt
bits.
The
pxirp8_pixrotl
performs a left-rotate of the pixel value's binary representation by
cnt
bits.
The
pxirp8_pixrotr
performs a right-rotate of the pixel value's binary representation by
cnt
bits.
The
pxirp8_pixreverse
performs a reversal of the bits of the pixel value's binary representation.
The
pxirp8_pixmsb
performs an extension of the most significant bit through
all bit positions of the pixel value's binary representation.


The
pxirp8_pixgraycode
with
mode=0
converts binary pixel values to Gray Code,
a reflected code in which each two successive values differs
by one bit.
The
pxirp8_pixgraycode
with
mode=1
performs the inverse conversion.


For operations above applied to color pixels, each component (i.e.
''pixie'')
of the pixel is independently
modified, as described above.


The
pxirp8_pixiemin
replaces each component of each color pixel
with the minimum value of the pixel's components.
The
pxirp8_pixiemax
operation replaces each component of each color pixel
with the maximum value of the pixel's components.
The
pxirp8_pixieave
operation replaces each component of each color pixel
with the median, or average, value of the pixel's components.
The
pxirp8_pixicopy
operation replaces one or more components of each color pixel
with the value of one of the pixel's components;
the
pixiesrc
specifies the index of the pixel's components to copied,
the
pixiedstmap
bitmap specifies one or more of the pixel's components to replaced.
The
pxirp8_pixiemin,
pxirp8_pixiemax,
pxirp8_pixieave,
and
pxirp8_pixiecopy
have no effect when used on a monochrome image.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
The
pxirp8_pixneg,
pxirp8_pixiemin,
pxirp8_pixiemax,
and
pxirp8_pixieave,
also supports monochrome or color, float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Scale Pixel Values in Region   ---   pxirp8_pixscale







Offset Pixel Values in Region   ---   pxirp8_pixadd







Scale Pixel Values in Region   ---   pxirpf_pixscale







Offset Pixel Values in Region   ---   pxirpf_pixadd







Summary



int pxirp8_pixscale(abortp, srp, drp, numerator, denominator);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uint                numerator;
uint                denominator;


int pxirp8_pixadd(abortp, srp, drp, constant, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
int                 constant;       // value added
int                 mode;           // 2: bounded by max pixel value and 0,
                                    // ?: modulo pixel word size


int pxirpf_pixadd(abortp, srp, drp, constant, mode);
int pxirpf_pixscale(abortp, srp, drp, constant, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
double              constant;       // value
int                 mode;           // reserved. should be 2










Description


The numeric value of each pixel of the source image referenced by
srp
is numerically modified
and placed in the corresponding pixel of the destination
image
referenced by
drp.


The
pxirp8_pixscale
scales each source pixel by multiplication with the factor
numerator/denominator,
with the integer result placed in the corresponding destination pixel.
Results are bounded to the maximum pixel value
(255 for 8 bit pixels).
Use of
numerator=1
and
denominator=1
(among other values)
effectively copies the image without modification.
If
denominator=0,
the destination pixels are set to the maximum pixel value.


The
pxirp8_pixadd
modifies each source pixel by addition with the signed
constant,
with the integer result placed in the corresponding destination pixel.
If
mode=2,
results are bounded to the minimum and maximum pixel value
(0 and 255, respectively, for 8 bit pixels).
Otherwise, the result is truncated by overflow of the pixel word size.


The
pxipf_pixadd
modifies each source pixel by addition with the signed
constant,
with the result placed in the corresponding destination pixel.
The
pxipf_pixscale
modifies each source pixel by multiplication with the signed
constant,
with the result placed in the corresponding destination pixel.
Results are bounded to the minimum and maximum pixel value.


For color pixels, each component (i.e.
''pixie'')
of the pixel is independently
modified, as described above.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

For
pxirp8_pixscale
and
pxirp8_pixadd:
Monochrome and color, of unsigned integer pixels, of 1 to 32 bits.
For
pxirpf_pixadd
and
pxirpf_pixscale:
Monochrome and color, of float or double pixels.


COC40

For
pxirp8_pixscale
and
pxirp8_pixadd:
Monochrome and color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Map Uchar Pixel Values in Region   ---   pxirp8_pixmap







Map uint16 Pixel Values in Region   ---   pxirp8_pixmaps







Map uint32 Pixel Values in Region   ---   pxirp8_pixmapl







Map Pixel Values in Region   ---   pxirp8_pixmaplut







Summary



int pxirp8_pixmap(abortp, srp, drp, ucharmap, nmap);
int pxirp8_pixmaps(abortp, srp, drp, uint16map, nmap);
int pxirp8_pixmapl(abortp, srp, drp, uint32map, nmap);
int pxirp8_pixmaplut(abortp, lutip, srp, drp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination
uchar               *ucharmap;      // lookup table
uint16              *uint16map;     // lookup table
uint32              *uint32map;     // lookup table
size_t              nmap;           // dimension of ..map[]
struct  pximage     *lutip;         // lookup table(s)










Description


The numeric value of each pixel of the source image referenced by
srp
is used as an index into a lookup table,
and the indexed value placed in the corresponding pixel of the destination
image referenced by
drp.


The
pxirp8_pixmap
operates on uchar pixels, using
ucharmap[0]
through
ucharmap[2bitsperpixie-1]
as the lookup table.
The
pxirp8_pixmaps
operates on uint16 pixels, using
uint16map[0]
through
uint16map[2bitsperpixie-1]
as the lookup table.
The
pxirp8_pixmapl
operates on uint32 pixels, using
uint32map[0]
through
uint32map[2bitsperpixie-1]
as the lookup table.
For color pixels, each component (i.e.
''pixie'')
of the pixel is independently
modified, as described above, using the same lookup table.


The
pxirp8_pixmaplut
operates on uchar, uint16, or uint32 pixels,
using the contents of the image referenced by
lutip
as the lookup table.
The
lutip
should be of the same data type and have the same number of pixies as
srp
and
drp,
with a dimension of (2bitsperpixiex1) (e.g.
256x1 for 8 bit pixies).
For color pixels, each pixie of
srp
is mapped through an individual lookup table composed of the corresponding
pixies of
lutip.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.
The image referenced by
lutip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome and color:
for
pxirp8_pixmaplut;
for
pxirp8_pixmap,
of uchar pixels, of 1 to 8 bits;
for
pxirp8_pixmaps,
of uint16 pixels, of 1 to 16 bits;
for
pxirp8_pixmapl,
of uint32 pixels, of 1 to 32 bits
(subject to available memory for the
uint32map
table).


COC40

Monochrome and color:
for
pxirp8_pixmap
and
pxirp8_pixmaplut,
monochrome, of uchar pixels, of 1 to 32 bits.
The
pxirp8_pixmaps
and
pxirp8_pixmapl
are neither needed nor available.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Copy Image Buffer Region   ---   pxirp8_copy







Summary



int pxirp8_copy(abortp, srp, drp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source
struct  pximregion  *drp;           // destination










Description


The content of the image referenced by
srp
is copied without modification to
the image referenced by
drp.


The
srp
and
drp
region must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



23.  Nonrectangular Regions - Histograms & Computations









Compute Histogram on Region   ---   pxirp8_histab







Summary



int pxirp8_histab(abortp, srp, hp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source image
struct  pxip8histab *hp;            // result table










Description


The image region referenced by
srp
is scanned and a histogram of pixel values constructed.
The histogram is returned in the
pxip8histab
structure referenced by
hp.


The
pxirp8_histab
is identical to
pxip8_histab,
but allows operations upon image regions.
The
pxip8_histab
should be consulted for additional information
regarding parameters and effect.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of uchar pixels, of 1 to 8 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 8 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Histogram on Region   ---   pxirp8_histab2







Compute Histogram on Region   ---   pxirp8_histab3







Summary



int pxirp8_histab2(abortp, srp, count, ncount);
int pxirp8_histab3(abortp, srp, count, ncount, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source image
pxim2size_t         *count;         // result count table
size_t              ncount;         // dimension of count[]
int                 mode;           // options










Description


The image region referenced by
srp
is scanned and a histogram of pixel values constructed.
The histogram is returned in the array referenced by
count,
of dimension
ncount.


The
pxirp8_histab2
and
pxirp8_histab3
are identical to
pxip8_histab2
and
pxip8_histab3,
respectively,
but allows operations upon image regions.
The
pxip8_histab2
and
pxip8_histab3
should be consulted for additional information
regarding parameters and effect.


The
srp
image reference
can be a full image or any image region.
The image referenced by
srp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Tabulated Histogram of Differences on Region   ---   pxirp8_histabpair







Summary



int pxirp8_histabpair(abortp, s1p, s2p, count, ncount, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *s1rp;          // source image A
struct  pximregion  *s2rp;          // source image B
pxim2size_t         *count;         // result count table
size_t              ncount;         // size of count[]
int                 mode;           // 'd'    : A-B
                                    // 'd'^'|': abs(A-B)
                                    // 'd'^'2': (A-B)*(A-B)










Description


The images referenced by
s1rp
and
s2rp
are scanned and a histogram of the differences of
corresponding pixel values constructed.
The histogram is returned in the array referenced by
count,
of dimension
ncount.


The
pxirp8_histabpair
is identical to
pxip8_histabpair,
but allows operations upon image regions.
The
pxip8_histabpair
should be consulted for additional information
regarding parameters and effect.


The
s1rp
and
s2rp
image references
can be a full image or any image region,
can reference the same image,
and must be of identical dimensions.
The image referenced by
s1rp
and
s2rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Count Region Pixels by Threshold   ---   pxirp8_pixthresholdcnt







Summary



int pxirp8_pixthresholdcnt(abortp, srp, threshold, mode, countp)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source image
uint32              threshold;      // threshold value
int                 mode;           // reserved. should be 0
pxim2size_t         *countp;        // returned !










Description


The image region referenced by
srp
is scanned and the number of pixels that are greater than
or equal to the
threshold
are
''returned''
at
*countp.
For color pixels, all components (i.e.
''pixies'')
of the pixel are scanned, compared to the threshold, and counted.
The maximum returned count is the number of pixels in the region
times the number of pixies per pixel.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Count Region Real Pixels by Threshold   ---   pxirpf_pixthresholdcnt







Summary



int pxirpf_pixthresholdcnt(abortp, srp, threshold, mode, countp)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // source image
double              threshold;      // threshold value
int                 mode;           // reserved. should be 0
pxim2size_t         *countp;        // returned !










Description


The image region referenced by
srp
is scanned and the number of pixels that are greater than
or equal to the
threshold
are
''returned''
at
*countp.
For color pixels, all components (i.e.
''pixies'')
of the pixel are scanned, compared to the threshold, and counted.
The maximum returned count is the number of pixels in the region
times the number of pixies per pixel.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of float pixels.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Center of Mass of Region   ---   pxirp8_masscenter







Compute Center of Mass of N'th Power of Region   ---   pxirp8_masscenterpow







Summary



int pxirp8_masscenter(abortp, srp, mass, xcenter, ycenter);
int pxirp8_masscenter(abortp, srp, mass, xcenter, ycenter, pow, rsvd);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // image
double              *mass;          // result mass
double              *xcenter;       // result center x
double              *ycenter;       // result center y
double              pow;            // should be 8
int                 rsvd;           // reserved. should be 0










Description


The image region referenced by
srp
is scanned and descriptive statistics returned.
For
pxip8_masscenter,
interpreting each pixel's value as its mass,
or for
pxip8_masscenterpow,
interpreting each pixel's value to the 8'th power as its mass,
the image region's total
mass,
and the x and y center of mass,
xcenter
and
ycenter
respectively, are
''returned''.
The
xcenter
and
ycenter
coordinates are always relative to the image origin.


The
pxirp8_masscenterpow
is useful when finding the location of a single bright spot
in an otherwise dark background, but where the background is not perfectly 0;
the non-linear 8'th power diminishes the effect of the many small background values.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 32 bits.
Monochrome, of float or double pixels.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Moments of Region   ---   pxirp8_moments







Compute Moments of Region w. Interpretation   ---   pxirp8_momentsf







Summary



int pxirp8_moments(srp, rsvd, momp)
struct  pximage     *srp;           // image
int                 rsvd;           // reserved. should be 0
struct pxip8moments *momp;          // result


int pxirp8_momentsf(srp, rsvd, mapzifunc, mapxyhvfunc, mapzirefp, mapxyhvrefp, momp);
struct  pximage     *srp;           // image
int                 rsvd;           // reserved. should be 0
double    (_cfunfcc *mapzifunc)(void *,struct pxyd *,double);
void      (_cfunfcc *mapxyhvfunc)(void *,struct pxyd *,struct pxyd *);
                                    // mappings: z to i, xy to hv
                                    // _cfunfcc is a predefined function modifier
void                *mapzirefp;     // arg for mapzifunc
void                *mapxyhvrefp;   // arg for mapxyhvfunc
struct pxip8moments *momp;          // result










Description


The image region referenced by
srp
is scanned and descriptive statistics returned.
The statistics are returned in the
pxip8moments
structure referenced by
momp.
The
pxirp8_moments
and
pxirp8_momentsf
are respectively identical to
pxip8_moments
and
pxip8_momentsf,
but allow operations upon image regions.
The
pxip8_moments
and
pxip8_momentsf
should be consulted for additional information.
The resulting moments are always relative to the image origin.


The
srp
image reference can be a full image or any image region.
The image referenced by
srp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Center of Mass, Binary Image Region   ---   pxirp8_masscenterbin







Summary



int pxirp8_masscenterbin(abortp, srp, area, xsum, ysum, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // image
ulong               *area;          // result area
ulong               *xsum;          // result sum x coordinates
ulong               *ysum;          // result sum y coordinates
int                 mode;           // 0: ignore 0 pixels










Description


The image region referenced by
srp
is scanned and descriptive statistics returned.
If
mode=0
pixels with value zero are considered background and ignored,
nonzero pixels are considered foreground.
If
mode≠0
all pixels in the region are considered foreground.
All foreground pixels are tabulated as equally weighted,
i.e. regardless of pixel value.
The returned
area
is the number of foreground pixels, the returned
xsum
is the sum of x coordinates of foreground pixels,
and the returned
ysum
is the sum of y coordinates of foreground pixels.
The
xsum
and
ysum
sum of coordinates are always relative to the image origin.
From these values the x and y coordinates of the center of mass
can be computed as
xsum/area
and
ysum/area,
respectively.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Compute Shape Statistics of Image Region   ---   pxirp_regionshapef







Summary



int pxirp_regionshapef(abortp,srp,mapxyhvfunc,maphvxyfunc,mapfuncrefp,shapep);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximregion  *srp;           // image
void      (_cfunfcc *mapxyhvfunc)(void *refp,struct pxyd *xyp,struct pxyd *hvp);
void      (_cfunfcc *maphvxyfunc)(void *refp,struct pxyd *hvp,struct pxyd *xyp);
                                    // mappings: xy to hv, hv to xy
                                    // _cfunfcc is a predefined function modifier
void                *mapfuncrefp;   // arg for mapxyhvfunc and maphvxyfunc
struct  pxirpshape  *shapep;        // result




struct pxirpshape
{
    double      n;              // number of pixels
    double      area;           // area


    struct pxy  majaxis[2];     // coordinates of major axis endpoints
    struct pxy  minaxis[2];     // 2 pixels farthest from major axis,
                                // each side. Line between these is NOT
                                // orthogonal to major axis.
    double      majaxislength;  // length of major axis
    double      majaxisangle;   // angle of major axis
    double      minaxiswidth[2];// distance of minaxis[] from major axis
    double      circumference;  // circumference


    struct pxyd cm_hv;          // center of uniform mass, h, v
    double      cm_minradius;   // minimum radius from center of mass
    double      cm_maxradius;   // maximum radius from center of mass
    double      cm_almoia;      // angle of least moment of inertia axis
    struct pxy  cm_minradxy;    // pixel at min radius from c.o.m.
    struct pxy  cm_maxradxy;    // pixel at max radius from c.o.m.


    struct pxy  haxismin;       // pixel with/at minimum H coordinate
    struct pxy  haxismax;       // pixel with/at maximum H coordinate
    struct pxy  vaxismin;       // pixel with/at minimum V coordinate
    struct pxy  vaxismax;       // pixel with/at maximum V coordinate
    double      haxiswidth;     // width as projected on H axis
    double      vaxisheight;    // height as projected on H axis
};










Description


Descriptive statistics about the shape of the image region referenced by
srp
are computed and returned.
Regions of types
using the
PXIMREGNEGATIVE
adjective are not supported by this operation.


The
pxirp_regionshapef
allows computation of the descriptive statistics
based upon an arbitrary interpretation of pixel location,
but does not access image memory;
all of the statistics are intrinsic to the shape of the image region.


The
mapxyhvfunc
should reference a caller provided function which maps a pixel's X, Y
coordinates into
''H''
and
''V''
axis coordinates.
The
mapxyhvfunc
is invoked with three parameters:
(1) The
mapfuncrefp
as passed to
pxirp_regionshapef,
(2) A pointer to a struct
pxyd
containing the pixel's X, Y coordinates,
and
(3) A pointer to a struct
pxyd
wherein the pixel's H, V coordinates are returned.


The
maphvxyfunc
should reference a caller provided function which maps a pixel's H, V
coordinates into
''X''
and
Y
axis coordinates; i.e. the inverse of
mapxyhvfunc.
The
maphvxyfunc
is invoked with three parameters:
(1) The
mapfuncrefp
as passed to
pxirp_regionshapef,
(2) A pointer to a struct
pxyd
containing the pixel's H, V coordinates,
and
(3) A pointer to a struct
pxyd
wherein the pixel's X, Y coordinates are returned.


The statistics are returned in the
pxirpshape
structure referenced by
shapep.


Except for
shapep->n,
all double values are with respect to H, V coordinates.
Various pixel locations on the image region's boundary are given
in X, Y coordinates for greater convenience;
their corresponding distances and/or angles are still with respect to H, V
coordinates.


The
shapep->n
is the number of pixels in the region.
The
shapep->area
is the region's area, in H, V units.


The
shapep->majaxis[]
are two points on the boundary which define the major axis
(are farther apart than any other pair of points,
with respect to H, V coordinates);
with distance
shapep->majaxislength
and angle
shapep->majaxisangle,
in radians.
The
shapep->minaxis[]
are the two points on the boundary which define the minor axis
(which, together with the major axis points, define
a rectangle enclosing the region);
with distance
shapep->minaxiswidth[],
respectively,
from the major axis.
The
shapep->circumference
is the sum of distances from pixel to pixel around the region's boundary.


Interpreting the region as a plate of uniform mass, the
shapep->cm_hv
gives the H and V coordinates of the center of mass.
The
shapep->cm_minradxy
and
shapep->cm_maxradxy
are the two points on the boundary which define the minimum and maximum radius
(nearest and furthest from the center of mass, with
respect to H, V coordinates);
with distance
shapep->cm_minradii
and
shapep->cm_maxradii,
respectively.
The
shapep->cm_almoia
gives the angle of the line of least moment of inertia, in radians.


The
shapep->haxismin,
shapep->haxismax,
shapep->vaxismin,
and
shapep->vaxismax
are four points on the boundary with minimum H coordinate,
maximum H coordinate, minimum V coordinate,
and maximum V coordinate, respectively.
The width and height of the region as projected on the
H and V axis are given in
shapep->haxiswidth
and
shapep->vaxisheight,
respectively.


The
rp
can be a full image or any image region.
The image referenced by
rp
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






See Also


See
pxip_calibxyhv
and
pxip_calibzi.






Supports



80x86

Any pixel type and precision.
A math coprocessor is recommended.


COC40

Any pixel type and precision.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








Example


If mapping between X, Y and H, V
coordinates is not required, an identity mapping function
should be created:



void _cfunfcc
mapxyhvnull(void *refp, struct pxyd *xyp, struct pxyd *hvp)
{
    hvp->xd = xyp->xd;
    hvp->yd = xyp->yd;
}




and
pxirp_regionshapef
invoked as:



    ...
    pxirp_regionshapef(...,...,mapxyhvnull,mapxyhvnull,NULL,...);







 
 
 



24.  Nonrectangular Regions - Find Blobs









Find Blobs and List   ---   pxip8_bloblist







Summary



int pxip8_bloblist(abortp, sip, findxyp, findcond, findvalue, mode,
                   bounds, clearvalue, proto, nblobs, results, nbadblobs);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image searched
struct pxy          *findxyp;       // starting coordinate, modified!
int                 findcond;       // search condition
uint                findvalue;      // search condition's value
int                 mode;           // various options
struct pxywindow    *bounds;        // size limits, or NULL
uint                clearvalue;     // pixel value for clear
struct pxip8blob    *proto;         // reserved. must be NULL
size_t              nblobs;         // maximum # of blobs to report
struct pxip8blob    results[];      // report of each blob
pxim2size_t         *nbadblobs;     // number of out-of-bounds found, returned




struct  pxip8blob
{
    struct  pxy seed;           // start coordinate of search
    struct  pxywindow wind;     // bounding rectangle, se exclusive
    ulong   xyarea;             // number of pixels
    struct  pxyd ucom;          // uniform center of mass
};










Description


The image referenced by
sip
is searched for
''blobs'',
and the first
nblobs
found are listed in the
results[].


The search for blobs, or regions, starts at
findxyp->x+1
and
findxyp->y,
looking for valid pixels — those for which
a comparison between the pixel value and
findvalue
is true.
The
findcond
defines the comparison performed:







findcond 


 comparison








'g'^'e'  


 pixel >= findvalue






'l'^'t'  


 pixel <  findvalue






'g'^'t'  


 pixel >  findvalue






'l'^'e'  


 pixel <= findvalue






'e'^'q'  


 pixel == findvalue






'n'^'e'  


 pixel != findvalue









For each valid pixel, all of the connected, 4-way adjacent
pixels that are similarly valid are collected to form a region.


If
mode&PXIP8BLOB_CONVEX,
all blobs are assumed to be convex.
If
mode&PXIP8BLOB_NOHOLE,
all blobs are assumed to not contain any holes.
If
mode
is OR'ed with PXIP8BLOB_CONVEX or PXIP8BLOB_NOHOLE,
and the assumptions are not true, a blob may be found as
two or more pieces, or containing pixels that are not part of the blob.


The size and position of the region is checked against
bounds
and the PXIP8BLOB_IGNOREEDGE option of
mode.
If
bounds≠NULL;
if the region's width is less than
bounds->nw.x,
or the region's height is less than
bounds->nw.y,
or the region's width is greater than
bounds->se.x,
or the region's height is greater than
bounds->se.y,
information about the region is not recorded in
results[].
Further, if
mode&PXIP8BLOB_IGNOREEDGE
and the region touches any edge of the image,
information about the region is not recorded in
results[].


If the size and position of the resulting region are acceptable,
information about the region is recorded in the next
(i.e. starting at [0] and incrementing)
element of
results[];
an array of
pxip8blob
structures.
The
results[].seed
are the x, y coordinates
of the first pixel found, of this region.
The
results[].wind
are the coordinates of the
smallest bounding rectangle around the region;
as customary the
results[].wind.nw
are inclusive coordinates,
and the
results[].wind.se
are exclusive coordinates.
The
results[].xyarea
is the number of pixels in the region.
The
results[].ucom
is the center of mass of the region, treating each
pixel of the region as a uniform mass.


After finding the region, and
optionally recording it in
results[],
unless
mode&PXIP8BLOB_NOCLEAR,
the pixels in the region are set to value
clearvalue,
allowing a search to continue for pixels of other regions.[33]


The search for, and recording of, regions
continues until the entire image has been searched,
or until
nblobs
have been found and recorded.
The
*findxyp
is modified to record the last search location, allowing
pxip8_bloblist
to be called repeatedly until all blobs have been reported.


If
nbadblobs≠0,
the number of blobs found which were not recorded due to the
bounds
or the
mode&PXIP8BLOB_IGNOREEDGE
is returned.


The
sip
must be a full image.
If
mode&PXIP8BLOB_NOCLEAR,
the image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



≥0

Operation complete; the number of blobs found
and recorded in
results[]
is returned.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








Example


An image buffer is searched for blobs, a blob being defined
as pixel with value greater than 128.
A reasonably large size of
results[]
aids efficiency, but does not limit the number of blobs found
in an image;
pxip8_bloblist
is called repeatedly until all blobs are reported.



#define NBLOBS      50
struct  pxy         search;
struct  pxip8blob   results[NBLOBS];
struct  pxywindow   bounds;
ulong               ngood;
ulong               nbad
pxim2size_t         bad;
int                 r, i;


search.x = -1;                          // init search coordinates
search.y = 0;
bounds.nw.x = 3;                        // min width
bounds.nw.y = 3;                        // min height
bounds.se.x = 100;                      // max width
bounds.se.y = 100;                      // max height
nbad = ngood = 0;                       // init blob count
for (;;) {
    r = pxip8_bloblist(NULL,
                       #if 1        // w. XCLIB
                         pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                       #else        // w. SVOBJ,4MOBJ,XCOBJ
                         pxd_defimage(1,0,0,-1,-1),
                       #endif
                       &search,
                       'g'^'t',
                       128,
                       0,               // use default modes
                       &bounds,
                       0,               // clear to value which isn't blob
                       NULL,
                       NBLOBS,
                       results,
                       &bad);
    if (r < 0) {
        printf("Error %s\n", pxerrnomesg(r));
        break;
    }
    nbad += bad;                        // sum bad blobs
    ngood += r;                         // sum good blobs
    if (!r)
        break;                          // no more blobs
    for (i = 0; i < r; i++)
        printf("Blob at (%f,%f), area=%ld\n", results[i].ucom.xd,results[i].ucom.yd,results[i].xyarea);
}
printf("Total blobs: Good=%ld, Bad=%ld\n", ngood, nbad);












Find Blobs, Analyze and List   ---   pxip8_bloblist2







Summary



int pxip8_bloblist2(abortp, sip, gip, findxyp, findcond, findvalue, mode,
                    bounds, clearvalue, mapzifunc, mapxyhvfunc, maphvxyfunc,
                    mapzirefp, mapxyhvrefp, proto, nblobs, results, nbadblobs);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image searched
struct pximage      *gip;           // image analyzed
struct pxy          *findxyp;       // starting coordinate, modified!
int                 findcond;       // search condition
uint                findvalue;      // search condition's value
int                 mode;           // various options
struct pxywindow    *bounds;        // size limits, or NULL
uint                clearvalue;     // pixel value for clear
double    (_cfunfcc *mapzifunc)(void*,struct pxyd*,double);         // see pxirp8_momentsf
void      (_cfunfcc *mapxyhvfunc)(void*,struct pxyd*,struct pxyd*); // and/or pxip8_histstat2f
void      (_cfunfcc *maphvxyfunc)(void*,struct pxyd*,struct pxyd*); // and/or pxirp_regionshapef
void                *mapzirefp;                                     // ditto
void                *mapxyhvrefp;                                   // ditto
struct pxip8blob2   *proto;         // reserved. must be NULL
size_t              nblobs;         // maximum # of blobs to report
struct pxip8blob2   results[];      // report of each blob
pxim2size_t         *nbadblobs;     // number of out-of-bounds found, returned




struct  pxip8blob2
{
    struct pxy seed;                // start coordinate of search
    struct pxywindow     wind;      // bounding rectangle
    struct pxip8moments  moments;   // as per pxirp8_momentsf
    struct pxip8histstat histstat;  // as per pxip8_histstat2f
    struct pxirpshape    shapestat; // as per pxirp_regionshapef
};










Description


The image referenced by
sip
is searched for
''blobs'',
and the first
nblobs
found are listed in the
results[].


The operation of
pxip8_bloblist2
is similar to
pxip8_bloblist,
but
pxip8_bloblist2
performs additional analysis upon each blob,
and is correspondingly slower.


As for
pxip8_bloblist,
the
sip
is searched for pixels/regions/blobs
which meet the
findcond
and
findvalue
condition.
The image referenced by
sip
might be a binarized
''map''
of blob locations;
after finding a region in
sip
the corresponding region of
gip
is the region actually analyzed.


If the size and position of the resulting region are acceptable,
information about the region is recorded in the next
(i.e. starting at [0] and incrementing)
element of
results[];
an array of
pxip8blob2
structures.
The
results[].seed
are the x, y coordinates
of the first pixel found, of this region.
The
results[].wind
are the coordinates of the
smallest bounding rectangle around the region;
as customary the
results[].wind.nw
are inclusive coordinates,
and the
results[].wind.se
are exclusive coordinates.


The
results[].moments
is the result of applying
pxirp8_momentsf
to the region in
gip.
The
results[].histstat
is the result of applying
pxip8_histstat2f
to the region in
gip.
The
results[].shapestat
is the result of applying
pxirp_regionshapef
to the region.
The five
map*
parameters are passed to
pxirp8_momentsf,
pxip8_histstat2f,
or
pxirp_regionshapef
to support interpretation under intensity and dimensional mappings.


After finding the region, and
optionally recording it in
results[],
if
clear≠0
then the pixels in the region of
sip
are set to value
clearvalue,
allowing a search to continue for pixels of other regions.


The
sip
and
gip
must be a full image of the same dimensions and pixel type.
If
clear=0,
the image referenced by
sip
is not modified.
The image referenced by
gip
is not modified, except by overlap with
sip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



≥0

Operation complete; the number of blobs found
and recorded in
results[]
is returned.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








Example


The statistics reported are
based upon an arbitrary interpretation of pixel value and pixel location;
a logarithmic density mapping
and simple dimensional scaling functions are defined.



double _cfunfcc densitymap(void *p, struct pxyd *xyp, double i)
{
    return(log(i+.01));             // density is log of pixel value
}
void _cfunfcc xyhvmap(void *p, struct pxyd *xyp, struct pxyd *hvp)
{
    hvp->xd = 10 + xyp->xd/2;       // hv coordinates are
    hvp->yd = 10 + xyp->yd/2;       // 10 + xy_coordinates/2
}
void _cfunfcc hvxymap(void *p, struct pxyd *hvp, struct pxyd *xyp)
{
    xyp->xd = 2 * (hvp->xd-10);     // the inverse of xyhvmap
    xyp->yd = 2 * (hvp->yd-10);
}




An image buffer is searched for blobs, a blob being defined
as a group of pixels with value greater than 128 followed by
one or more morphological operations to
''clean''
the boundaries.



int     i;
pxip8_pixthreshold2(NULL,
          #if 1        // w. XCLIB
            pxd_defineImage(1,1,0,0,-1,-1,"Grey"),  // original image
            pxd_defineImage(1,2,0,0,-1,-1,"Grey"),  // thresholded copy
          #else        // w. SVOBJ,4MOBJ,XCOBJ
            pxd_defimage(1,0,0,-1,-1),              // original image
            pxd_defimage(2,0,0,-1,-1),              // thresholded copy
          #endif
            128, 255, 128, 0);
for (i = 0; i < 3; i++) {
    pxip8_morperode3x3(NULL,
            #if 1        // w. XCLIB
              pxd_defineImage(1,2,0,0,-1,-1,"Grey"),    // clean blob
              pxd_defineImage(1,2,0,0,-1,-1,"Grey"),    // fragments
            #else        // w. SVOBJ,4MOBJ,XCOBJ
              pxd_defimage(2,0,0,-1,-1),
              pxd_defimage(2,0,0,-1,-1),
            #endif
            0);
}




A reasonably large size of
results[]
aids efficiency, but does not limit the number of blobs found
in an image;
pxip8_bloblist2
is called repeatedly until all blobs are reported.



#define NBLOBS      10
struct  pxy         search;
struct  pxip8blob2  results[NBLOBS];
struct  pxywindow   bounds;
ulong               ngood = 0;
ulong               nbad = 0;
pxim2size_t         bad = 0;
int                 r;


search.x = -1;                          // init search coordinates
search.y = 0;
bounds.nw.x = 3;                        // min width
bounds.nw.y = 3;                        // min height
bounds.se.x = 100;                      // max width
bounds.se.y = 100;                      // max height


for (;;) {
    r = pxip8_bloblist2(NULL,
            #if 1        // w. XCLIB
              pxd_defineImage(1,2,0,0,-1,-1,"Grey"),    // searched image
              pxd_defineImage(1,1,0,0,-1,-1,"Grey"),    // analyzed image
            #else        // w. SVOBJ,4MOBJ,XCOBJ
              pxd_defimage(2,0,0,-1,-1),                // searched image
              pxd_defimage(1,0,0,-1,-1),                // analyzed image
            #endif
            &search,
            'g'^'e',
            128,
            0,              // use default modes
            &bounds,
            0,              // clear to value which isn't blob
            densitymap,     // map grey levels
            xyhvmap,        // map coordinates
            hvxymap,        // map coordinates
            NULL,
            NULL,
            NULL,
            NBLOBS,
            results,
            &bad);
    if (r < 0) {
        printf("Error %s\n", pxerrnomesg(r));
        break;
    }
    nbad += bad;                        // sum bad blobs
    ngood += r;                         // sum good blobs
    if (!r)
        break;                          // no more blobs
    for (i = 0; i < r; i++)
        printf("Blob at (%f,%f), area=%f\n", results[i].moments.cmass_x,
                                              results[i].moments.cmass_y,
                                              results[i].moments.n);
}
printf("Total blobs: Good=%ld, Bad=%ld\n", ngood, nbad);












Find Blobs and List   ---   pxip8_bloblist3







Summary



int pxip8_bloblist3(abortp, sip, findxyp, findcond, findvalue, mode,
                   bounds, clearvalue, proto, nblobs, results, nbadblobs);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *sip;           // image searched
struct pxy          *findxyp;       // starting coordinate, modified!
int                 findcond;       // search condition
uint                findvalue;      // search condition's value
int                 mode;           // various options
struct pxywindow    *bounds;        // size limits, or NULL
uint                clearvalue;     // pixel value for clear
struct pxip8blob3   *proto;         // reserved. must be NULL
size_t              nblobs;         // maximum # of blobs to report
struct pxip8blob3   results[];      // report of each blob
pxim2size_t         *nbadblobs;     // number of out-of-bounds found, returned




struct  pxip8blob3
{
    struct  pxyd seed;          // start coordinate of search
    struct  pxydwindow wind;    // bounding rectangle, se exclusive
    double  xyarea;             // number of pixels
    struct  pxyd ucom;          // uniform center of mass
};










Description


The
pxip8_bloblist3
is the same as
pxip8_bloblist
except that an array of
pxip8blob3
structures
are used
instead of
pxip8blob
structures.
The
pxip8blob3
structure has the same fields and subfields,
but is composed entirely of
double's
and can be construed as an array of double's;
thereby facilitating use of non-C languages.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns
As described for
pxip8_bloblist.



 
 
 



25.  Characters, Lines, Icons, Patterns & Graphics









Draw Arrow   ---   pxip8_drawarrow







Summary



int pxip8_drawarrow(abortp, ip, xyp, length, angle, aspect, hform, hlength,
                    hangle, tform, tlength, tangle, dotspace, thickness,
                    mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // arrow head point coordinate
double              length;         // shaft length
double              angle;          // shaft angle. 0 is arrow to the right
double              aspect;         // video aspect ratio: X/Y
int                 hform;          // arrow head: 'v' or 0
double              hlength;        // arrow head length
double              hangle;         // arrow head angle relative to shaft
int                 tform;          // arrow tail: 'v' or 0
double              tlength;        // arrow tail length
double              tangle;         // arrow tail angle relative to shaft
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct  pximage     *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


An arrow, consisting of a shaft, an optional arrow head,
and an optional arrow tail, is drawn in the image referenced by
ip.
The shaft, of length
length,
is drawn with its head end at the coordinate defined by
xyp,
at angle of
angle
radians.
An
angle=0
is an arrow to the right;
with increasing
angle
corresponding to clockwise rotation.


If
hform='v',
an arrow head is drawn
consisting of two line segments which meet at the head end of the shaft
(i.e. nominally in the shape of a
''V''),
each line segment of length
hlength,
at an angle of
hangle
radians relative to the shaft.
If
tform='v',
an arrow head is drawn consisting of two line segments which meet
at the tail end of the shaft
(i.e. nominally in the shape of a
''V''),
each line segment of length
tlength,
at an angle of
tangle
radians relative to the shaft.
A small
hangle
or
tangle,
less than
pi/4,
forms a
''sharp''
arrow head at the respective shaft end; line segments close to the shaft.
An
hangle
or
tangle
of
3pi/4,
for example, forms an
''inverted''
arrow head with line segments extending past the respective shaft end.


The
length,
hlength,
and
tlength
are in units of horizontal pixels.
Using
aspect,
the current video aspect ratio (X/Y), nonhorizontal line segments are scaled
so that a rotated arrow (varying
angle)
does not appear to change dimension or shape.


The
xyp
coordinate is defined by reference to a
pxy
structure,
and is relative to the image's coordinates,
not its area of interest.
Any portion of the arrow out of the
ip
area of interest is not drawn
(i.e.
''clipped'').


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels composing the arrow are set to
value[].
If
mode='+',
the
value[]
is added to pixels composing the arrow.
If
mode='x',
the
value[]
is XORed with pixels composing the arrow.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of pixels composing the arrow are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels composing the arrow are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn line segments are solid; every pixel
composing the arrow is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read,
along with the end point pixels.
Using
dotspace>1
increases the effective drawing speed and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn arrow is 1 pixel thick.
Otherwise, the drawn arrow is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn, or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








See Also


See
pxvid_xformat
or
pxd_imageAspectRatio
to obtain the video aspect ratio.








Draw Curved Line defined as Bezier Polynomial   ---   pxip8_drawbezier







Summary



int pxip8_drawbezier(abortp, ip, m, xyp, dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximage     *ip;            // image
int                 m;              // number of guide points: 2 <= m <= 10
struct  pxy         xyp[];          // array of guide points, dimension m
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct  pximage     *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The
pxip8_drawbezier
draws a curved line segment in the image referenced by
ip.
The curved line is defined by the
m'th
order, for
2<=m<=10,
Bezier polynomial as specified by the
m
coordinates,
xyp[0],...,xyp[m-1].
As usual, the
xyp[0]
and
xyp[m-1]
are end points with the other coordinates serving as guide points.


The
xyp
coordinates
are relative to the image's coordinates,
not its area of interest.
Any portion of the curve out of the
ip
area of interest is not drawn
(i.e.
''clipped'').


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the curve are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the curve.
If
mode='x',
the
value[]
is XORed with pixels along the curve.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of pixels along the curve are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels along the curve are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn curve is solid; every pixel
along the curve is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read,
along with the end point pixels.
Using
dotspace>1
increases the effective drawing speed and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn curve is 1 pixel thick.
Otherwise, the drawn curve is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.


The execution time of this operation increases significantly
for larger polynomial orders, i.e.
m.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








See Also


The theory and practice of Bezier polynomials
is discussed in most texts on graphics.
For example,
ALGORITHMS FOR GRAPHICS AND IMAGE PROCESSING,
Theo Pavlidis,
Computer Science Press, 1982.








Draw Box   ---   pxip8_drawbox







Summary



int pxip8_drawbox(abortp, ip, windp, dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct pximage      *ip;            // image
struct pxywindow    *windp;         // box coordinates, inclusive !
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The
pxip8_drawbox
draws a rectangular box in the image referenced by
ip,
with northwest corner coordinate
windp->nw
and southeast corner coordinate
windp->se,
both inclusive.
The corners are defined by references to a pair of
pxy
structures in a
pxywindow
structure,
and are relative to the image's coordinates,
not its area of interest.
The corner coordinates must be
''normalized'';
i.e. the
windp->nw.x<=windp->se.x
and
windp->nw.y<=windp->se.y.
Any portion of the box out of the
ip
area of interest is not drawn
(i.e.
''clipped'').


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the line segment(s) are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the line segment(s).
If
pixmode='x',
the
value[]
is XORed with the pixels along the line segment(s).
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of pixels along the line segment(s) are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels along the line segment(s) are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn line segment(s) are solid; every pixel
along the line segment(s) is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read, along with the end point pixels.
Using
dotspace>1
increases the effective drawing speed and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn lines are 1 pixel thick.
Otherwise, the drawn lines are
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.










Draw Characters   ---   pxip8_drawchars







Summary



int pxip8_drawchars(abortp, ip, xyp, cp, cn, width, height, hlead, vlead,
                    groundtype, background, foreground, antialias);
pxabortfunc_t       **abortp;       // NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // position
char                cp[];           // chars to output
size_t              cn;             // number of chars to output
int                 width;          // character width
int                 height;         // character height
int                 hlead;          // horiz lead, each side
int                 vlead;          // vert lead, top & bottom
int                 groundtype;     // 0: fill background
                                    // -1: no fill, pixels set to foreground
                                    // -2: add foreground level to pixels
uint                background[];   // background pixel value(s)
uint                foreground[];   // foreground pixel value(s)
int                 antialias;      // !0: background fill interpolated










Description


A line of characters is drawn in the image referenced by
ip,
the character
height
and
width
can be chosen to compensate for differences
in aspect ratio and video resolution.
Characters can be drawn with or without background fill.


The
foreground[]
and
background[]
provide the pixel values to be used as the foreground
and, optionally, background;
each dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
foreground[0]
specifies the foreground grey level,
and
background[0]
specifies the (optionally used)
background grey level.
Each of the
foreground
and
background
values may range from 0 to the maximum pixel component value
(255 for 8 bit pixels).


If
groundtype=0,
characters are drawn with the
foreground
value(s)
against the filled
background
value(s).
If
groundtype=-1,
characters are drawn by setting pixels to the
foreground
value(s) without background fill.
If
groundtype=-2,
characters are drawn by adding
foreground
to pixels, without modification to the background.
Each character is drawn
width
pixels wide by
height
pixels high,
with an additional
hlead
pixels of background
''leading''
on the left and right,
and an additional
vlead
pixels of background
''leading''
on the bottom and top.
In no fill mode, the
hlead'ing
is unfilled background,
i.e. spacing,
and the
vlead
is ignored.
Thus, each character is drawn within a rectangle of
width+2*hlead
by
height+2*vlead.
The coordinate of the upper left corner of the first character
is defined by
xyp,
a reference to a
pxy
structure,
with following characters at
xyp->x
plus increments of
width+2*hlead.


Up to
cn
characters are drawn,
with character codes taken from
cp[0],
cp[1],
etc.
Note that
cp
is
not
interpreted as a NULL terminated string.


Less than
cn
characters will be drawn if there is insufficient space
in the defined image, or area of interest.
No characters are written if
xyp->y
is closer than
height+2*vlead
to the bottom of the image, or area of interest.
Otherwise, up to
cn
characters are drawn,
as will fit between
xyp->x
and the right edge of the image,
or area of interest.
If less than
cn
characters fit, the
remaining right edge margin
is, in fill mode, filled with the
background
value(s).
In all cases, the number of characters
drawn are returned.


As the characters are copied from the current PC's BIOS ROM,
character sizes with
height
and
width
both multiples of 8
are, computationally, most efficient
and implemented by pixel replication.
Other character sizes must be computed by interpolation
from the basic 8x8 size.
In fill mode, if
antialias≠0,
then interpolated intermediate grey levels between
foreground
and
background
are used to reduce aliasing.
There are no explicit limitations on the character sizes,
although extreme rescaling will produce blocky characters.


The
pxip8_drawchars
is deprecated and not suggested for use in new applications;
use
pxip8_drawchars3.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.
The character set is the
ASCII codes defined for the IBM PC and compatibles.
Under DOS, the 256 code extended character set is available.
Under Windows, the 128 code ASCII set is available.
The
antialias
is supported only for uint8, monochrome, pixels.
Not supported under Linux.








Returns



≥0

Number of characters written.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








Example





char    mesg[] = "A long message is to be written in the lower right"
                 " quadrant of the image. The message will not fit"
                 " on one line of the image. This IS the message."
                 " Note that in ANSI ``C'' these four lines are actually"
                 " one continuous ``C'' string (character array).";
int     n, i;
struct  pxy  xy;
char    *p;
uint    background = 0, foreground = 255;
/*
 * Size message & draw.
 * The image pixels are assumed to be monochrome.
 */
xy.x = pxd_xdim()/2;                    // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
xy.y = (pxd_ydim()<<pxd_ylace())/2;     // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
xy.x = pxd_imageXdim()/2;               // starting coordinate  w. XCLIB
xy.y = pxd_imageYdim()/2;               // starting coordinate  w. XCLIB
n = strlen(mesg);                       // in C library
p = (uchar*)mesg;
while (n) {
    i = pxip8_drawchars(NULL,
                #if 1       // w. XCLIB
                  pxd_defineImage(1,1,xy.x,xy.y,-1,-1,"Default"),
                #else       // w. SVOBJ,4MOBJ,XCOBJ
                  pxd_defimage(1,xy.x,xy.y,-1,-1),  // the image to draw in
                #endif
                &xy,                                // where to draw
                p,                                  // characters to draw
                n,                                  // how many to draw
                8,                                  // width
                16,                                 // double height for interlace!
                2,                                  // extra x leading
                4,                                  // extra y leading
                0,                                  // fill background
                &background,                        // black background
                &foreground,                        // white foreground
                0 );                                // no antialiasing


    if (i <= 0) {
        printf("error %d\n", i);
        break;
    }
    p += i;                 // these characters drawn ..
    n -= i;                 // .. on current line
    xy.y += 16+4+4;         // coordinate to start next line
}












Draw Text   ---   pxip8_drawchars3







Draw Text from Font Map   ---   pxip8_drawchars4







Summary



int pxip8_drawchars3(abortp, ip, xyp, angle, cp, cn, width, height, hlead, vlead,
                    mode, forevalue, backvalue, bufip, cntp);
int pxip8_drawchars4(abortp, ip, xyp, angle, charbuf, width, height, baseline,
                     hlead, vlead, mode, forevalue, backvalue, bufip, cntp);
pxabortfunc_t       **abortp;       // NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // start position, baseline & left edge
                                    // future: may be modified!
double              angle;          // angle of baseline
char                cp[];           // chars to output
size_t              cn;             // number of chars to output
int                 width;          // character width
int                 height;         // character height
int                 hlead;          // horizontal lead, each side
int                 vlead;          // vertical lead, top & bottom
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                forevalue[];    // foreground: value(s) for '+', 's', 'x' modes
uint                backvalue[];    // background: value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL
char                *fontmap;       // 'bit' map of character font
int                 baseline;       // position of character font baseline










Description


A line of text is drawn in the image referenced by
ip,
at a selected position and angle, with selected character height and width.
The
pxip8_drawchars3
draws characters and text using a predefined font, scaled to fit the specified size;
the
pxip8_drawchars4
allows drawing characters, text, or graphics, from an arbitrary, user supplied,
prescaled, font.


For
pxip8_drawchars3,
characters to be drawn are taken from
cp[0],
cp[1],
through
cp[cn-1].
Note that
cp
is
not
interpreted as a NULL terminated string.
The character set is the
ASCII codes defined for the IBM PC
and compatibles.
The character size is specified by
height
and
width;
that are the nominal height and width, in pixels, of typical capital letters.
The
hlead
specifies extra horizontal space, in pixels,
to be added to the left of the first character,
and to the
''right''
(e.g. relative to the
angle)
of all characters.
The
vlead
specifies extra vertical space, in pixels,
above and below the characters;
it has effect only if the background is being drawn
(background≠NULL).


For
pxip8_drawchars4,
Characters to be drawn are taken from
fontmap,
which is interpreted as a two-dimensional
''map''
of the characters, of
width
wide and
height
high, left to right and top to bottom;
each
''char''
in the
fontmap
interpreted as 0 for background, or 1 for foreground.
Typically, the
fontmap
represents a single character, but may represent multiple characters.
The
baseline,
0<=baseline<height,
specifies the position of the baseline
of the font referenced by
fontmap.
The
hlead
specifies extra horizontal space, in pixels,
to be added to the left,
and to the
''right''
(e.g. relative to the
angle)
of the drawn text.
The
vlead
specifies extra vertical space, in pixels,
above and below the drawn text;
it has effect only if the background is being drawn
(background≠NULL).


The
xyp,
a reference to a
pxy
structure,
specifies the text's drawn position;
specifically the left edge and baseline[34]
of the first character relative to the image's coordinates,
and not relative to the image's area of interest.
Any characters, or portions of characters, out of the
ip
area of interest are not drawn
(i.e.
''clipped'').
The
Angle
specifies the angle of the baseline, extending from the point
referenced by
xyp.


For
mode='s',
mode='+',
or
mode='x',
the
forevalue[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
forevalue[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels forming the character(s) are set to
forevalue[].
If
mode='+',
the
forevalue[]
is added to pixels forming the character(s).
If
mode='x',
the
forevalue[]
is XORed with the pixels forming the character(s).
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


For images composed of float or double pixels
with
mode='s'
or
mode='+',
forevalue[]
and
backvalue[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
mode='x'
is undefined.


If
mode='b',
the sequence of pixels forming the character(s) are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels forming the character(s) are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
backvalue=NULL,
the background
''behind''
the characters is not modified.
Otherwise,
backvalue
is a pixel value, dimensioned and interpreted
as for
forevalue,
and drawn, with the same
mode
as described above.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.


Future implementation: Upon completion, the
xyp->x
and
xyp->y
are modified; being incremented past the last character drawn,
and in the proper position to draw additional characters on the same line.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



≥0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.










Windows: Draw Text using FONT   ---   pxip8_drawchars5







Summary



int pxip8_drawchars5(abortp, ip, xyp, angle, hFont, cp, cn, width, height,
                     hlead, vlead, mode, forevalue, backvalue, bufip, cntp);
pxabortfunc_t       **abortp;       // NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // start position, baseline & left edge
                                    // future: may be modified!
double              angle;          // angle of baseline
HFONT               hFont;          // Windows font
char                cp[];           // chars to output
size_t              cn;             // number of chars to output
int                 width;          // reserved. must be 0.
int                 height;         // reserved. must be 0.
int                 hlead;          // horizontal lead, each side
int                 vlead;          // vertical lead, top & bottom
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                forevalue[];    // foreground: value(s) for '+', 's', 'x' modes
uint                backvalue[];    // background: value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


A line of text is drawn in the image referenced by
ip,
at a selected position and angle, using the specified Windows
hFont.


Characters to be drawn are taken from
cp[0],
cp[1],
through
cp[cn-1].
Note that
cp
is
not
interpreted as a NULL terminated string.
The
hlead
specifies extra horizontal space, in pixels,
to be added to the left of the first character,
and to the
''right''
(e.g. relative to the
angle)
of all characters.
The
vlead
specifies extra vertical space, in pixels,
above and below the characters;
it has effect only if the background is being drawn
(background≠NULL).


The
xyp,
a reference to a
pxy
structure,
specifies the text's drawn position;
specifically the left edge and baseline[35]
of the first character relative to the image's coordinates,
and not relative to the image's area of interest.
Any characters, or portions of characters, out of the
ip
area of interest are not drawn
(i.e.
''clipped'').
The
Angle
specifies the angle of the baseline, extending from the point
referenced by
xyp.


For
mode='s',
mode='+',
or
mode='x',
the
forevalue[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
forevalue[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels forming the character(s) are set to
forevalue[].
If
mode='+',
the
forevalue[]
is added to pixels forming the character(s).
If
mode='x',
the
forevalue[]
is XORed with the pixels forming the character(s).
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


For images composed of float or double pixels
with
mode='s'
or
mode='+',
forevalue[]
and
backvalue[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
mode='x'
is undefined.


If
mode='b',
the sequence of pixels forming the character(s) are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels forming the character(s) are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
backvalue=NULL,
the background
''behind''
the characters is not modified.
Otherwise,
backvalue
is a pixel value, dimensioned and interpreted
as for
forevalue,
and drawn, with the same
mode
as described above.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.


Future implementation: Upon completion, the
xyp->x
and
xyp->y
are modified; being incremented past the last character drawn,
and in the proper position to draw additional characters on the same line.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



≥0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXEROPSYS

Windows error in using the
hFont.








Example





    HFONT       hFont;
    struct pxy  xy;
    uint        fore[3];


    //
    // Get a font from Windows.
    //
    hFont = CreateFont(18, 0, 0, 0, 400, 0,
                       0, 0, ANSI_CHARSET, OUT_DEFAULT_PRECIS,
                       CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, FIXED_PITCH,
                       NULL);
    if (hFont) {
        //
        // Draw. The fore[] values assumes 8 bit pixels
        // so as to draw white characters.
        //
        xy.x = 0;
        xyy = 100;
        fore[0] = fore[1] = fore[2] = 255;


        pxip8_drawchars5(NULL,
                         #if 1       // w. XCLIB
                           pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                         #else       // w. SVOBJ,4MOBJ,XCOBJ
                           pxd_defimage(1,0,0,-1,-1), // the image to draw in
                         #endif
                         hFont,                       // the font to draw with
                         &xy,                         // draw position
                         0,                           // draw angle
                         "Hello",                     // what to draw
                         5,                           // how many characters to draw
                         0, 0,                        // reserved
                         0, 0,                        // no extra leading
                         's', fore, NULL,             // drawing mode
                         NULL, NULL);                 //
        DeleteObject(hFont);
    }












Draw Ellipse   ---   pxip8_drawellipse







Draw Ellipse Section   ---   pxip8_drawellipsesect







Summary



int pxip8_drawellipse(abortp, ip, xyp, xdiam, ydiam, theta, dotspace,
                      thickness, mode, value, bufip, cntp);
int pxip8_drawellipsesect(abortp, ip, xyp, xdiam, ydiam, theta, starta, enda,
                          dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // center coordinate
int                 xdiam;          // x axis 'diameter'
int                 ydiam;          // y axis 'diameter'
double              theta;          // rotation, radians
double              starta;         // angle at which section starts
double              enda;           // angle at which section ends
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct  pximage     *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The
pxip8_drawellipse
or
pxip8_drawellipsesect
draws an ellipse, or a section of ellipse, with arbitrary width, height, and rotation,
in the image referenced by
ip.
The ellipse is centered at the coordinate specified by
xyp,
with a horizontal diameter of
xdiam,
and a vertical diameter of
ydiam.
The ellipse may be rotated, as specified by
theta
in radians, counterclockwise.
For a rotated ellipse, the
xdiam
and
ydiam
specify the dimensions, along the horizontal and
vertical axis, prior to rotation.


For
pxip8_drawellipsesect
the
starta
and
starta,
in radians,
specifies the angular position at which the section of the ellipse
starts and stops.


The
xyp
coordinate is relative to the image's coordinates,
not its area of interest.
Any portion of the ellipse out of the
ip
area of interest is not drawn
(i.e.
''clipped'').
Circles may of course be drawn as an ellipse with
xdiam=ydiam.



For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the curve are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the curve.
If
mode='x',
the
value[]
is XORed with pixels along the curve.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of pixels along the curve are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels along the curve are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn curve is solid; every pixel
along the curve is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read,
along with the end point pixels.
Using
dotspace>1
increases the effective drawing speed
and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn curve is 1 pixel thick.
Otherwise, the drawn curve is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.










Draw Icon or Cursor   ---   pxip8_drawicon







Summary



int pxip8_drawicon(ip, imxy, iconbit, icondim, iconorg, iconmode, pixmode, pixvalue, bufip);


struct  pximage     *ip;            // image
struct  pxy         *xyp;           // coordinate in ip for icon origin
uchar               iconbit[];      // icon's definition, bit map
                                    // use NULL for predefined cross-hair
struct  pxy         *icondim;       // icon's dimensions
struct  pxy         *iconorg;       // icon's origin
int                 iconmode;       // if xyp out of image window:
                                    //  0:  don't draw
                                    // 'p': draw pixels falling within window
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    //  0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, only for 'b' mode
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


An arbitrary bit map defined icon is drawn in the image referenced by
ip,
at the coordinate defined by
xyp.
A
''1''
bit in the icon causes the corresponding image pixel to be modified
as defined below, a
''0''
bit in the icon has no effect on the image pixel.


The image coordinate, icon dimension, and icon origin
are each defined by reference to a
pxy
structure.
The dimensions of the icon are specified as
icondim->x
(horizontal) and
icondim->y
(vertical).
The icon bit map is specified by the
iconbit;
interpreted as
icondim->x
times
icondim->y
bits, stored in the order left to right and top to bottom.
Within each byte of
iconbit
the most significant bit is the
''left most bit'',
and the least significant the
''right most bit''.
The
icondim->x
need not be a multiple of 8,
but note that each line of the icon starts a new byte of
iconbit.
Thus, the dimension of
iconbit
is:



((icondim->x + 7) / 8) * icondim->y




allowing for unused
''pad''
bits at the end of each line.
For example, a rectangular icon of horizontal dimension 13
and vertical dimension 5 would be defined by:



uchar bitmap[] = {
    0xFF, 0xF8,         // X X X X X X X X X X X X X
    0x80, 0x08,         // X . . . . . . . . . . . X
    0x80, 0x08,         // X . . . . . . . . . . . X
    0x80, 0x08,         // X . . . . . . . . . . . X
    0xFF, 0xF8,         // X X X X X X X X X X X X X
};




using 10 bytes.


The
iconorg
defines the origin,
or
''hot spot'',
of the icon;
i.e. the icon bit which will be positioned over coordinate
xyp
in the
ip
image with other icon bits arranged in reference to the origin.
Icon coordinates are 0, 0 for the upper left bit,
with
x
coordinates increasing to the right and
y
coordinates increasing downward.
With
iconorg->x=0
and
iconorg->y=0
the icon will appear to the lower right of the
xyp
image coordinate.
For the example bitmap shown above,
iconorg->x=6
and
iconorg->y=2
positions the hot spot in the center of the icon,
which will then appear centered about the
xyp
image coordinate.


If the
xyp
is close to and within the border of the image or area of interest,
any icon bits which fall outside of the image or area of interest
are clipped and not seen.
If
xyp
is outside of the image or area of interest:
then, if
iconmode=0
no pixels are modified,
if
iconmode='p',
then any icon bits which fall within the image or area of interest
modify the corresponding pixels.
The
iconmode='p'
allows the icon to be gradually
''slid''
from view.


Use of
iconbit=NULL
specifies use of a predefined cross-hair
of width
icondim->x
and height
icondim->y.
The thickness of the horizontal segment is specified as
iconorg->y
pixels high,
and the thickness of the vertical segment is
specified as
iconorg->x
pixels wide.
The
icondim->x
and
icondim->y
should be an odd integer between 3 and 127 (inclusive).
The
iconorg->x
and
iconorg->y
should be an odd integer between 1 and 127 (inclusive).
The
cross-hair's origin is always at its center.


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels composing the icon are set to
value[].
If
mode='+',
the
value[]
is added to the pixels composing the icon.
If
pixmode='x',
the
value[]
is XORed with the pixels composing the icon.
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of
pixels composing the icon are exchanged with the
sequence of values in
bufip.
A second invocation of the 'b'
mode, with the same icon,
restores the original pixel values.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








Example


The rectangular icon defined above is drawn, centered,
at image coordinate 100, 50 in the first image frame buffer.



struct  pxy     dimxy, orgxy, crdxy;
uint    value = 255;


dimxy.x = 13;   dimxy.y = 5;
orgxy.x = 6;    orgxy.y = 2;
crdxy.x = 100;  crdxy.y = 50;
pxip8_drawicon(
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Default"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               &crdxy, bitmap, &dimxy, &orgxy, 's', &value,NULL,NULL);












Draw Line Segment   ---   pxip8_drawline







Summary



int pxip8_drawline(abortp, ip, sxyp, exyp, dotspace, thickness, mode, value, bufip, cntp);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct pximage      *ip;            // image
struct pxy          *sxyp;          // line start coordinate
struct pxy          *exyp;          // line end coordinate , inclusive !
int                 dotspace;       // dot spacing. 1 for continuous
int                 thickness;      // line thickness: 1, 3, 5, ...
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap w. bufip
                                    // 'R': read to bufip, 0: count
uint                value[];        // value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, for 'b', 'R' modes
pxim2size_t         *cntp;          // count of pixels touched 'returned', or NULL










Description


The
pxip8_drawline
draws a line segment in the image referenced by
ip,
from the coordinate defined by
sxyp
to the coordinate defined by
exyp,
inclusive.
The
sxyp
and
exyp
coordinates are defined by references to a
pxy
structure,
and are relative to the image's coordinates,
not its area of interest.
Any portion of the line out of the
ip
area of interest is not drawn
(i.e.
''clipped'').


For
mode='s',
mode='+',
or
mode='x',
the
value[]
provides a pixel value,
dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
value[0]
specifies the grey level,
ranging from 0 to the maximum pixel component value
(255 for 8 bit pixels).
If
mode='s',
the pixels along the line segment(s) are set to
value[].
If
mode='+',
the
value[]
is added to pixels along the line segment(s).
If
pixmode='x',
the
value[]
is XORed with the pixels along the line segment(s).
If
mode=0,
no pixels are modified or read, but the number of pixels that would
be modified or read with a different
mode
is counted.


If
mode='b',
the sequence of pixels along the line segment(s) are exchanged with the
sequence of values in
bufip;
a second invocation of the operation
with identical parameters restores the original pixel values.
If
mode='R',
the sequence of pixels along the line segment(s) are read into
bufip.
The image referenced by
bufip
must be of the same pixel type as the image referenced by
ip;
pixels are exchanged or written to
bufip
in sequential order,
left-to-right and top-to-bottom, starting at window coordinate (0,0) of
bufip.


If
dotspace<=1,
then the drawn line segment(s) are solid; every pixel
along the line segment(s) is modified or read as defined above.
Otherwise only pixels at intervals of
dotspace-1
are modified or read, along with the end point pixels.
Using
dotspace>1
increases the effective drawing speed and for
mode='b'
or
mode='R'
decreases the necessary size of the
bufip.


If
thickness<=0
or
thickness<=1,
the drawn line is 1 pixel thick.
Otherwise, the drawn line is
thickness
pixels thick, where
thickness
must be odd.
Use of a thickness larger than 1
is intended only for use with
mode='s'.


For images composed of float or double pixels
with
pixmode='s'
or
pixmode='+',
value[]
0 through ~(uint)0
is interpolated into the minimum through maximum pixel values.
The effect of
pixmode='x'
is undefined.


If
cntp≠NULL,
the number of pixels drawn,
or for
mode=0
would be drawn, is
''returned''
at
*cntp.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 32 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








Example


Draw two white diagonal lines from corner to corner,
hitting alternate pixels.
The image is assumed monochrome, with one 8 bit pixel component.



struct  pxy sxy, exy;       // line coordinates
uint    value = 255;        // pixel value


sxy.x = 0; sxy.y = 0;
exy.x = pxd_xdim() -1;                  // endinf coordinate  w. SVOBJ,4MOBJ,XCOBJ
exy.y = (pxd_ydim()<<pxd_ylace()) -1;   // ending coordinate  w. SVOBJ,4MOBJ,XCOBJ
exy.x = pxd_imageXdim() -1;             // ending coordinate  w. XCLIB
exy.y = pxd_imageYdim() -1;             // ending coordinate  w. XCLIB
pxip8_drawline(NULL,
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               &sxy, &exy, 2, 1, 's', &value, NULL, NULL);
sxy.x = pxd_xdim() - 1;
sxy.y = 0; exy.x = 0;
exy.y = (pxd_ydim()<<pxd_ylace()) -1;   // ending coordinate  w. SVOBJ,4MOBJ,XCOBJ
exy.y = pxd_imageYdim() -1;             // ending coordinate  w. XCLIB
pxip8_drawline(NULL,
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               &sxy, &exy, 2, 1, 's', &value, NULL, NULL);






Read pixel values along a line at an arbitrary angle.
There are more efficient methods of reading pixels
along a horizontal or vertical line.
The image is assumed monochrome, with one 8 bit pixel component.



#define N   200         // max number of pixels expected
struct  pxy sxy, exy;   // line coordinates
uchar   buf[N];         // destination for pixel values
struct  pxy     bufxy;  // describe buf
struct  pximage bufip;  // describe buf
long    cnt = 0;        // result count


sxy.x = 0; sxy.y = 0;   // specify line at 45 degrees
sxy.x = exy.y = 100;
bufxy.x = N;            // describe buf
bufxy.y = 1;
pximage_memory(&bufip, buf, &bufxy, 0, PXDATUCHAR, 8, 1, PXHINTGREY, 0);
pxip8_drawline(NULL,
               #if 1       // w. XCLIB
                 pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
               #else       // w. SVOBJ,4MOBJ,XCOBJ
                 pxd_defimage(1,0,0,-1,-1),
               #endif
               &sxy, &exy,
               1, 1, 'R', NULL, bufip, &cnt);       // read
printf("pixel values read: %d\n", cnt);            // report
for (int i = 0; i < cnt; i++)
    printf("%d\n", buf[i]);












Draw Alignment Pattern   ---   pxip8_patternalign







Summary



int pxip8_patternalign(abortp, ip, type);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *ip;            // target image
int                 type;           // reserved. should be 0










Description


An alignment pattern is drawn in the image referenced by
ip.
There are no current options, the
type
should be 0.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Draw 2-D Cosine Product Pattern   ---   pxip8_patterncos







Summary



int pxip8_patterncos(abortp, ip, patp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *ip;            // target image
struct pxip8pat     *patp;          // parameters




struct  pxip8pat
{
    int     xfreq;      // x frequency
    int     yfreq;      // y frequency
    ...
};










Description


A two-dimensional cosine product pattern is drawn in the image defined
by
ip.
For integer pixels, the pattern generated is of the form:



(cos(x+y)+1) * maximum_pixel_value/2




For real pixels, the pattern generated is of the form:



(cos(x+y)+1) * (max_pixel_value - min_pixel_value) + min_pixel_value






The
pxip8pat
structure referenced by
patp
specifies the frequencies of the pattern.


The
xfreq
and
yfreq
frequency parameters specify the number of cycles
(within the area of interest, if used)
in the indicated direction;
either frequency can be set to 0 for a one-dimensional pattern
in the opposite direction.
Other parameters in
*patp
are ignored.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Draw 2-D Fiducial Pattern   ---   pxip8_patternfiducial







Summary



int pxip8_patternfiducial(abortp, ip, patp, background, foreground, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *ip;            // target image
struct pxip8pat     *patp;          // parameters
uint                background[];   // background pixel value(s)
uint                foreground[];   // foreground pixel value(s)
int                 mode;           // reserved. should be 0




struct  pxip8pat
{
    int     xfreq;      // x frequency
    int     yfreq;      // y frequency
    ...
};










Description


A two-dimensional circular fiducial pattern is drawn in the image referenced by
ip.
Each fiducial pattern is drawn with a
foreground
grey level or color over a
background
grey level or color.


The
foreground[]
and
background[]
provide the pixel values to be used as the foreground
and, optionally, background;
each dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
foreground[0]
specifies the foreground grey level,
and
background[0]
specifies the background grey level.
Each of the
foreground
and
background
values may range from 0 to the maximum pixel component value
(255 for 8 bit pixels).
For images composed of float or double pixels, the
foreground
and
background
values 0 through ~(uint)0
are interpolated into the minimum through maximum pixel values.


The
pxip8pat
structure referenced by
patp
specifies the repeat frequencies of the pattern.
The
xfreq
and
yfreq
frequency parameters specify the number of fiducial patterns
(within the area of interest, if used)
in the indicated direction;
values less than 1 are taken to be 1.
Other parameters in
*patp
are ignored.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Draw 2-D Gaussian Pattern   ---   pxip8_patterngaussian







Summary



int pxip8_patterngaussian(abortp, ip, patp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *ip;            // target image
struct pxip8pat     *patp;          // parameters




struct  pxip8pat
{
    int     xfreq;      // x frequency
    int     yfreq;      // y frequency
    ...
    float   x2width;    // x pixel width at 50% intensity
    float   y2width;    // y pixel width at 50% intensity
};










Description


A two-dimensional Gaussian pattern is drawn in the image referenced by
ip.


The
pxip8pat
structure referenced by
patp
specifies the frequencies and shape of the pattern.


The
xfreq
and
yfreq
frequency parameters specify the number of curves
(within the area of interest, if used)
in the indicated direction;
values less than 1 are taken to be 1.
The
x2width
and
y2width
specify the
''steepness''
of the gaussian curve;
the width and height, in pixels,
at which the curve decays to ½ intensity.
Other parameters in
*patp
are ignored.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.
A math coprocessor is recommended.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Draw 2-D Separable Patterns   ---   pxip8_patterns







Summary



int pxip8_patterns(ip, patp, type);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *ip;            // target image
struct pxip8pat     *patp;          // parameters
int                 type;           // 'c': cos, 'r': linear ramp, 'l': log, 'g': grid




struct  pxip8pat
{
    int     xfreq;      // x frequency
    int     yfreq;      // y frequency
    char    xhalf;      // 0: x is full wave, 1: x is half wave
    char    yhalf;      // 0: y is full wave, 1: y is half wave
    char    xinvert;    // 0: x is high/low/high, 1: low/high/low
    char    yinvert;    // 0: y is high/low/high, 1: low/high/low
    int     incfc;      // 1: normal, else 'wallpaper'
    int     mulfc;      // 1: normal, else 'wallpaper'
    float   x2width;    // gaussian width  at 50% intensity
    float   y2width;    // gaussian height at 50% intensity
};










Description


Two-dimensional and separable cosine, linear ramp
or logarithmic patterns are drawn in the image referenced by
ip.


The
pxip8pat
structure referenced by
patp
specifies the frequencies and other characteristics of the pattern.


The
xfreq
and
yfreq
frequency parameters specify the number of cycles
(within the area of interest, if used)
in the indicated direction;
either frequency can be set to 0 for a one-dimensional pattern
in the opposite direction.


For each direction, with invert and half cycle parameters both off
(i.e.
xhalf,
yhalf,
xinvert,
and
yinvert
all 0)
the
patterns begin with high values (white), fall to low values (black)
and rise to high values.
The
xinvert
and
yinvert
invert parameters cause the patterns to begin low, rise high,
and fall low in the indicated direction.
The
xhalf
and
yhalf
half cycle parameters cause the patterns to begin high, fall to low
values, and immediately return to high values in a particular direction;
if invert and half cycle parameters are used then the patterns
begin low, rise to high, and immediately return to low values
in a particular direction.


The
incfc
and
mulfc
should normally be 1; other values
generate pseudorandom
''wall paper''
patterns.


If
type='r'
a linear ramp is generated in one or two dimensions,
with frequency and other parameters as described above.
If
type='l'
a logarithm of linear ramp is generated in one or two dimensions,
with frequency and other parameters as described above.
If
type='c'
the separable product of cosine pattern of the form:



(cos(x)+1) * (cos(y)+1) * maximum_pixel_value/4




is generated in one or two dimensions,
with frequency and other parameters as described above.


If
type='g'
a grid of lines whose cross section is a gaussian
curve is generated in one or two dimensions,
with frequency and other parameters as described above.
The
x2width
and
y2width
specify the
''steepness''
of the gaussian curve;
the width and height, in pixels,
at which the curve decays to ½ intensity.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Draw Test Pattern   ---   pxip8_testpattern







Summary



int pxip8_testpattern(ip, patp, type);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct pximage      *ip;            // target image
int                 type;           // see below
int                 amplitude;      // see below










Description


A selection of an image test pattern is drawn in the image referenced by
ip.


If
type=0,
a vertical bar color pattern is drawn with amplitude
0<=amplitude<=100.


If
type='s',
horizontal monochrome steps are drawn, with
amplitude
specifying the number of steps.


If
type='S',
horizontal color steps are drawn, with
amplitude
specifying the number of steps.


If
type='H',
a slice of the HSB color cylinder is drawn, with
amplitude
specifying the brightness slice.


If
type=('m'^'2'),
a Macbeth Colorchecker is drawn.
If
type=('m'^'2'^'l'),
a Macbeth Colorchecker is drawn with all rows combined into a single row.
If
type=('M'),
a Macbeth Colorchecker DC is drawn.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or color, of float or double pixels.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










H-P PCL Font: Load   ---   pxip8_pclfontload







Summary



int pxip8_pclfontload(pathname, fonthandlep);
const char          *pathname;      // File path name
void _far           **fonthandlep;  // *NULL, becomes ..   [16 bit environments]
void                **fonthandlep;  // .. *handle to font  [32 bit environments]










Description


The H-P PCL compatible font in the file referenced by
pathname
is loaded into PC memory.
The
*fonthandlep
must initially be NULL;
the handle to the loaded font is
''returned''
at
*fonthandlep.
The font handle
may be used with
pxip8_pclfontdraw
to draw characters in an image, and with
pxip8_pclfontinfo
and
pxip8_pclfontcinfo
to obtain information about the font and its characters.
The font handle is released with
pxip8_pclfontunload.
The
pxip8_pclfontload
stores the font in
_fmalloc'ed
(16 bit environments)
or
malloc'ed
(32 bit environments)
PC memory;
all such allocated memory is released by
pxip8_pclfontunload.
The amount of memory required is approximately the same as the
size of the file referenced by
pathname.


The format of the file referenced by
pathname
is expected to be Hewlett-Packard Printer Control Language (PCL)
compatible, such as used with HP LaserJet II and compatible printers,
in portrait format.
When
pxip8_pclfontdraw
draws characters from the font,
each font dot is drawn as an image pixel.
Knowing that the font was designed for 300 dpi (dots per inch)
allows the font's stated point size to be interpreted as
300/72 pixels per point.
Only font files of size less than (approximately) 63 Kbyte
are supported;
this limit allows use of typical fonts smaller than 18 pt.






Supports



80x86









Returns





0

Font loaded.


PXERNOFILE

File not found.


PXERDOSIO

DOS/Windows I/O read error.


PXERMALLOC

Memory allocation error.


PXERFILEFORM

Invalid file format
(not PCL format),
or file too large.










H-P PCL Font: Draw Line of Characters   ---   pxip8_pclfontdraw







Summary



int pxip8_pclfontdraw(abortp, ip, fonthandle, xyp, cp, cn, rsvd1, rsvd2,
                      hlead, vlead, groundtype, background, foreground);
pxabortfunc_t       **abortp;       // reserved. must be NULL
struct  pximage     *ip;            // image
void _far           *fonthandle;    // font handle [16 bit environments]
void                *fonthandle;    // font handle [32 bit environments]
struct  pxy         *xyp;           // original & final position. Modified!
char                cp[];           // chars to output
int                 cn;             // number of chars to output
int                 rsvd1;          // reserved. should be 0
int                 rsvd2;          // reserved. should be 0
int                 hlead;          // horiz lead, each side
int                 vlead;          // vert lead, top & bottom
int                 groundtype;     // 0: fill background, -1 for no fill
uint                background[];   // background pixel value(s)
uint                foreground[];   // foreground pixel value(s)










Description


Using the font referenced by
fonthandle,
where
fonthandle
was previously obtained via
pxip8_pclfontload,
a line of characters is drawn in the image referenced by
ip.
Characters can be drawn with or without background fill.


The
foreground
and
background
provide the pixel values to be used as the foreground
and, optionally, background;
each dimensioned equal to the number of
pixel components (i.e.
''pixies'')
of
ip.
For monochrome imagery,
foreground[0]
specifies the foreground grey level,
and
background[0]
specifies the (optionally used)
background grey level.
Each of the
foreground
and
background
values may range from 0 to the maximum pixel component value
(255 for 8 bit pixels).


If
groundtype=0,
characters are drawn with the
foreground
value(s)
against the filled
background
value(s).
If
groundtype=-1,
characters are drawn with the
foreground
value(s) without background fill.
Each character is drawn in the size and shape
specified by
fonthandle,
with an additional
hlead
pixels of background
''leading''
on the left and right,
and an additional
vlead
pixels of background
''leading''
on the bottom and top.
In no fill mode, the
hlead'ing
is unfilled background,
i.e. spacing,
and the
vlead
is ignored.


Up to
cn
characters are drawn, as space permits,
with character codes taken from
cp[0],
cp[1],
etc.
Note that
cp
is
not
interpreted as a NULL terminated string.


The coordinate of the baseline, left edge, of the first character
drawn is defined by
xyp,
a reference to a
pxy
structure;
with following characters on the same baseline
horizontally spaced according to each character's width plus the
hlead.
Upon completion, the
xyp->x
is modified; being incremented past the last character drawn,
and in the proper position (assuming sufficient space in the image)
to draw additional characters on the same line.


Up to
cn
characters are drawn,
as will fit between
xyp->x
and the right edge of the image, or area of interest.
If less than
cn
characters fit, the
remaining right edge margin is, in fill mode, filled with the
background
value(s).
In all cases, the number of characters drawn are returned.
No characters are drawn if
xyp->y
is too close to the top of the image, or area of interest.
The
xyp->y
may be the last line of the image, or area of interest,
allowing drawing of capital letters, but cropping any
lower case descenders.


The
pxip8_pclfontdraw
function is designed to efficiently
use the frame grabber's image memory bandwidth.
In fill mode for example, the entire line of characters
is composed and then copied to the image in a
''burst''
mode (subject to memory constraints).
Invoking
pxip8_pclfontdraw
to draw an entire line of characters is,
depending on the PC and the number of characters drawn,
10 to 100 times faster than invoking
pxip8_pclfontdraw
to draw each individual character.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.








Returns



≥0

Number of characters drawn.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.








See Also


See
pxip8_pclfontinfo
for suggested line spacing.






Example


The first example shows how a long string of characters,
which may or may not fit within the image area of interest,
can be drawn.
This image is assumed monochrome, with one pixel component.



void _far *font1 = NULL;    // [16 bit environments]
void      *font1 = NULL;    // [32 bit environments]
struct  pxy  xy;
int     n, i;
char    *p;
char    mesg[] = "A long message is to be written in the lower right"
                 " quadrant of the image. The message will not fit"
                 " on one line of the image. This IS the message."
                 " Note that in ANSI ``C'' these four lines are actually"
                 " one continuous ``C'' string (character array).";
uint    foreground = 255, background = 0;


/*
 * Load font.
 */
if (pxip8_pclfontload("normal.fnt", &font1) < 0) {
    printf("error ...\n");
    return;
}
/*
 * Size message & draw.
 * The image pixels are assumed to be monochrome.
 */
xy.x = pxd_xdim()/2;                    // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
xy.y = (pxd_ydim()<<pxd_ylace())/2;     // starting coordinate  w. SVOBJ,4MOBJ,XCOBJ
xy.x = pxd_imageXdim()/2;               // starting coordinate  w. XCLIB
xy.y = pxd_imageYdim()/2;               // starting coordinate  w. XCLIB
xy.y -= pxip8_pclfontinfo(font1)->cellheight -1;    // sufficient space at top
n = strlen(mesg);                                   // in C library
p = mesg;
while (n) {
    i = pxip8_pclfontdraw(
                NULL,
                #if 1       // w. XCLIB
                  pxd_defineImage(1,1,xy.x,xy.y,-1,-1,"Default"),
                #else       // w. SVOBJ,4MOBJ,XCOBJ
                  pxd_defimage(1,xy.x,xy.y,-1,-1),  // the image to draw in
                #endif
                font1,                              // font handle
                &xy,                                // where to draw
                p,                                  // characters to draw
                n,                                  // how many to draw
                0, 0,                               // reserved
                0,                                  // extra x leading
                0,                                  // extra y leading
                0,                                  // background filling
                &background,                        // black background
                &foreground);                       // white foreground
    if (i <= 0) {
        printf("error %d\n", i);
        pxip8_pclfontunload(&font1);
        return;
    }
    p += i;                         // these characters drawn ..
    n -= i;                         // .. on current line
    xy.x = pxd_xdim()/2;            // reset x to left edge
    xy.y += pxip8_pclfontinfo(font1)->cellheight -1;
                                    // and down 1 line
}






The second example,
an extension of the first, shows how
multiple fonts may be loaded and combined on one line.
For the sake of simplicity, this example assumes that
all characters drawn fit on one line.



void _far *font2 = NULL;    // [16 bit environments]
void      *font2 = NULL;    // [32 bit environments]


/*
 * Load second font.
 */
if (pxip8_pclfontload("italic.fnt", &font2) < 0) {
    printf("error ...\n");
    pxip8_pclfontunload(&font1);
    return;
}
/*
 * Set coordinates
 */
xy.x = 0;                               // leftmost x
xy.y = (pxd_ydim()<<xd_ylace())/2;      // middle y
/*
 * Write text
 */
i = pxip8_pxlfontdraw(NULL,
                      #if 1       // w. XCLIB
                        pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                      #else       // w. SVOBJ,4MOBJ,XCOBJ
                        pxd_defimage(1,0,0,-1,-1),
                      #endif
                      font1, xy,
                      "This is normal font, and ",
                      25, 0, 0, 0, 0, 0, &background, &foreground);
if (i > 0)
    i = pxip8_pxlfontdraw(NULL,
                          #if 1       // w. XCLIB
                            pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                          #else       // w. SVOBJ,4MOBJ,XCOBJ
                            pxd_defimage(1,0,0,-1,-1),
                          #endif
                          font2, xy,
                          "this is italicized.",
                          19, 0, 0, 0, 0, 0, &background, &foreground);
if (i < 0)
    printf("error %d\n", i);
/*
 * Be sure to unload fonts, to recover memory.
 */
pxip8_pclfontunload(&font1);
pxip8_pclfontunload(&font2);












H-P PCL Font: Obtain Information   ---   pxip8_pclfontinfo







H-P PCL Font: Obtain Character Info   ---   pxip8_pclfontcinfo







Summary [16 bit environments]



struct pxip8pclfont _far * pxip8_pclfontinfo(fonthandle);
struct pxip8pclchar _far * pxip8_pclfontcinfo(fonthandle, c);
void _far *fonthandle;      // font handle
int       c;                // character code










Summary [32 bit environments]



struct pxip8pclfont * pxip8_pclfontinfo(fonthandle);
struct pxip8pclchar * pxip8_pclfontcinfo(fonthandle, c);
void      *fonthandle;      // font handle
int       c;                // character code










Description


Information about the font referenced by
fonthandle
is returned.
The
fonthandle
must have been previously obtained via
pxip8_pclfontload.


The
pxip8_pclfontinfo
returns general font characteristics,
contained in a
pxip8pclfont
structure.
The
pxip8_pclfontcinfo
returns characteristics of symbol
c,
contained in a
pxip8pclchar
structure;
NULL is returned if the font does not contain symbol
c.


The
pxip8pclfont
and
pxip8pclchar
structures, not shown, are defined via
inclusion of
pxipl.h.
The structures are, with exceptions noted,
exact representations of the font and character descriptor tables
defined by H-P PCL.
The exceptions are:
(a) All 2 byte integer values are in correct byte order
for interpretation as a numerical value on the host machine,
(b) All values in quarter dot units have been rounded to full dot units.
The casual programmer need not be concerned with these tables,
other than noting that the suggested character line spacing
may be found as:



pxip8_pclfontinfo(pclhandle)->cellheight - 1




Interpretations of the other table values may
be found in H-P PCL documentation.






Supports



80x86









Returns


As described above.








H-P PCL Font: Unload   ---   pxip8_pclfontunload







Summary



void pxip8_pclfontunload(fonthandlep);
void _far           **fonthandlep;  // *handle to font [16 bit environments]
void                **fonthandlep;  // *handle to font [32 bit environments]










Description


The font referenced by
*fonthandlep
is unloaded,
and all memory used by the font is
free'ed
or
_ffree'ed.
The
fonthandle
must have been previously obtained via
pxip8_pclfontload.


After
pxip8_pclfontunload,
the
*fonthandlep
is invalid, set to NULL, and must not be used with any function.






Supports



80x86









Returns


None.



 
 
 



26.  Spatial and Intensity Calibration









Calibrate Spatial Mapping   ---   pxip_calibxyhv







Summary



int pxip_calibxyhv(mode, order, xy, hv, handlep);
int                 mode;           // reserved. should be 0
int                 order;          // 2: 2nd order, 3: 3rd order
struct  pxyd        xy[];           // X, Y coordinates
struct  pxyd        hv[];           // corresponding H, V coordinates
void                **handlep;      // *NULL, becomes *handle to mapping state










Description


A mapping state to perform spatial calibration is created,
allowing mapping of pixel X, Y coordinates
to user-defined H, V coordinates.
The
*handlep
must initially be NULL;
the handle to the mapping state is
''returned''
at
*handlep.
The handle
may be used with
pxip_calibxyhvmap
and
pxip_calibhvxymap
to map X, Y coordinates to/from H, V coordinates.
The mapping state handle is released with
pxip_calibxyhvdone.
The
pxip_calibxyhv
stores the mapping state in
malloc'ed
PC memory;
all such allocated memory is released by
pxip_calibxyhvdone.
The amount of memory required is less than 128 bytes.


If
order=2,
the
xy
and
hv
should each reference an array of dimension 2,
defining two X, Y coordinates and their corresponding
H, V coordinates.
The
order=2
provides a linear mapping,
the H being scaled and offset with respect to X,
and similarly for V and Y.


If
order=3,
the
xy
and
hv
should each reference an array of dimension 3,
defining three X, Y coordinates and their corresponding
H, V coordinates.
The
order=3
provides a bilinear mapping,
the H-V coordinates being scaled, offset, and rotated with respect
to the X, Y coordinates.


Some combinations of calibration points are unacceptable.
For example, trying to assign two different H, V coordinates to the same
X, Y coordinate,
or using a set of three calibration points that are collinear.


Using
pxip_calibxyhv,
in itself,
does not affect the result of other image processing functions;
nor does it modify any image.
Rather it enables later use of
pxip_calibxyhvmap
and
pxip_calibhvxymap
which maps X, Y coordinates to H, V coordinates;
either to be invoked directly,
or to be provided to functions such as
pxip8_momentsf,
pxirp8_momentsf,
or
pxirp_regionshapef.






Supports



80x86

Any pixel type and precision.
A math coprocessor is recommended.


COC40

Any pixel type and precision.








Returns



1

Calibration successful.


0

One or more calibration points are collinear or otherwise insufficient.
The
*handlep
remains NULL.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.










Release Spatial Mapping State   ---   pxip_calibxyhvdone







Summary



void pxip_calibxyhvdone(handlep);
void                **handlep;      // *handle to mapping state










Description


The mapping state referenced by
*handlep
is released,
and all memory used is
free'ed.
The
handle
must have been previously obtained via
pxip_calibxyhv.


After
pxip_calibxyhvdone,
the
*handlep
is invalid, set to NULL, and must not be used with any function.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns


None.








Perform Spatial Mapping   ---   pxip_calibxyhvmap







Perform Inverse Spatial Mapping   ---   pxip_calibhvxymap







Summary



void pxip_calibxyhvmap(handle, xyp, hvp);
void pxip_calibhvxymap(handle, hvp, xyp);
void                *handlep;       // handle to mapping state
struct  pxyd        *xyp;           // x, y coordinates
struct  pxyd        *hvp;           // h, v coordinates










Description


Using the mapping state referenced by
handle,
where
handle
was previously obtained via
pxip_calibxyhv,
X, Y coordinates can be mapped into H, V coordinates,
or inversely.


The
pxip_calibxyhvmap
maps X, Y coordinates referenced by
xy
into H, V coordinates,
placing the result at the
pxyd
structure referenced by
hv.


The
pxip_calibhvxymap
maps H, V coordinates referenced by
hv
into X, Y coordinates,
placing the result at the
pxyd
structure referenced by
xy.


Note:
Although the X, Y and H, V
coordinates are expressed in
''double''
precision,
actual computations are currently performed in
''float''
precision.






Supports



80x86

Any pixel type and precision.
A math coprocessor is recommended.


COC40

Any pixel type and precision.








Returns


None.








Calibrate Intensity/Density Mapping   ---   pxip_calibzi







Summary



int pxip_calibzi(mode, order, z, i, handlep);
int                 mode;           // interpolation: 's': spline, 'l': linear
int                 order;          // number of calibration points, 2-6
double              z[];            // pixel values
double              i[];            // corresponding intensity values
void                **handlep;      // *NULL, becomes *handle to mapping state










Description


A mapping state to perform intensity or density calibration is created,
allowing mapping of pixel values
to user-defined intensity or density values.
The
*handlep
must initially be NULL;
the handle to the mapping state is
''returned''
at
*handlep.
The handle
may be used with
pxip_calibzimap
to map pixel values to intensity or density values.
The mapping state handle is released with
pxip_calibzidone.
The
pxip_calibzi
stores the mapping state in
malloc'ed
PC memory;
all such allocated memory is released by
pxip_calibzidone.
The amount of memory required is less than 128 bytes.


The
order
specifies the number of corresponding
calibration points provided,
2<=order<=6.
The
z
and
i
should each reference an array of dimension
order,
defining pixel values in
z,
and their corresponding intensity or density values in
i.
If
mode='l',
a piecewise linear extrapolation is used.
If
mode='s',
a cubic spline extrapolation is used.
Unlike linear extrapolation for which the resulting curve
(generally) has discontinuities at each calibration point,
the cubic spline offers a smooth curve through all calibration points,
but with the possibility of overshoot or oscillations
depending upon the values used.


The values referenced by
z
must be unique;
or if any
z[]
values are duplicated
then they should have the same corresponding
i[]
value.
In the event of any duplicates,
pxip_calibzi
may ignore the duplicates,
or may average the offending
i[]
values;
a particular behavior in this regard should not
be depended upon.


Using
pxip_calibzi,
in itself,
does not affect the result of other image processing functions;
nor does it modify any image.
Rather it enables later use of
pxip_calibzimap
which maps pixel values to intensity or density values;
either to be invoked directly,
or to be provided to functions such as
pxip8_momentsf,
pxirp8_momentsf,
pxip8_histstatf,
or
pxirp_regionshapef.






Supports



80x86

Any pixel type and precision.
A math coprocessor is recommended.


COC40

Any pixel type and precision.








Returns



1

Calibration successful.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.








Example





void    maphandle = NULL;


/*
 * A density mapping is defined using 5 calibration points.
 */
{
    double  pixvalues[5] = {   0,  45,    97,  153,  243 };
    double  densities[5] = { 1.3,  1.7,  2.4,  2.9,  3.0 };


    pxip_calibzi('s', 5, pixvalues, densities, &maphandle);
}


/*
 * The histogram of the first image frame buffer is obtained,
 * and the density mapping used for pxip8_histstatf.
 */
{
    struct  pxip8histab   histab;
    struct  pxip8histstat histstat;
    struct  pxip8histperc histperc;


    pxip8_histab(NULL,
                 #if 1       // w. XCLIB
                   pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                 #else       // w. SVOBJ,4MOBJ,XCOBJ
                   pxd_defimage(1,0,0,-1,-1),
                 #endif
                 &histab);
    pxip8_histstatf(&histab, pxip_calibzimap, maphandle, &histstat, &histperc);
}


/*
 * The mapping is freed after one or more uses.
 */
void pxip_calibzidone(&maphandle);












Release Intensity/Density Mapping State   ---   pxip_calibzidone







Summary



void pxip_calibzidone(handlep);
void                **handlep;      // *handle to mapping state










Description


The mapping state referenced by
*handlep
is released,
and all memory used is
free'ed.
The
handle
must have been previously obtained via
pxip_calibzi.


After
pxip_calibzidone,
the
*handlep
is invalid, set to NULL, and must not be used with any function.






Supports



80x86

Any pixel type and precision.


COC40

Any pixel type and precision.








Returns


None.








Perform Intensity/Density Mapping   ---   pxip_calibzimap







Summary



double pxip_calibzimap(handle, xyp, z);
void                *handlep;       // handle to mapping state
struct  pxyd        *xyp;           // ignored
double              z;              // pixel value










Description


Using the mapping state referenced by
handle,
where
handle
was previously obtained via
pxip_calibzi,
the pixel value
z
is mapped into an
intensity or density value.


Note:
Although the pixel value and the intensity or density
values are expressed in
''double''
precision,
actual computations are currently performed in
''float''
precision.






Supports



80x86

Any pixel type and precision.
A math coprocessor is recommended.


COC40

Any pixel type and precision.








Returns


The intensity or density value.



 
 
 



27.  Image Normalizations









Histogram Equalization   ---   pxip8_histfit







Summary



int pxip8_histfit(abortp, sip, dip, hp, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
struct  pxip8histab *hp;            // desired frequency distribution
                                    // or NULL for uniform
int                 mode;           // reserved. should be 0










Description


The image referenced by
sip
is modified so that its histogram has a specified shape
and the result placed in the image referenced by
dip.
Histogram equalization often improves image contrast.


If
hp=NULL,
the resulting image's histogram is uniform and flat.
Alternately,
hp
may reference a
pxip8histab
structure,
described under
pxip8_histab,
which specifies a desired frequency distribution,
in the
hp->count[],
to which the image's histogram should be fit.
The sum of the
hp->count[]
must be equal to the number of pixels in the image referenced by
sip.


The image is modified by shifting pixel values.
For example, assuming
hp=NULL,
an image of
''n''
pixels, and a maximum pixel value of
''k'':
the lowest
n/(k+1)
pixels are shifted to value 0,
the next lowest
n/(k+1)
pixels are shifted to value 1, etc.
If the number of pixels in the image
is divisible by (k+1),
the resulting histogram will be perfectly flat;
otherwise the resulting pixel frequencies will differ by at most 1 count.


For color images, the mean of the pixel value components are shifted;
each pixel's components are scaled by the same multiplicative factor.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters, including
incorrect sum of
hp->count[].


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Normalize Image as per Background Image   ---   pxip8_normalizebackground







Summary



int pxip8_normalizebackground(abortp, s1p, s2p, dip, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1, background
struct  pximage     *s2p;           // source 2, image
struct  pximage     *dip;           // destination
int                 mode;           // 's': subtractive, 'r': ratio










Description



The
pxip8_normalizebackground
performs a type of normalization often
referred to as
''flat-field'',
intended to correct for lighting variations
over what should be an evenly illuminated subject.
The image referenced by
s1p
should be an image captured of a flat white target
(or any other constant grey level),
while the image referenced by
s2p
should be the subject image captured under identical
illumination and camera adjustments.
Using
s1p,
which should be of constant grey level,
as a map of illumination variations, the
s2p
is corrected for uneven illumination
and the result placed in the image referenced by
dip.


If
mode='s'
the images are assumed to represent the target/subject
as modified by additive variations of illumination.


If
mode='r'
the images are assumed to represent the target/subject
as modified by multiplicative variations of illumination.


The
s1p,
s2p,
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
s1p
and
s2p
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Correct Image as per Speckle Mask   ---   pxip8_normalizespecklemask







Correct Image as per Speckle Mask   ---   pxip8_normalizespecklemask2







Summary



int pxip8_normalizespecklemask(abortp, s1p, s2p, dip, testmap, nmap, testbit, mode);
int pxip8_normalizespecklemask2(abortp, s1p, s2p, dip, testvalue, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *s1p;           // source 1, background
struct  pximage     *s2p;           // source 2, image
struct  pximage     *dip;           // destination
uchar               *testmap;       // defines pixel values considered bad
size_t              nmap;           // dimension of above
int                 testbit;        // .. by testmap[pixelvalue]&testbit
uint                testvalue;      // defines pixel values considered bad
int                 mode;           // reserved. should be 0










Description


The
pxip8_normalizespecklemask
and
pxip8_normalizespecklemask2
are intended to remove
''spots''
caused by imperfect sensors;
i.e. bad pixels
which consistently occur in the same location.


The image referenced by
s1p
defines the bad pixel locations.
For
pxip8_normalizespecklemask
bad pixels are those for which
testmap[pixelvalue]&testbit
is not 0.
For
pxip8_normalizespecklemask2
bad pixels are those for which
the pixel value is equal to
testvalue.
The image referenced by
s2p
is corrected for the bad pixels and the result placed
in the image referenced by
dip.


The correction of bad pixels is via replacement
by a horizontally adjacent, or next to adjacent, good pixel.
For each bad pixel of
s1p
and for which the left or right horizontally
adjacent, or next to adjacent, pixel of
s1p
is not bad, the pixel of
s2p
which corresponds to the bad pixel
is replaced by the pixel of
s2p
which corresponds to the adjacent, or next to adjacent, pixel which is not bad.


The
s1p,
s2p,
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
s1p
and
s2p
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Spatial Intensity Normalization   ---   pxip8_normalizeintensity







Summary



int pxip8_normalizeintensity(abortp, sip, dip, xgran, ygran, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 xgran;          // reserved. should be 0
int                 ygran;          // reserved. should be 0
int                 mode;           // reserved. should be 0










Description


The image referenced by
sip
is corrected so as to flatten intensity variance,
and the result placed in the image referenced by
dip.
Areas of the image that are darker than average are made lighter;
areas lighter than average are made darker.
The operation is intended for images
which should exhibit a uniform intensity of background,
but exhibit shading effects due to nonuniform illumination;
such as images about to be thresholded or subject to
''Blob Analysis''.
This operation is not intended to eliminate sharp shadows;
nor is it intended for images with large foreground objects
(greater than 1/8 the image dimension)
or images with a grossly uneven distribution of foreground objects.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters, including an image or area
of interest with a dimension smaller than 4.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Normalize Lines' Mean   ---   pxip8_normalizemeanline







Normalize Columns' Mean   ---   pxip8_normalizemeancolumn







Summary



int pxip8_normalizemeanline(abortp, sip, dip, numerator, denominator, mode)
int pxip8_normalizemeancolumn(abortp, sip, dip, numerator, denominator, mode)
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                numerator;      // scale factor numerator
uint                denominator;    // scale factor denominator
int                 mode;           // reserved. should be 0










Description


The
pxip8_normalizemeanline
and
pxip8_normalizemeancolumn
normalize each line or column, respectively, of the
image referenced by
sip
and the result placed in the image referenced by
dip.


Each line or column is normalized by computing the mean value
of the line or column, then scaling each pixel in the line or column by



    numerator / (denominator * mean)




If the
denominator
or mean are 0, the line or column of pixels is set to 0.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).





 
 
 



28.  Display and Print Operations









Windows: Create Device Independent Bitmap (DIB)   ---   pxio8_DIBCreate







Windows: Release Device Independent Bitmap (DIB)   ---   pxio8_DIBCreateDone







Summary



int  pxio8_DIBCreate(sip, lutip, mode, handlep);
void pxio8_DIBCreateDone(handlep);


struct pximage      *sip;           // Image and area of interest
struct pximage      *lutip;         // Reserved, must be NULL
int                 mode;           // Reserved, should be 0
HGLOBAL             *handlep;       // Pointer to handle to DIB










Description



The
pxio8_DIBCreate
copies the contents of the image referenced by
sip
to a newly created Windows Device Independent Bitmap (DIB)
in global memory (e.g. using the Windows'
GlobalAlloc)
and the handle to the DIB returned at
handlep.
The
*handlep
must initially be NULL.


The bitmap created must be freed by
pxio8_DIBCreateDone
when no longer needed.
The
*handlep
is set to NULL.


Color images are copied as 24 bit RGB pixels
without compression.
Monochrome images are copied
as 8 bit pixels with a monochrome, identity, palette
without compression.


The number of pixels per line
should be a multiple of four;
as some Windows drivers do not properly support
Device Independent Bitmaps which violate this condition.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.






Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Windows: Display Image via DirectDraw   ---   pxio8_DirectXDisplay








Summary



int pxio8_DirectXDisplay(abortp, sip, lutip, vgapalettebits, resizemode, options, xyoptions,
                         ddsp, *ddswindp, hWnd, hDC, cursxyp, cursip);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Unused
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0:  Render from all image lines
                                    //   1:  Render from even image lines
                                    //   2:  Render from odd image lines
                                    //  21:  Render from odd image lines, duplicated
                                    //  22:  Render from even image lines, duplicated
                                    //  41:  Render even display lines from even image lines
                                    //  42:  Render odd display lines from odd image lines
                                    //       only in resizemode='1'
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
LPDIRECTDRAWSURFACE ddsp;           // DirectDraw surface
struct pxywindow    *ddswindp;      // AOI within DirectDraw surface
HWND                hWnd;           // Handle to window or NULL
HDC                 hDC;            // Handle to device context or NULL
struct pxy          *cursxyp;       // Cursor coordinate or NULL
struct pximage      *cursip;        // Cursor old/new data or NULL










Description


The
pxio8_DirectXDisplay
copies, or displays, an image referenced by
sip
onto the Direct Draw
''surface''
referenced by
ddsp.
Access to Direct Draw, and obtaining a Direct Draw
''surface'',
is the responsibility of the application.[36]


The
pxio8_DirectXDisplay
is similar to, and intended as a substitute for
pxio8_GDIDisplay,
when Direct Draw access to the S/VGA is available.
The support functions,
pxio8_GDICoord,
pxio8_GDICoord1,
and
pxio8_GDICursor
are intended to be used with
pxio8_DirectXDisplay.


If
ddsp
is a
''primary surface'',
either the
hWnd
or the
hDC,
a handle to the window or a device context for the window corresponding to the
ddsp,
should be provided, from which
pxio8_DirectXDisplay
constructs a
''clip list''.
Without
hWnd
or
hDC,
the displayed image will cover the primary surface's area,
without regard to overlaying windows or menus.
The
vgapalettebits
and the feature selected by bit 1 of
options,
used by
pxio8_GDIDisplay
for a S/VGA in paletted mode,
do not apply to
pxio8_DirectXDisplay.
Other parameters are the same as described for the
pxio8_GDIDisplay
series of functions, and not repeated here.


The
pxio8_DirectXDisplay
supports RGB/BGR surfaces with
24 or 32 bits per pixel,
and YUYV/YVYU/VYUY/UYVY surfaces.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or BGR color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome or BGR color, of float or double pixels;
application of the palette at image bit depth is not available.
Under Windows.










Windows: Display Image via Video for Windows   ---   pxio8_DrawDibDisplay








Summary



int pxio8_DrawDibDisplay(abortp, sip, lutip, vgapalettebits, resizemode, options, yignore,
                         hDrawDib, hDC, hdcwindp, cursxyp, cursip);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Unused
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0:  Render from all image lines
                                    //   1:  Render from even image lines
                                    //   2:  Render from odd image lines
                                    //  21:  Render from odd image lines, duplicated
                                    //  22:  Render from even image lines, duplicated
                                    //  41:  Render even display lines from even image lines
                                    //  42:  Render odd display lines from odd image lines
                                    //       only in resizemode='1'
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
HDRAWDIB            hDrawDib;       // VFW handle
HDC                 hDC;            // Handle to device context
struct pxywindow    *hdcwindp;      // AOI within device context
struct pxy          *cursxyp;       // Cursor coordinate or NULL
struct pximage      *cursip;        // Cursor old/new data or NULL










Description


The
pxio8_DrawDibDisplay
copies, or displays, an image referenced by
sip
onto the device context referenced by
hDC
using the
DrawDibDraw
service of the
Video for Windows API.
Access to Video for Windows, and obtaining a VFW handle,
hDrawDib,
is the responsibility of the application.


The
pxio8_DrawDibDisplay
is similar to, and intended as a substitute for
pxio8_GDIDisplay.
The support functions,
pxio8_GDICoord,
pxio8_GDICoord1,
and
pxio8_GDICursor
are intended to be used with
pxio8_DrawDibDisplay.


The
vgapalettebits
and the feature selected by bit 1 of
options,
used by
pxio8_GDIDisplay
for a S/VGA in paletted mode,
do not apply to
pxio8_DrawDibDisplay.
Other parameters are the same as described for the
pxio8_GDIDisplay
series of functions, and not repeated here.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or BGR color, of unsigned integer pixels, of 1 to 16 bits, on any device context.
Under Windows.










Windows: Display Image via GDI   ---   pxio8_GDIDisplay







Windows: Translate Image to Device Coordinates   ---   pxio8_GDICoord







Windows: Translate Device to Image Coordinates   ---   pxio8_GDICoord1







Windows: Display Cursor via GDI   ---   pxio8_GDICursor







Windows: Waterfall Line Display via GDI   ---   pxio8_GDIWaterfall








Summary



int pxio8_GDIDisplay(abortp, sip, lutip, vgapalettebits, resizemode, options,
                     xyoptions, hDC, hDCwindp, cursxyp, cursip);
int pxio8_GDICoord(sip, resizemode, xyoptions, hDC, hDCwindp, cursxyp);
int pxio8_GDICoord1(sip, resizemode, xyoptions, hDC, hDCwindp, cursxyp);
int pxio8_GDICursor(abortp, sip, resizemode, xyoptions, hDC, hDCwindp, cursxyp, cursip);
int pxio8_GDIWaterfall(abortp,vbtimefunc,vbtimefuncrefp,sip,lutip,vgapalettebits,
                       resizemode,options,bottomup,hDC,hDCwindp,scrollfactor,results);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Number of grey levels set in VGA palette
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x1: Enhance grey levels via dithering,
                                    //          otherwise don't enhance
                                    // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0:  Render from all image lines
                                    //   1:  Render from even image lines
                                    //   2:  Render from odd image lines
                                    //  21:  Render from odd image lines, duplicated
                                    //  22:  Render from even image lines, duplicated
                                    //  41:  Render even display lines from even image lines
                                    //  42:  Render odd display lines from odd image lines
                                    //       only in resizemode='1'
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
HDC                 hDC;            // Handle to device context
struct pxywindow    *hDCwindp;      // AOI within device context
struct pxy          *cursxyp;       // Cursor coordinate or NULL
struct pximage      *cursip;        // Cursor old/new data or NULL
int                 bottomup;       // 0: Scroll top to bottom, 1: Scroll bottom to top
int                 scrollfactor;   // Number of lines in scroll group, >= 1
pxvbtime_t          results[3];     // Start time, end time, lines shown
uint32    (_cfunfcc *vbtimefunc)(void*);// Video time function. _cfunfcc is a predefined
void                *vbtimefuncrefp;// Arg for vbtimefunc










Description


The
pxio8_GDIDisplay
copies, or displays, an image referenced by
sip
onto the device context referenced by
hDC.
The
pxio8_GDICoord
provides the same coordinate mapping as used by
pxio8_GDIDisplay,
mapping image coordinates to device context coordinates,
supporting applications which intend to draw cursors
or other tools at specific pixels relative to the
sip
image.
The
pxio8_GDICoord1
does the inverse of the coordinate mapping used by
pxio8_GDIDisplay,
mapping device context to image coordinates,
supporting applications which accept mouse clicks, or other pointers,
at specific pixels relative to the
sip
image.
The
pxio8_GDICursor
draws a cross-hair cursor over the image displayed in
hDC,
it may also be used to erase a cross-hair cursor previously
drawn by
pxio8_GDIDisplay
or
pxio8_GDICursor.
The
pxio8_GDIWaterfall
copies, or displays,
the first line of the image area of interest referenced by
sip
repeatedly, in
''waterfall''
fashion,
onto the device context referenced by
hDC.


These functions are similar to
pxio8_vgadisplay,
pxio8_vgacoord,
pxio8_vgacoord1,
pxio8_vgacursor,
and
pxio8_vgawaterfall,
respectively,
but customized to display images on a Windows device context (i.e. the Windows GDI).
Whereas the
pxio8_vgadisplay
and related functions use an abstract
vgaip
to reference a display device,
the
pxio8_GDIDisplay
and related functions reference the display device via an
hDC
handle to a device context, and an
hDCwindp
area of interest within the device context's surface (as per PXIPL conventions,
the
hDCwindp->se
are exclusive coordinates).
Other parameters are the same as described for
pxio8_vgadisplay
and related functions, and not repeated here.


The
pxio8_GDIDisplay
and related functions interpret a device context
with 16, 24, or 32 bits per pixel
as being RGB (e.g. having 3 pixies per pixel in the context of
pxio8_vgadisplay's
discussion of the effect of
lutip).
Device contexts with 8 or 4 bits and with a palette are interpreted
as being monochrome
(e.g. having 1 pixie per pixel);
as for
pxio8_vgadisplay,
2vgapalettebits
entries of the device context's palette
are assumed to have been set-up as monotonically increasing grey levels.
If
vgapalettebits=0,
then all device contexts are interpreted as RGB;
GDI handles the mapping of pixel values
to available palette colors (or grey levels);
however for device contexts with 8 or 4 bits and a palette
this is both slower, and typically yields fewer grey levels.


The cursor'ed pixels referenced by
cursip
should always have 3 pixies per pixel.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or BGR color, of unsigned integer pixels, of 1 to 32 bits, on any device context.
Monochrome or BGR color, of float or double pixels, on any device context;
application of the palette at image bit depth is not available.
Under Windows.








Returns


As described for
pxio8_vgadisplay,
pxio8_vgacoord,
pxio8_vgacoord1,
pxio8_vgacursor,
and
pxio8_vgawaterfall.






Example


Example 1: Display a monochrome image, assuming
the device context uses a palette, such as in 256 color mode.
First, a suitable display palette is established.



    extern      HDC hDC;        // assumed set elsewhere
    extern      HWND hWnd;      // assumed set elsewhere
    HPALETTE    hPal;
    HPALETTE    hPal, hPalold;
    struct {
        LOGPALETTE pal;
        PALETTEENTRY pale[128];
    } palproto;
    palproto.pal.palVersion = 0x300;
    palproto.pal.palNumEntries = 128;
    for (int i = 0; i < 128; i++) {
        palproto.pal.palPalEntry[i].peGreen = i*2;
        palproto.pal.palPalEntry[i].peBlue = i*2;
        palproto.pal.palPalEntry[i].peRed = i*2;
        palproto.pal.palPalEntry[i].peFlags = PC_RESERVED;
    }
    hPal = CreatePalette(&palproto.pal);
    hPalold = SelectPalette(hDC, hPal, 0);
    RealizePalette(hDC);




The first image frame buffer is displayed to the full client area;
7 bits are used to match the size of the palette created above.



    RECT        rect;
    struct      pxywindow wind;
    int         i;


    GetClientRect(hWnd, &rect);
    wind.nw.x = wind.nw.y = 0;              // from upper left
    wind.se.x = rect.right - rect.left + 1; // to right edge
    wind.se.y = rect.bottom - rect.top + 1; // and bottom edge
    i = pxio8_GDIDisplay(NULL,
                         #if 1       // w. XCLIB
                           pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                         #else       // w. SVOBJ,4MOBJ,XCOBJ
                           pxd_defimage(1,0,0,-1,-1),
                         #endif
                         NULL, 7, 'n',
                         0, 0, hDC, &wind, NULL, NULL);
    if (i < 0) {
        MessageBox(NULL, pxerrnomesg(i), "pxio8_GDIDisplay", MB_OK|MB_TASKMODAL);




After the image need no longer be seen and the device context
is overwritten with other graphics, the created
palette should be destroyed.



    SelectPalette(hDC, hPalold, 0);
    RealizePalette(hDC);
    DeleteObject(hPal);






Example 2: When the device context does not use a palette,
such as in 16 bit, 24 bit, or 32
bit VGA modes, usage is much simpler.



    extern      HDC hDC;        // assumed set elsewhere
    extern      HWND hWnd;      // assumed set elsewhere
    RECT        rect;
    struct      pxywindow wind;
    int         i;


    GetClientRect(hWnd, &rect);
    wind.nw.x = wind.nw.y = 0;              // from upper left
    wind.se.x = rect.right - rect.left + 1; // to right edge
    wind.se.y = rect.bottom - rect.top + 1; // and bottom edge
    i = pxio8_GDIDisplay(NULL,
                         #if 1       // w. XCLIB
                           pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                         #else       // w. SVOBJ,4MOBJ,XCOBJ
                           pxd_defimage(1,0,0,-1,-1),
                         #endif
                         NULL, 0, 'n',
                         0, 0, hDC, &wind, NULL, NULL);
    if (i < 0) {
        MessageBox(NULL, pxerrnomesg(i), "pxio8_GDIDisplay", MB_OK|MB_TASKMODAL);






Example 3: When the device context does not use a palette,
and the pixels should be colorized or enhanced via a supplied palette
or lookup table.



    extern      HDC hDC;        // assumed set elsewhere
    extern      HWND hWnd;      // assumed set elsewhere
    RECT        rect;
    struct      pxywindow wind;
    uchar       lutbuf[256*3];   // 8 bits per pixel * 3 colors per pixel
    struct      pximage lutimage;
    struct      pxy  lutxy;
    int         i;


    GetClientRect(hWnd, &rect);
    wind.nw.x = wind.nw.y = 0;              // from upper left
    wind.se.x = rect.right - rect.left + 1; // to right edge
    wind.se.y = rect.bottom - rect.top + 1; // and bottom edge


    for (i = 0; i < 256; i++) {             // construct palette which
        lutbuf[i*3+0] = max(255,i*2);       // which doubles the blue
        lutbuf[i*3+1] = i/2;                // halves the green
        lutbuf[i*3+2] = (i*1234567)>>2;     // and pseudo randomizes the red
    }                                       // for each pixel
    lutxy.x = 256;
    lutxy.y = 1;                            // construct description of
    pximage_memory(&lutimage, lutbuf, &lutxy, 0, PXDATUCHAR, 8, 3, PXHINTBGR, 0);
                                            // and reference to the palette


    pxio8_GDIDisplay(NULL,
                     #if 1       // w. XCLIB
                       pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                     #else       // w. SVOBJ,4MOBJ,XCOBJ
                       pxd_defimage(1,0,0,-1,-1),
                     #endif
                     &lutimage, 0, 'n',
                     0, 0, hDC, &wind, NULL, NULL);












Print Image   ---   pxio8_print







Summary



int pxio8_print(abortp, sip, parms, printfunc, printfuncrefp);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Image and area of interest
struct pxio8print   *pp;            // Print parameters, may be changed!
int       (_cfunfcc *printfunc)(void *, uchar *, size_t);
                                    // Function called back with print data
                                    // _cfunfcc is a predefined function modifier
void                *printfuncrefp; // Arg for printfunc




struct pxio8print {
    int     hreplic;        // h pixel replication factor
    int     vreplic;        // v pixel replication factor
    float   hsize;          // print h size, centimeters
    float   vsize;          // print v size, centimeters
    float   hmargin;        // left print margin, centimeters
    float   vmargin;        // top print margin, centimeters
    int     orient;         // 'p': portrait, 'l': landscape
    int     sharpen;        // preprocess: degree of sharpening, 0:none
    float   gamma;          // preprocess: gamma correction, 1.0: none
    char    *halftone;      // "screen", "dither", "threshold"
    float   halfparm;       // depends on halftone
    char    *printer;       // "HPLJ2", "HPLJ3", "HPLJ4", "IBMGP", etc
    int     printerres;     // printer resolution
    int     copies;         // 0: use front panel selection
    int     eject;          // laser & similar: eject page after output?
};










Description


The content of the image referenced by
sip
is formatted for printing,
with preprocessing, print dimensions and orientation,
printer type and resolution,
and halftone technique specified by the
parms.


The
pxio8print
structure referenced by
parms
specifies the image print format options.
If
parms->hreplic
and
parms->vreplic
are zero, the printed image is
parms->hsize
centimeters wide by
parms->vsize
centimeters high.
Otherwise, the image pixels are each replicated
parms->hreplic
times horizontally and
parms->vreplic
times vertically and the result mapped 1-1 to printer dots;
the actual print size depends upon the image dimensions and the printer resolution.
The upper left corner of the printed image is offset by
parms->hmargin
centimeters from the left,
and
parms->vmargin
centimeters from the top
(from the bottom for
''PostScript'')
of the printable page.
If
parms->orient='p'
the image is printed in portrait orientation,
If
parms->orient='l'
the image is printed in landscape orientation.
The
parms->sharpen
specifies the degree of image sharpening, from 0 (none) to 10 (maximum).
The
parms->gamma
specifies a grey level correction (brightening or darkening), with
parms->gamma=1.0
for no correction.
The
parms->halftone
and
parms->halfparm
specifies a halftone method and parameter.







halftone    


 halfparm








"screen"    


 screen density in dots per centimeter






"dither"    


 reserved, should be 0






"threshold" 


 threshold level









The
parms->printer
and
parms->printerres
specifies a target printer and resolution.







printer     


 printerres                      


 type & notes








"HPLJ2"     


 300, 150, 100, 75 DPI           


 Hewlett-Packard LaserJet II








"HPLJ3"     


 300, 150, 100, 75 DPI           


 Hewlett-Packard LaserJet III








"HPLJ4"     


 600, 300, 150, 200, 100, 75 DPI 


 Hewlett-Packard LaserJet 4








"epsongp"   


 reserved, use 0       


 Epson Graphics Printer at 120 (h) by 72 (v) DPI








"ibmgp"     


 reserved, use 0       


 IBM Graphics Printer at 120 (h) by 72 (v) DPI








"ibm4019"   


 300, 150, 100, 75 DPI 


 IBM 4019 LaserPrinter








"ccpm"      


 reserved, use 0       


 CalComp PlotMaster w. monochrome film, at 200 DPI








"alden"     


 reserved, use 0       


 Alden 9315CTP, at 203 DPI






            


                       


 The parms->halftone is ignored, use "".








"PostScript"


 reserved, use 0       


 Any PostScript compatible printer






            


                       


 The parms->halftone may be either






            


                       


 "screen" or "threshold".






            


                       


 The parms->halfparm is ignored, use 0.






            


                       


 The parms->hreplic and parms->vreplic






            


                       


 must be 0.











For
parms->copies
specifies the number of copies, for printers which support multiple copies.
If
parms->copies=0,
no copy specification is sent to the printer, allowing front panel selection.


For printers which buffer print data
until the page is complete
(i.e. HP Laserjet II, III, 4, 4000, and IBM 4019),
if
parms->eject=0,
the page is not ejected after the image is printed,
allowing printing several images on the same page.


Future versions of
pxio8_print
may change the parameters referenced by
parms;
the caller should not expect the
*parms
to remain unchanged.


The
pxio8_print
does not actually send any data to the printer port;
instead data intended for the specified type of printer is passed
back to the caller via the
printfunc,
for transmittal to a particular hardware port, or storage in a file.
The
printfunc
is invoked with three parameters:
(a) The
printfuncrefp,
(b) A pointer to the data, and
(c) The byte count of the data.
The
printfunc
normally returns 0; a return value less than 0 causes
pxio8_print
to abort and return the same value.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).


May also return a value provided by the user-defined callback function,
printfunc.






See Also


See the
SVIP User's Manual,
4MIP User's Manual,
XCIP User's Manual,
or
XCAP User's Manual
for discussion of the selection and impact of the various print options.






Example


A callback function to pass printer data via BIOS,
suitable for use under DOS and Windows 3.1, is defined.
The
''_bios_printer''
is a Microsoft ``C'' 16 bit library function.



int _cfunfcc printdata(void *vp, uchar *p, uint  n)
{
    int   timeout;
    int   lpt = 0;    // use LPT1


    for ( ; n--; p++) {
      for ( ;; ) {
        if ((_bios_printer(_PRINTER_STATUS, lpt, 0) &0x80)  // busy?
         &&!(_bios_printer(_PRINTER_WRITE, lpt, *p)&0x01))  // !timeout?
                break;
        timeout = 10000;
        while (!(_bios_printer(_PRINTER_STATUS, lpt, 0) & 0x80)) {
          if (!--timeout) {
            fprintf(stderr, "Printer timeout - retrying\n");
            timeout = 10000;
          }
        }
      }
    }
    return(0);
}




The first image frame buffer is printed to LPT1, assumed connected to a
Hewlett-Packard LaserJet II, or 100% compatible.



struct  pxio8print  parms;
int                 i;


memset(&parms, 0, sizeof parms);
parms.hsize      = 12.0;
parms.vsize      = 8.0;
parms.hmargin    = 0.0;
parms.vmargin    = 0.0;
parms.orient     = 'p';
parms.sharpen    = 5;
parms.gamma      = 1.0;
parms.halftone   = "screen";
parms.halfparm   = 21;
parms.printer    = "HPLJ2";
parms.printerres = 300;
parms.copies     = 0;
parms.eject      = 1;
i = pxio8_print(NULL,
                #if 1
                   pxd_defineImage(1,1,0,0,-1,-1,"Grey"), // w. XCLIB
                #else
                   pxd_defimage(1,0,0,-1,-1),   // w. SVOBJ,4MOBJ,XCOBJ
                #endif
                &parms, printdata, NULL);
if (i < 0)
    printf("Error\n");






An alternate callback function, suitable for use under 16 and 32 bit Windows
and Linux is defined.



int _cfunfcc printdata(void *vp, uchar *p, uint  n)
{
    FILE *fp = (FILE*)vp;
    if (fwrite(p, 1, n, fp) != n)
        return(PXERDOSIO);
    return(0);
}




The first image frame buffer is printed, using the same
printer parameters as the example above.



FILE    *fp;
#define PRINTER "LPT1"          // for Windows
#define PRINTER "/dev/lp0"      // for Linux


if (fp = fopen(PRINTER, "wb")) {
    i = pxio8_print(NULL,
                    #if 1       // w. XCLIB
                      pxd_defineImage(1,1,0,0,-1,-1,"Grey"),
                    #else       // w. SVOBJ,4MOBJ,XCOBJ
                      pxd_defimage(1,0,0,-1,-1),
                    #endif
                    &parms, printdata, fp);
    fclose(fp);
}
if (!fp || i < 0)
    printf("Error\n");












S/VGA: Translate Image to Screen Coordinates   ---   pxio8_vgacoord







S/VGA: Translate Screen to Image Coordinates   ---   pxio8_vgacoord1








Summary



int pxio8_vgacoord(sip, resizemode, xyoptions, vgaip, cursxyp);
int pxio8_vgacoord1(sip, resizemode, xyoptions, vgaip, cursxyp);
struct pximage      *sip;           // Source image and area of interest
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0: Use all image lines
                                    //   1: Ignore odd image lines
                                    //   2: Ignore even image lines
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
struct pximage      *vgaip;         // Target image, typically referencing an S/VGA
struct pxy          *cursxyp;       // Cursor coordinate or NULL. Modified!










Description


The
pxio8_vgacoord
provides the same coordinate mapping as used by
pxio8_vgadisplay,
mapping image coordinates to screen coordinates,
supporting applications which intend to draw cursors
or other tools at specific pixels relative to the
sip
image.
The
pxio8_vgacoord1
does the inverse of the coordinate mapping used by
pxio8_vgadisplay,
mapping screen to image coordinates,
supporting applications which accept mouse clicks, or other pointers,
at specific pixels relative to the
sip
image.


The
sip,
resizemode,
xyoptions,
and
vgaip
should be the same parameters as previously (or intended to be)
passed to
pxio8_vgadisplay.


For
pxio8_vgacoord,
the
cursxyp
should reference coordinates
within, and relative to, the image area of interest referenced by
sip.
The coordinates referenced by
cursxyp
are translated and altered to coordinates
relative to the area of interest referenced by
vgaip.


For
pxio8_vgacoord1,
the
cursxyp
should reference coordinates
within, and relative to, the image area of interest referenced by
vgaip.
The coordinates referenced by
cursxyp
are translated and altered to coordinates
relative to the area of interest referenced by
sip.






Supports



80x86

Any pixel type and precision.








Returns



1

Operation complete, coordinates are within the AOI.


0

Operation complete, coordinates are not within the AOI.
Note that the coordinate are still mapped, producing a result
relative to the AOI.


PXERROR

Invalid parameters.










S/VGA: Display Cursor   ---   pxio8_vgacursor








Summary



int pxio8_vgacursor(abortp, sip, resizemode, xyoptions, vgaip, cursxyp, cursip);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0: Use all image lines
                                    //   1: Ignore odd image lines
                                    //   2: Ignore even image lines
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
struct pximage      *vgaip;         // Target image, typically referencing an S/VGA
struct pxy          *cursxyp;       // Cursor coordinate
struct pximage      *cursip;        // Cursor old/new data










Description


The
pxio8_vgacursor
draws a cross-hair cursor over the image displayed in
vgaip,
it may also be used to erase a cross-hair cursor previously
drawn by
pxio8_vgadisplay
or
pxio8_vgacursor.


The
sip,
resizemode,
xyoptions,
vgaip,
cursxyp,
and
cursip
should be the same parameters as previously (or intended to be)
passed to
pxio8_vgadisplay;
pxio8_vgacursor
exchanges pixels in
cursip
with pixels in
vgaip
under the cross-hair.


In typical usage:

    

    

  1. 
An image referenced by
cursip
is set to the desired cursor color or grey level.

    

  2. 
The
pxio8_vgadisplay
is used, with cursor coordinates at, for example, 10x10.

    

  3. 
When the cursor is to be moved to, for example, 15x15:

      

      

    1. 
The
pxio8_vgacursor
is used, with cursor coordinates at 10x10, which
erases the previous cursor (assuming the same parameters
as previously passed to
pxio8_vgacursor).

      

    2. 
The
pxio8_vgacursor
is used again, with cursor coordinates at 15x15, which
draws a cursor at the new location, and saves the underlying pixels
for later erasure.

    








Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.
RGB, RGBx, BGR or BGRx color, of unsigned integer pixels, of 1 to 16 bits.








Returns



1

Operation complete, a cursor was drawn.


0

Operation complete, no cursor was drawn.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










S/VGA: Display Image   ---   pxio8_vgadisplay








Summary



int pxio8_vgadisplay(abortp,sip,lutip,vgapalettebits,resizemode,options,xyoptions,vgaip,cursxyp,cursip);
pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Number of grey levels set in VGA palette
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x1: Enhance grey levels via dithering,
                                    //          otherwise don't enhance
                                    // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0:  Render from all image lines
                                    //   1:  Render from even image lines
                                    //   2:  Render from odd image lines
                                    //  21:  Render from odd image lines, duplicated
                                    //  22:  Render from even image lines, duplicated
                                    //  41:  Render even display lines from even image lines
                                    //  42:  Render odd display lines from odd image lines
                                    //       only in resizemode='1'
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
struct pximage      *vgaip;         // Target image, typically referencing an S/VGA
struct pxy          *cursxyp;       // Cursor coordinate or NULL
struct pximage      *cursip;        // Cursor old/new data or NULL










Description


The image referenced by
sip
is copied, or displayed,
onto the image device referenced by
vgaip.
Typically, the
vgaip
references a
pximage
which provides access to the S/VGA or other display subsystem.
Unlike other functions which perform image to image copies,
pxio8_vgadisplay
provides special features intended for display applications,
such as nondestructive colorization or contrast modification,
nondestructive full screen cross-hair cursor,
and display card (i.e. S/VGA) oriented optimizations.
See
vga_open
and related functions to obtain a
pximage
which accesses the S/VGA.


If
lutip≠NULL,
the
pximage
image referenced by
lutip
is used as a lookup table or palette,
for nondestructive contrast enhancement or colorization
of the image referenced by
sip.
The
lutip
is expected to be of type PXHINTGREY, PXHINTBGR, or
PXHINTRGB with 8 bit pixies, of dimension 256x1.
The effect of the
lutip
is as follows:







lutip 


sip   


vgaip 


 result






pixies


pixies


pixies








none  


 1    


 1    


 grey level of sip






none  


 1    


 3    


 grey level of sip






none  


 3    


 1    


 intensity of sip






none  


 3    


 3    


 color of sip






 1    


 1    


 1    


 grey level of sip, contrast enhanced






 1    


 1    


 3    


 grey level of sip, contrast enhanced






 1    


 3    


 1    


 intensity of sip, contrast enhanced






 1    


 3    


 3    


 color of sip, each component contrast enhanced by same lut






 3    


 1    


 1    


 grey level of sip, contrast enhanced by green component of lutip






 3    


 1    


 3    


 false color, each monochrome pixel mapped to color via lut






 3    


 3    


 1    


 intensity of sip, contrast enhanced by green component of lutip






 3    


 3    


 3    


 color of sip, each component contrast enhanced by different lut











If
resizemode='b',
the
sip
area of interest is resized by bilinear interpolation to the
vgaip
area of interest.
If
resizemode='n',
the
sip
area of interest is resized by nearest neighbor interpolation to the
vgaip
area of interest.
If
resizemode='n'^1,
the
sip
area of interest is resized by a near neighbor interpolation
which reduces display artifacts due to the image
being interlaced (horizontally and/or vertically)
to the
vgaip
area of interest.
If
resizemode='s',
the
sip
area of interest is reduced by subsampling, or enlarged by supersampling
to be as large as possible, but fit within the
vgaip
area of interest.
If
resizemode='1',
no resizing is done, and the upper left corner of, or the entire,
sip
area of interest is copied to the upper left corner of, or the entire,
vgaip
area of interest.
For
resizemode='s'
and
resizemode='1',
the entire
vgaip
area of interest may not be used;
the unused portion is not modified.


The
pxio8_vgadisplay
does not explicitly adjust for any difference in aspect ratio
between the image referenced by
sip
and
vgaip.
Corrections to aspect ratio can be effected by suitably setting the
vgaip's
area of interest.


For paletted S/VGA modes,[37]
the
vgapalettebits
specifies the number of bits of
each pixel component to be displayed,
and implies that the first
2vgapalettebits
entries of the VGA's palette
have been set-up as monotonically increasing grey levels.[38]
For example in a 256 color S/VGA mode, the palette set-up
might map values 0 through 127 into grey levels for display of imagery, and
map values 128 through 255 into colors for screen graphics.
For such a palette, use
vgapalettebits=7,
to force all displayed pixels into the range
of 0 through 127.


If
options&0x1=0x1,
pixel values are
''enhanced''
(i.e. dithered)
so as to generate the appearance of additional grey levels
at the expense of spatial resolution.
Typically, this option is needed and supported with
vgapalettebits
less than 6 bits per pixel.


If
options&0x2=0x2
and
lutip≠NULL,
the palette is applied at
ip's
bit depth,
otherwise the palette is applied
at the display's bit depth.
The distinction is only important with
images with more than 8 bits per pixel component;
the former option allows using the palette to view
the pixel's full dynamic range, the latter option is quicker.


If
xyoptions&0xFF=1
or
xyoptions&0xFF=2
the odd (or even) lines of the image referenced by
sip
are ignored; only the even (or odd) lines are copied to
vgaip,
rendering the entire display from alternate lines of the image.
If
xyoptions&0xFF=21
or
xyoptions&0xFF=22
the even (or odd) lines of the image referenced by
sip
are ignored; the odd (or even) lines are each copied twice to
vgaip,
rendering the entire display from alternate lines of the image
but maintaining the same apparent image height when
resizemode='1'.
If
xyoptions&0xFF=41
or
xyoptions&0xFF=42
and
resizemode='1',
the odd (or even) lines of the image referenced by
sip
are ignored; only the even (or odd) lines are copied to
alternate lines of
vgaip,
rendering alternate lines of the display from alternate lines of the image.
These options are useful when displaying live video from
an interlaced camera, to avoid appearance of interlace artifacts.


If
xyoptions&0x100,
the displayed image is flipped left to right.
If
xyoptions&0x200,
the displayed image is flipped top to bottom.
If
xyoptions&0x400,
the displayed image is rotated by 90 degrees.


If
cursxyp≠NULL
a cross-hair style cursor is overlaid as the image is copied to the
vgaip.
Particularly when
pxio8_vgadisplay
is used repeatedly to update the display
(i.e.
''live''
mode),
having
pxio8_vgadisplay
draw the cursor with the image will appear better
than drawing the cursor after
pxio8_vgadisplay
is done.
The
cursxyp
should reference coordinates
within, and relative to, the image area of interest referenced by
sip.
The pixels which compose the cursor are taken from
cursip;
which should be of the same data type as
vgaip
with X dimension no smaller than:



    (vgaip->se.x - vgaip->nw.x) + (vgaip->se.y - vgaip->nw.y)




and a Y dimension of 1.
The
cursip
is not an two-dimensional image of a cursor, but a buffer wherein
cursor'ed pixels are stored.
Before using
pxio8_vgadisplay,
the image referenced by
cursip
is typically set to a constant, bright, value.
As the
sip
image is drawn, pixels along the cross-hair are
exchanged from successive locations of
cursip.
After
pxio8_vgadisplay,
the cross-hair may be removed without redrawing the entire image
by use of
pxio8_vgacursor
and the pixel data remaining in
cursip.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, RGB, RGBx, BGR or BGRx color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome, RGB, RGBx, BGR or BGRx color, of float or double pixels;
application of the palette at image bit depth is not available.








Returns



1

Operation complete, a cursor was drawn.


0

Operation complete, no cursor was drawn.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








See Also


Under Windows, the
pxio8_GDIDisplay
and related functions provide a similar
service, displaying an image to a Windows' device context.
Under Linux, the
pxio8_X11Display
and related functions provide a similar
service, displaying an image to a XWindows/X11 device context.








S/VGA: Waterfall Line Display   ---   pxio8_vgawaterfall








Summary



#include "pxobj.h"


int pxio8_vgawaterfall(abortp,vbtimefunc,vbtimefuncrefp,sip,lutip,vgapalettebits,resizemode,
                      options,bottomup,vgaip,scrollfactor,scrollfunc,scrollstate,results);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
uint32    (_cfunfcc *vbtimefunc)(void*);// Video time function. _cfunfcc is a predefined
void                *vbtimefuncrefp;// Arg for vbtimefunc
struct pximage      *sip;           // Imaging board's buffer and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Number of grey levels set in VGA palette
int                 resizemode;     // 'b': Linear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x1: Enhance grey levels via dithering,
                                    //          otherwise don't enhance
                                    // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 bottomup;       // 0: Scroll top to bottom, 1: Scroll bottom to top
struct pximage      *vgaip;         // Target image, typically referencing an S/VGA
int                 scrollfactor;   // Number of lines in scroll group, >= 1
void (_cfunfcc      *scrollfunc)(void *statep, struct pximage *vgaip, int bottomup, int scrollfactor),
void                *scrollstate,   // Optional scrolling function
uint32              results[3];     // Start time, end time, lines shown










Description


The first line of the image area of interest referenced by
sip
is repeatedly, in
''waterfall''
fashion, copied, or displayed,
onto the image device referenced by
vgaip.
Typically, the
vgaip
references a
pximage
which provides access to the S/VGA or other display subsystem.
See
vga_open
and related functions to obtain a
pximage
which accesses the S/VGA.


The
pxio8_vgawaterfall
expects that
sip
references an frame grabber's frame buffer,
and is normally used while digitizing, often with a line scan camera.
In (nominally) each field, the area of interest of
vgaip
is scrolled down, the first line of
sip
copied to the vacated space,
and the process repeated.
The effect is that the
sip
area of interest
shows the last:
vgaip->se.y-vgaip->nw.y
instances of the image line.
If
bottomup=1,
the display area of interest of
vgaip
is instead scrolled up, and the first line of
sip
copied to the vacated space.


If
lutip≠NULL,
the
pximage
image referenced by
lutip
is used as a lookup table or palette,
for nondestructive contrast enhancement or colorization
of the image referenced by
sip.
The
lutip
is expected to be of type PXHINTGREY, PXHINTBGR, or
PXHINTRGB with 8 bit pixies, of dimension 256x1.
The effect of the
lutip
is as follows:







lutip 


sip   


vgaip 


 result






pixies


pixies


pixies








none  


 1    


 1    


 grey level of sip






none  


 1    


 3    


 grey level of sip






none  


 3    


 1    


 intensity of sip






none  


 3    


 3    


 color of sip






 1    


 1    


 1    


 grey level of sip, contrast enhanced






 1    


 1    


 3    


 grey level of sip, contrast enhanced






 1    


 3    


 1    


 intensity of sip, contrast enhanced






 1    


 3    


 3    


 color of sip, each component contrast enhanced by same lut






 3    


 1    


 1    


 grey level of sip, contrast enhanced by green component of lutip






 3    


 1    


 3    


 false color, each monochrome pixel mapped to color via lut






 3    


 3    


 1    


 intensity of sip, contrast enhanced by green component of lutip






 3    


 3    


 3    


 color of sip, each component contrast enhanced by different lut











If
resizemode='b',
the
sip
area of interest is resized by linear interpolation to the
vgaip
area of interest.
If
resizemode='n',
the
sip
area of interest is resized by nearest neighbor interpolation to the
vgaip
area of interest.
If
resizemode='s',
the
sip
area of interest is reduced by subsampling, or enlarged by supersampling
to be as large as possible, but fit within the
vgaip
area of interest.
If
resizemode='1',
no resizing is done, and the left-most, or the entire,
sip
area of interest is copied to the left-most, or the entire,
vgaip
area of interest.
For
resizemode='s'
and
resizemode='1',
the entire
vgaip
area of interest may not be used;
the unused portion is not modified.


For paletted S/VGA modes,[39]
the
vgapalettebits
specifies the number of bits of
each pixel component to be displayed,
and implies that the first
2vgapalettebits
entries of the VGA's palette
have been set-up as monotonically increasing grey levels.[40]
For example in a 256 color S/VGA mode, the palette set-up
might map values 0 through 127 into grey levels for display of imagery, and
map values 128 through 255 into colors for screen graphics.
For such a palette, use
vgapalettebits=7,
to force all displayed pixels into the range
of 0 through 127.


If
options&0x1=0x1,
pixel values are
''enhanced''
(i.e. dithered)
so as to generate the appearance of additional grey levels
at the expense of spatial resolution.
Typically, this option is needed and supported with
vgapalettebits
less than 6 bits per pixel.


If
options&0x2=0x2
and
lutip≠NULL,
the palette is applied at
ip's
bit depth,
otherwise the palette is applied
at the display's bit depth.
The distinction is only important with
images with more than 8 bits per pixel component;
the former option allows using the palette to view
the pixel's full dynamic range, the latter option is quicker.


Depending on the frame grabber, video format, CPU, type of S/VGA
referenced by
vgaip,
video mode, etc., a one line per field
update rate may not be achieved.
Setting
scrollfactor>1
will reduce the scrolling overhead, by scrolling only after
each group of
scrollfactor
lines has been displayed.


If
scrollfunc≠NULL,
the
pxio8_vgawaterfall
does not implement scrolling itself, but calls:



    (*scrollfunc)(scrollstate, vgaip, bottomup, scrollfactor);




Such a user provided function may, given intimate knowledge
of the S/VGA card being accessed, perform specialized
scrolling operations faster than
pxio8_vgawaterfall.
For example, the notoriously inefficient VGA mode 0x12 can be scrolled
faster by,
(a) Specifying
scrollfactor
to be the number of lines composing a BIOS character,
(b) Having the user supplied
scrollfunc
invoke the BIOS VGA service which scrolls
up or down by one
text
line.


The
pxio8_vgawaterfall
runs continuously until
(*abortp)(...),
tested periodically, returns a nonzero value.


The
results
''returns''
three numbers indicating the throughput and update rate
achieved by
pxio8_vgawaterfall.
The
results[0]
is the operation's starting field time,
results[1]
is the operation's ending field time,
and
results[2]
is the number of times the image line was displayed.
Thus, if:



    (results[1] - results[0]) == results[2]




a image line of each field was displayed,
otherwise some fields were skipped due to overhead of the display or
scrolling process.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.






Supports



80x86

Monochrome, BGR, or BGRx color, of unsigned integer pixels, of 1 to 32 bits.
Monochrome, BGR, or BGRx color, of float or double pixels;
application of the palette at image bit depth is not available.








Returns



PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








See Also




Under Windows, the
pxio8_GDIWaterfall
provides a similar
service, displaying an image to a Windows' device context.








Linux: Display Image via XWindows/X11   ---   pxio8_X11Display







Linux: Display Cursor via XWindows/X11   ---   pxio8_X11Cursor








Summary



int pxio8_X11Display(abortp, sip, lutip, vgapalettebits, resizemode, options, xyoptions,
                     display, drawable, visualID, colormapID, drawwindp, cursxyp, cursip);
int pxio8_X11Cursor(abortp, sip, resizemode, xyoptions, display, drawable, visualID,
                    colormapID, drawwindp, cursxyp, cursip);


pxabortfunc_t       **abortp;       // Premature termination function, or NULL
struct pximage      *sip;           // Source image and area of interest
struct pximage      *lutip;         // Enhance or colorize palette, or NULL
int                 vgapalettebits; // Unused
int                 resizemode;     // 'b': Bilinear interpolation
                                    // 'n': Nearest neighbor interpolation
                                    // 'n'^1: Near neighbor deflicker interpolation
                                    // '1': 1-1 pixel
                                    // 's': Replicate/Decimate
int                 options;        // Bit 0x2: Apply palette at image bit depth,
                                    //          otherwise apply palette at display bit depth
int                 xyoptions;      // xyoptions&0xFF:
                                    //   0:  Render from all image lines
                                    //   1:  Render from even image lines
                                    //   2:  Render from odd image lines
                                    //  21:  Render from odd image lines, duplicated
                                    //  22:  Render from even image lines, duplicated
                                    //  41:  Render even display lines from even image lines
                                    //  42:  Render odd display lines from odd image lines
                                    //       only in resizemode='1'
                                    // xyoptions&0x700:
                                    //   bit  8: L-R image flip
                                    //   bit  9: T-B image flip
                                    //   bit 10: 90 deg image flip
Display             *display;       // X11 Display
Drawable            drawable;       // X11 Drawable
VisualID            visualID;       // Reserved, should be 0
Colormap            colormapID;     // Reserved, should be 0
struct pxywindow    *drawwindp;     // AOI within Drawable
struct pxy          *cursxyp;       // Cursor coordinate or NULL
struct pximage      *cursip;        // Cursor old/new data or NULL










Description


The
pxio8_X11Display
copies, or displays, an image referenced by
sip
onto the
''Drawable''
window referenced by
display
and
drawable.
The
pxio8_X11Cursor
draws a cross-hair cursor over the image displayed in
display
and
drawable;
it may also be used to erase a cross-hair cursor previously
drawn by
pxio8_X11Display
or
pxio8_X11Cursor.
The
pxio8_X11Display
and
pxio8_X11Cursor
only supports
''Drawable''
windows in TrueColor or DirectColor mode.[41]
Access to XWindows/X11 and obtaining the
''Display''
and
''Drawable''
references
is the responsibility of the application.


The
drawwindp
specifies an area of interest
within the
''drawable'';
as per PXIPL conventions,
the
drawwindp->se
are exclusive coordinates.
The
vgapalettebits,
visualID,
and
colormapID,
parameters are not used.
Other parameters are the same as described for
pxio8_vgadisplay,
pxio8_vgacursor,
and related functions, and not repeated here.


The support functions,
pxio8_vgacoord
and
pxio8_vgacoord1
are intended to be used with
pxio8_X11Display
and
pxio8_X11Cursor.


The
sip
can be a full image or an area of interest.
The image referenced by
sip
is not modified.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or BGR color, of unsigned integer pixels, of 1 to 32 bits,
on TrueColor or DirectColor displayables.
Monochrome or BGR color, of float or double pixels,
on TrueColor or DirectColor displayables;
application of the palette at image bit depth is not available.
Under Linux.





 
 
 



29.  Miscellaneous Operations









Dither Pixels, Uniform   ---   pxip8_dither







Summary



int pxip8_dither(abortp, sip, dip, ditherbits);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
uint                ditherbits;     // noise amplitude










Description


Dithering (i.e. pseudo-random noise) is added to the image referenced by
sip,
and the result placed in the image referenced by
dip.
The
pxip8_dither
operation adds pseudo-random noise with an (approximately) uniform
distribution to each pixel, with the maximum amplitude
of the noise specified as a power of 2 by
ditherbits.


For color pixels,
pseudo-random noise is independently added to
each component (i.e.
''pixie'')
of each pixel.


Addition of noise is sometimes useful for minimizing the visual
impact of false contouring,
such as when the image has been reduced to few grey levels.


The
sip
and
dip
areas of interest must be of identical dimensions,
and can reference the same image.
The image referenced by
sip
is not modified, except by overlap with
dip.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome or color, of uchar pixels, of 1 to 16 bits.








Returns



0

Operation complete.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).










Search for Pixel by Table   ---   pxip8_findpixel







Search for Pixel by Value   ---   pxip8_findpixelv







Summary



int pxip8_findpixel(abortp, ip, xyp, testmap, testbit, mode);
int pxip8_findpixelv(abortp, ip, xyp, cond, value, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // initial & end search coordinates. modified!
                                    // coordinates are absolute, not relative to AOI!
int                 mode;           // 'u': scan up (-Y), 'd': scan down (+Y)
                                    // 'l': scan left (-X), 'r': scan right (+X)
                                    //  0:  scan l-r, u-d


uchar               *testmap;       // defines pixel values to be found
sized_t             nmap;           // dimension of above
int                 testbit;        // .. by testmap[pixelvalue]&testbit


int                 cond;           // defines pixel values to be found
uint                value;          // by pixvalue>value, pixvalue<value, etc.










Description


The image referenced by
ip
is searched for specified pixel values.
The first acceptable pixel value found terminates the search.


For
pxip8_findpixel
acceptable pixel values are those for which
testmap[pixelvalue]&testbit
is not 0.


For
pxip8_findpixelv
acceptable pixel values are those for which
a comparison between the pixel value and
value
is true.
The
cond
defines the comparison performed:







cond     


 comparison








'g'^'e'  


 pixel >= value






'l'^'t'  


 pixel <  value






'g'^'t'  


 pixel >  value






'l'^'e'  


 pixel <= value






'e'^'q'  


 pixel == value






'n'^'e'  


 pixel != value











The
mode
specifies the direction of search; the
xyp
specifies the search start coordinate as modified
by the
mode.
The
*xyp
are always absolute image coordinates, and not relative to the image's
area of interest, if any.


If
mode='u'
the search begins at
xyp->x,
xyp->y-1
and proceeds by decrementing
xyp->y.
If
mode='d'
the search begins at
xyp->x,
xyp->y+1
and proceeds by incrementing
xyp->y.
If
mode='l'
the search begins at
xyp->x-1,
xyp->y
and proceeds by decrementing
xyp->x.
If
mode='r'
the search begins at
xyp->x+1,
xyp->y
and proceeds by incrementing
xyp->x.
If
mode=0
the search begins at
xyp->x+1,
xyp->y
and proceeds by incrementing
xyp->x,
then
xyp->y
(i.e. scanning left to right, top to bottom).


Upon termination, the coordinates of the first acceptable pixel are
''returned''
at
*xyp.
If no acceptable pixel is found, the first coordinate outside
of the
ip->wind
is
''returned''
at
*xyp;
xyp->x,
ip->wind.nw.y-1
for
mode='u',
xyp->x,
ip->wind.se.y
for
mode='d',
ip->wind.nw.x-1,
xyp->y
for
mode='l',
ip->wind.se.x,
xyp->y
for
mode='r',
or
ip->wind.se.x,
ip->wind.se.y
for
mode=0.


The operation will terminate prematurely if
abortp≠NULL,
and
(*abortp)(...),
tested periodically, returns a nonzero value.






Supports



80x86

Monochrome, of unsigned integer pixels, of 1 to 16 bits.


COC40

Monochrome, of uchar pixels, of 1 to 16 bits.








Returns



1

Acceptable pixel found.


0

No acceptable pixel found.


PXERROR

Invalid parameters.


PXERMALLOC

Memory allocation error.


PXERNODATA

Pixel data type is not supported.


PXERNOCOLOR

Pixel color is not supported.


PXERBREAK

Operation aborted due to
abortp
(may return other values as determined by
abortp,
PXERBREAK is suggested).








Example


The first image frame buffer
is searched for all occurrences
of pixel value 111 or 222.



struct  pxy     xy;
uchar   map[256];
int     i;


memset(map, 0, sizeof map);     // C library function
map[111] = 1;
map[222] = 1;
xy.x = -1;                      // coordinate for
xy.y = 0;                       // start of search
for (;;) {
    i = pxip8_findpixel(NULL,
                        #if 1       // w. XCLIB
                          pxd_defineImage(1,1,xy.x+1,xy.y,-1,-1,"Grey"),
                        #else       // w. SVOBJ,4MOBJ,XCOBJ
                          pxd_defimage(1,xy.x+1,xy.y,-1,-1),
                        #endif
                        &xy, map, 256, 1, 0);
    if (i != 1)
        break;
    printf("Pixel found at %d, %d\n", xy.x, xy.y);
}












Ellipse Fitting Measurement   ---   pxip_fitellipse







Summary



int pxip_fitellipse(points, npoints, mode, ellipsecoef, coniccoef);
pxyd_s              points[];       // points on ellipse
size_t              npoints;        // number of points, >= 5
int                 mode;           // reserved. should be 0
pxyd_s              ellipsecoef[3]; // result center, width, height, angle
double              coniccoef[6];   // result polynomial coefficients










Description


The
pxip_fitellipse
computes an ellipse which fits the specified points.
The ellipse's parameters are returned as
the center, width, height, and angle and
also returned as the coefficients for a second order polynomial.


The
points
are an array of unique observed points on the ellipse's boundary;
with
npoints
specifying the number of points.
At least five points must be specified.
Typically, the points are found with
pxip_fractedges.
For more accurate results, the points should be spaced
as far apart as possible along the ellipse's boundary;
a group of points taken from a narrow section of the boundary
may lead to an inaccurate result.


The parameters of the ellipse are
''returned''
in
ellipsecoef.
The
ellipsecoef[0].xd
and
ellipsecoef[0].yd
is the center,
the
ellipsecoef[1].xd
and
ellipsecoef[1].yd
is the width/2 and height/2 (prior to rotation), respectively,
and
ellipsecoef[2].xd
is the rotation angle in radians.


The parameters of the ellipse are
also
''returned''
in
coniccoef
as the conic coefficients of a second order polynomial:



A*X*X + B*X*Y + C*Y*Y + D*X + E*Y + F = 0




where
coniccoef[0]=A,
coniccoef[1]=B,
coniccoef[2]=C,
coniccoef[3]=D,
coniccoef[4]=E,
and
coniccoef[5]=F.


The
pxip_fitellipse
expects that the
points
actually fall on the boundary of an ellipse,
with some margin for error.
It is not a best-fit algorithm in the sense that
if given random points,
for example the four corners and center of a rectangle,
it will fail rather than ignore the
''outlier''
center
and fit the remaining points.


If a conic section can be fitted but not an ellipe,
the
coniccoef
''returns''
the conic coefficients.
The values in
ellipsecoef
are not set.


For better accuracy, if more than five points are given, each group of
five should be spaced out along the ellipse boundary.
For example, if 25 points are taken at one degree
(or milliradian) intervals along the boundary, they should
not be presented as:



    point[ 0]    measured at angle  0
    point[ 1]    measured at angle  1
    point[ 2]    measured at angle  2
    point[ 3]    measured at angle  3
    point[ 4]    measured at angle  4
    point[ 5]    measured at angle  5
    point[ 6]    measured at angle  6
        ...




but rather as:

    point[ 0]    measured at angle  0
    point[ 1]    measured at angle  5
    point[ 2]    measured at angle 10
    point[ 3]    measured at angle 15
    point[ 4]    measured at angle 20
    point[ 5]    measured at angle  1
    point[ 6]    measured at angle  6
        ...



Supports

80x86
Any pixel type and precision.

COC40
Any pixel type and precision.



Returns

2
Operation complete, an ellipse was fitted.

1
Operation complete, a conic section but not an ellipse was fitted.

0
A conic section could not be fitted.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.



Example

The following example: 

    pxyd_s  points[5];
    pxyd_s  ecoef[3];
    double  ccoef[6];
    int     r;


    points[0].xd =  651.0;
    points[0].yd =  491.0;
    points[1].xd =  533.0;
    points[1].yd =  647.0;
    points[2].xd =  350.0;
    points[2].yd =  514.0;
    points[3].xd =  427.0;
    points[3].yd =  367.0;
    points[4].xd =  597.0;
    points[4].yd =  384.0;
    r = pxip_fitellipse(points, 5, 0, ecoef, ccoef);
    printf("r=%d\ncenter=%.2f,%.2f\nwidth=%.2f\nheight=%.2f\nangle=%.2f\n",
           r, ecoef[0].xd, ecoef[0].yd, ecoef[1].xd, ecoef[1].yd, ecoef[2].xd);
where the points are taken from an ellipse approximately centered at 500,500 with approximate width and height of 300, produces the result: 
    r=2
    center=500.25,499.43
    width=151.41
    height=150.61
    angle=0.76
Subpixel Edge Measurement --- pxip_fractedges
Subpixel Line Measurement --- pxip_fractlines



Summary 
int pxip_fractedges(pixbuf, pixbufsize, windowsize, esthreshold, mode, nedge, edgepos, edgestrength);
int pxip_fractlines(pixbuf, pixbufsize, windowsize, esthreshold, esmatch, minwidth, maxwidth,
                    mode, nedge, edgepos, edgestrength, linewidth);
double              pixbuf[];       // pixel value
int                 pixbufsize;     // number of pixel values
int                 windowsize;     // analysis window size: 3, 5, 7, ...
int                 esthreshold;    // edge strength threshold
int                 mode;           // 'u': report all edges unsorted, unthresholded
                                    //      not used for lines
                                    //
                                    //      Bits 0xFF00:
                                    //  0:  report rising and falling edges,
                                    //      report light and dark lines
                                    // 'p': report only rising edges,
                                    //      report only light on dark lines
                                    // 'n': report only falling edges,
                                    //      report only dark on light lines
                                    //
                                    //      Bits 0x00FF:
                                    // 'l': edge/line report priority: lo to hi
                                    //  0 : same as 'l'
                                    // 'h': edge/line  report priority: hi to lo
                                    // 'm': edge/line  report priority: middle out
                                    // 'e': edge/line  report priority: ends in
double              esmatch;        // allowable percent difference in strength of two edges
double              minwidth,       // allowable minimum width of line
double              maxwidth;       // allowable maximum width of line, 0 for default
int                 nedge;          // # of edges/lines to report in edgepos, edgestrength,
                                    // linepos, linestrength, linewidth
double              edgepos[];      // edge/line positions: sorted, best first
double              edgestrength[]; // relative edge/line strengths and direction
double              linewidth[];    // line widths



Description

The pxip_fractedges performs subpixel precision edge (a single boundary between contrasting image regions) measurement, analyzing the pixel values provided in pixbuf and ''returning'' the position and relative strengths of the strongest edges in edgepos[] and edgestrength[]. The pxip_fractlines performs subpixel precision line (a pair of boundaries of a narrow contrasting image region) measurement, analyzing the pixel values provided in pixbuf and ''returning'' the position of the center of the line, relative strengths, and widths of the strongest lines in linepos[], linestrength[], and linewidth[]. Neither pxip_fractedges nor pxip_fractlines directly accesses any image.

The pixbuf should contain the value of pixels taken from consecutive image coordinates; the number of pixel values in pixbuf specified as pixbufsize. The windowsize specifies the size of the analysis window; where windowsize is odd and 3<=windowsize<=pixbufsize. Moving the analysis window along the pixel values, for each group of windowsize pixels, the fractional edge positions and strengths are determined.

For pxip_fractedges, the matched pairs of fractional edge positions, constrained by having the difference in edge strengths no larger than esmatch percent, and the distance between edges between minwidth and maxwidth, inclusive.

The nedge is the number of fractional edges/lines that are ''returned''; edgepos[] providing the fractional position relative to the beginning of pixbuf (which has position 0), and edgestrength[] providing the relative strength of the edge/line. The absolute value of edgestrength[] is the relative strength of the edge/line, ranging between 0 and 100, assuming that the original pixel values range from 0 through 255. For edges, the sign of edgestrength[] is positive if the corresponding values of pixbuf are rising, or negative if the corresponding values of pixbuf are falling. For lines, the sign of edgestrength[] is positive for light lines over dark background, or negative for dark lines over light background.

If mode='u', each fractional edge position and strength computed along pixbuf is ''returned'' in edgepos[] and edgestrength[], in order corresponding to index position along the pixbuf. As the total number of edges computed is pixbufsize-windowsize+1, an nedge of this size reports all edges, a smaller nedge reports the first nedge edges, a larger nedge fills the excess edgepos[] and edgestrength[] with 0. The esthreshold and other mode options, below, are ignored. The mode='u' option is not used for lines.

If mode≠'u', the nedge strongest edges/lines are ''returned'' in edgepos[] and edgestrength[], sorted, strongest first. If less than nedge edges/lines are found, the corresponding values of edgestrength[] are 0. For lines, the distance between the two edges, is reported in linewidth[]. For edges, if mode>>8='p', only rising edges with a positive edgestrength[] are reported; if mode>>8='n', only falling edges with a negative edgestrength[] are reported; otherwise both rising and falling edges are reported. For lines, if mode>>8='p', only light lines over dark background are reported; if mode>>8='n', only dark lines over light background are reported; otherwise both light and dark lines are reported. If esthreshold>0, all of the edge strengths are thresholded; values below esthreshold are set to 0 and therefore not reported, values above are set to esthreshold.

If mode='l', 'h', 'm', or 'e', and multiple edges/lines have the same strength, reporting priority and reporting order among each group of edges with the same strength is assigned as follows. If mode='l', edges/lines closest to the start of pixbuf have priority. If mode='h', edges/lines closest to the end of pixbuf have priority. If mode='m', edges/lines closest to the middle of pixbuf have priority. If mode='e', edges/lines closest to the ends of pixbuf have priority. It is unlikely for multiple edges/lines to have the same strength on ''real'' pixel data; these options are intended for use with esthreshold which forces all edge strengths above the threshold to be identical.

The pxip_fractedges and pxip_fractlines determines the subpixel edge position on synthetic images to a precision of better than .1 pixel. The obtainable precision on actual images, particularly images containing noise, may be less than .1 pixel.


Supports


80x86
Any pixel type and precision.

COC40
Any pixel type and precision.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.



Example

The following example: 

double  pix1[9] = { 0,  0,  0,  255,255,255,255,255,255 };
double  pix2[9] = { 250,255,255,255,255,255,250,0,  0   };
double  pos[7], str[7];
int     i;


pxip_fractedges(pix1, 9, 3, 0, 'l', 2, pos, str);
printf("edge 1: %.2f %.2f\nedge 2: %.2f %.2f\n\n",
       pos[0], str[0], pos[1], str[1]);


pxip_fractedges(pix2, 9, 3, 0, 'l', 2, pos, str);
printf("edge 1: %.2f %.2f\nedge 2: %.2f %.2f\n\n",
       pos[0], str[0], pos[1], str[1]);


pxip_fractedges(pix2, 9, 3, 0, 'u', 7, pos, str);
for (i = 0; i < 7; i++)
    printf("edge %d: %.2f %.2f\n", i+1, pos[i], str[i]);
produces the result: 
edge 1: 3.00 100.00
edge 2: 0.00 0.00


edge 1: 6.98 -99.05
edge 2: 1.00 1.96


edge 1: 1.00 1.96
edge 2: 0.00 0.00
edge 3: 0.00 0.00
edge 4: 0.00 0.00
edge 5: 2.00 -1.96
edge 6: 1.98 -99.05
edge 7: 1.00 -98.04
Halftone by Black/White Sum --- pxip8_halftsum



Summary 
int pxip8_halftsum(abortp, sip, dip);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination



Description

The image referenced by sip is halftoned, and the result image put in the image referenced by dip. The halftone operation replaces each pixel with either 0 or the maximum pixel value, in such manner that (to the extent possible) the average grey level of any image area is unchanged. The sum of white/black method is used. For best results, the original image should have good contrast and have strong edges. Some dithering is also beneficial.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Add Pseudo-Random Noise --- pxip8_noiseadd



Summary 
int pxip8_noiseadd(abortp, sip, dip, type, seed, mean, variance, parm0, parm1);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 type;           // noise distribution
uint32              seed;           // pseudo-random starting seed
double              mean;           // see below
double              variance;       // distribution's variance
double              parm0;          // see below
double              parm1;          // see below



Description

Pseudo-random noise (dithering) with a specified probability distribution is added to the image referenced by sip, and the result placed in the image referenced by dip.

If type='u', pseudo-random noise with a uniform distribution and a variance of variance is added to the image's pixels. If type='g', pseudo-random noise with a Gaussian (normal) distribution and a variance of variance is added to the image's pixels. If type='r', pseudo-random noise with a Rayleigh distribution and a variance of variance is added to the image's pixels. If type='n'^'e', pseudo-random noise with a negative exponential distribution and a variance of variance is added to the image's pixels. If type='s'^'p' randomly selected pixels are set to the minimum or maximum pixel values, with the probability of a pixel being modified specified by parm0, 0.0<=parm0<=1.0. Except as explicitly mentioned above, parameters mean, variance, parm0, or parm1 are ignored.

The seed provides the pseudo-random number generator's ''seed'' value; consistent values of seed produce consistent sequences of pseudo-random numbers, and thus identical results from pxip8_noiseadd.

For color pixels, pseudo-random noise is independently added to each component (i.e. ''pixie'') of each pixel.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 32 bits. Monochrome or color, of float or double pixels. A math coprocessor is recommended.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
Track Particle Motion --- pxip_particleflow



Summary 
int pxip_particleflow(abortp, nt, blobs, nblob, firstblob, results, nresults, nextblob,
                      minV, maxV, maxdV, minA, maxA, maxdA, trackV, trackA);


pxabortfunc_t       **abortp;       // premature termination function, or NULL
                                    // -- blobs --
int                 nt;             // nmumber of time samples
struct pxip8blob    *blobs[];       // list of blobs for each time sample, dimensioned [nt]
size_t              nblob[];        // number of blobs in above lists, dimensioned [nt]
size_t              firstblob;      // start analysis with blobs[0][firstblob]
                                    // -- results --
size_t              results[];      // indices into blobs[]
size_t              nresults;       // dimension of results
size_t              *nextblob;      // returns next blob to be first blob, 0 if all done
                                    // -- tracking parameters --
double              minV;           // min velocity, T0->T1
double              maxV;           // max velocity, T0->T1 (inclusive)
double              maxdV;          // max change/error in velocity, T1->T2->T3->T4->...
                                    // negative: percentage of T0->T1 velocity
ulong               minA;           // min area, at T0
ulong               maxA;           // max area, at T0 (inclusive)
long                maxdA;          // max change in area, T0->T1->T2->...
                                    // negative: percentage*100 of T0 area
int                 trackV;         //  0: maxdV is absolute, from T0->T1
                                    // !0: maxdV is relative, from T(t-2)->T(t-1)
int                 trackA;         //  0: maxdA is absolute, from T0
                                    // !0: maxdA is relative, from T(t-1)




struct pxip8blob
{
    struct  pxy seed;           // start coordinate of search
    struct  pxywindow wind;     // bounding rectangle, se exclusive
    ulong   xyarea;             // number of pixels
    struct  pxyd ucom;          // uniform center of mass
};



Description

A sequence of lists of blobs, representing blobs found in each image of a sequence, is analyzed, reporting each blob which has consistent and predictable displacement through the sequence of images, and is therefore, likely, a single particle in motion. The pxip_particleflow does not, by itself, analyze images nor find blobs; rather pxip_particleflow works upon existing lists of blobs, such as produced by pxip8_bloblist. Only the ucom and xyarea members of the pxip8blob structure are used by pxip_particleflow.

The nt specifies the number of images in the sequence. For each image of the sequence, blobs[0] through blobs[nt-1] provides a pointer to a list of blobs previously found in the image, and nblob[0] through nblob[nt-1] specifies the number of blobs found in the image and the dimension of each list referenced by blobs[0] through blobs[nt-1], respectively.

For each blob for which tracking is successful, results are returned in results[], as indices in blobs. For example, if two blobs were successfully tracked, and assuming nt=4, after use of pxip_particleflow the coordinates of the first blob would be recovered as: 

    blobs[0][ results[0] ].ucom
    blobs[1][ results[1] ].ucom
    blobs[2][ results[2] ].ucom
    blobs[3][ results[3] ].ucom
and for the second blob as: 
    blobs[0][ results[4+0] ].ucom
    blobs[1][ results[4+1] ].ucom
    blobs[2][ results[4+2] ].ucom
    blobs[3][ results[4+3] ].ucom
The nresults specifies the dimension of the provided results array; the maximum number of blobs that can be ''returned'' is nresults/nt. Analysis starts with blob blobs[0][firstblob] and, space for results permitting, continues through blobs[0][nblob[nt-1]]. The firstblob is normally 0 for the first invocation of pxip_particleflow; should the results be too small for the results, a second pass of pxip_particleflow can be invoked with firstblob set to the value of nextblob which was ''returned'' by the first pass.

The minV, maxV, maxdV, minA, maxA, maxdA, trackV, and trackA control the identification of particles across the image sequence. For every blob in the first image, blobs[0] (denoted as time T0, hereafter), which has area (member xyarea of pxip8blob) between minA and maxA, inclusive, the particle tracking operation will search for a corresponding blob at time T1 (i.e. blobs[1]). A blob at time T1 will be considered as corresponding to a blob at time T0 if their relative velocity (difference of position of member ucom of pxip8blob), is between minV and maxV, inclusive, and if their relative area differs by no more than maxdA.

If a corresponding blob is found at time T1, the distance between the blobs at time T0 and T1, DeltaXY, is calculated and added to the position of the blob at time T1 to give the predicted coordinates for the blob at time T2. If a blob is found at time T2 within a maxdV radius of the predicted coordinates, with a difference in area as compared to the blob at T0 no larger than maxdA, it is accepted as the same particle, and the search and verification repeated at time T3, T4, etc.

The maxdV may be negative; instead of an allowable change in velocity fixed for all particles, the allowable change in velocity is -maxdV percent of the particle's initial velocity, as determined from its T0 and T1 positions. The maxdA may be negative; instead of an allowable change in area fixed for all particles, the allowable change in area is -maxdA/100 percent of the particle's initial area, as determined from its T0 area.

If trackV≠0 the DeltaXY is updated at each time Ti, based upon the displacement from time Ti-1; allowing curved particle tracks. If trackV=0 the DeltaXY is computed as the displacement from time T0 to time T1 is used without modification, expecting the particle track to be straight, with a maxdV allowance for error.

If trackA≠0 the maxdA constraint is applied to the difference of size of the blobs at time Ti and Ti-1; allowing growing or shrinking blobs. If trackA=0 maxdA constraint is applied to the difference of size of the blobs at time Ti and T0; expecting the blob area to remain fixed, with a maxdA allowance for error.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Any pixel type and precision.

COC40
Any pixel type and precision.



Returns

≥0
Operation complete; the number of particle tracks found is returned.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

A sequence of image buffers are searched for blobs, a blob being defined as pixel with value greater than 128. Then pxip_particleflow is called repeatedly until all vectors are reported. This simplified example assumes that no errors will occur. 

#define NIMAGES     6       // number of images in sequence
#define NBLOBS      200     // max number of blobs per image
struct  pxip8blob   blob[NIMAGES][NBLOBS];
struct  pxip8blob   *blobs[NIMAGES];
uint                nblobs[NIMAGES];
int                 i, j, k;
int                 results[NIMAGES*100];
int                 nextblob = 0;


for (i = 0; i < NIMAGES; i++) {
    struct  pxywindow   bounds;
    struct  pxy         search;
    search.x = -1;                              // init search coordinates
    search.y = 0;
    bounds.nw.x = 3;                            // min blob width
    bounds.nw.y = 3;                            // min blob height
    bounds.se.x = 100;                          // max blob width
    bounds.se.y = 100;                          // max blob height
    nblobs[i] = pxip8_bloblist(NULL,
                               #if 1        // w. XCLIB
                                 pxd_defineImage(1,i+1,0,0,-1,-1,"Grey"),
                               #else        // w. SVOBJ,4MOBJ,XCOBJ
                                 pxd_defimage(i+1,0,0,-1,-1),
                               #endif
                               &search, 'g'^'t', 128, 0,
                               &bounds, 0, NULL, NBLOBS, blob[i], NULL);
    blobs[i] = blob[i];
}


do {
    i = pxip_particleflow(
                    NULL,               // no abort
                    NIMAGES,            // number of lists of blobs
                    blobs,              // array of pointers to blob lists
                    nblobs,             // number of blobs in each list
                    nextblob,           // start with this blob in first list
                    results,            // pointer to array where results are placed
                    sizeof(results)/sizeof(int),    // size of above
                    &nextblob,          // if not all blobs in first list are examined,
                                        // next blob to be first blob
                    20,                 // min velocity
                    40,                 // max velocity
                    10,                 // max change/error in velocity
                    100,                // min area
                    150,                // max area
                    20,                 // max change in area
                    0,                  // don't track V
                    0);                 // don't track A
    for (j = 0; j < i; j++) {
        printf("Next Particle Track:\n");
        for (k = 0; k < NIMAGES; k++)
            printf("X=%g Y=%g\n", blobs[k][results[j*NIMAGES+k]].ucom.xd,
                                  blobs[k][results[j*NIMAGES+k]].ucom.yd);
        printf("\n");
    }
} while (nextblob);
Recursive Average --- pxip8_recursiveaverage
Recursive Average --- pxip8_recursiveaverage2



Summary 
int pxip8_recursiveaverage(abortp, sip, dip, dap, divisor, mode);
int pxip8_recursiveaverage2(abortp, sip, dip, dap, divisor,
                           odivisor, prime,  mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
struct  pximage     *dap;           // summation buffer
int                 divisor;        // > 0
int                 odivisor;       // >= 0
int                 prime;          // 0 or >= 2 and <= divisor
int                 mode;           // reserved. should be 0.



Description

The pxip8_recursiveaverage or pxip8_recursiveaverage2 implements one cycle of recursive averaging, averaging the pixels of the input image referenced by sip into the corresponding pixels in the summation buffer referenced by dap, and producing an averaged image into the buffer referenced by dip.

The divisor specifies the number of images to be averaged, or more precisely, the decay rate of the images contained in the summation buffer dap. The pxip8_recursiveaverage or pxip8_recursiveaverage2 executes significantly faster with values of divisor that are a power of two.

Typically, the summation buffer dap is pre-allocated via pximage_memory, pximage_malloc, or similar function and initialized to 0. Thereafter, pxip8_recursiveaverage or pxip8_recursiveaverage2 is invoked with each new image sip, yielding an averaged image in dip for display or analysis, and yielding a modified summation buffer in dap for use in the next invocation of pxip8_recursiveaverage or pxip8_recursiveaverage2.

Typically, the dap has more bits per pixel than sip or dip; suggested is, at least, 

B * divisor
where B, is the number of bits per pixel of sip. Fewer bits per pixel may suffice if the images being averaged are less than maximum intensity.

With summation buffer dap pre-initialized to 0, the initial dip images will be dark, gradually increasing to proper brightness. This effect can be avoided by applying the first few sip images multiple times; such as by invoking pxip8_recursiveaverage or pxip8_recursiveaverage2 repeatedly. Alternately, setting 2<=prime<=divisor, applies sip the specified prime times with a single invocation. Using prime is quicker than multiple invocations, and produces similar - but not identical - results. The pxip8_recursiveaverage2 executes significantly faster with values of prime that are a power of two.

Modifying the divisor between invocations of pxip8_recursiveaverage or pxip8_recursiveaverage2 may result in a sip image which is too dark, too bright, or exhibits overflow artifacts. These artifacts will decay as additional sip images are applied. Alternately, if odivisor>0 the summation buffer is converted so as to produce appropriate results for the new divisor assuming that the old divisor was odivisor. For convenience, setting odivisor=divisor has no effect.

The sip, dip, and dap areas of interest must be of identical dimensions. The sip and dip can reference the same image. The image referenced by sip is not modified, except by overlap with dip or dap.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.
The image referenced by dap may be unsigned integer pixels, of 1 to 32 bits, independently of sip and dip.


Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).
FIFO Average --- pxip8_fifoaverage



Summary 
int pxip8_fifoaverage(abortp, sip, sjp, dip, dap, divisor, mode);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // old source - remove from summation
struct  pximage     *sjp;           // new source - add to summation
struct  pximage     *dip;           // destination - averaged image, or NULL
struct  pximage     *dap;           // summation buffer
int                 divisor;        // > 0
int                 mode;           // reserved. should be 0.



Description

The pxip8_fifoaverage implements one cycle of first in, first out averaging, subtracting the pixels of the input image referenced by sip and adding the pixels of the input image referenced by sjp into the corresponding pixels in the summation buffer referenced by dap, and producing an averaged image into the buffer referenced by dip.

The divisor specifies the number of images to be averaged, or more precisely, the factor by which pixel values in dap are divided to produce corresponding pixels in dip. The pxip8_fifoaverage executes significantly faster with values of divisor that are a power of two. The dip may be NULL; the summation is updated but an averaged image is not produced.

Typically, the summation buffer dap is pre-allocated via pximage_memory, pximage_malloc, or similar function and initialized to 0. Thereafter, pxip8_fifoaverage is invoked with each old image to be removed, sip, and each new image to be added, sjp, yielding an averaged image in dip for display or analysis, and yielding a summation in dap for use in the next invocation of pxip8_fifoaverage.

Typically, for sip with unsigned integer pixels, the dap has more bits per pixel than sip or dip; suggested is, at least, 

B * divisor
where B, is the number of bits per pixel of sip. Fewer bits per pixel may suffice if the images being averaged are less than maximum intensity.

The sip, sjp, dip, and dap areas of interest must be of identical dimensions. The sip, sjp, and dip can reference the same image. The image referenced by sip and sjp is not modified, except by overlap with dip or dap.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels of 1 to 16 bits, or of float pixels.
If sip, sjp, and dip are unsigned integer pixels of 1 to 16 bits, the dap may be unsigned integer pixels of 1 to 32 bits, independently of sip, sjp, and dip. If sip, sjp, and dip and float or double, the dap must be of the same type.


Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



See Also

Given a sequence of images, the pxip8_averagebufs generates an identical result. However, if used for a ''running'' average, at each cycle the pxip8_averagebufs sums all pixels of all images in the sequence. In contrast, the pxip8_fifoaverage need only add or subtract the first and last images in the sequence, but at the expense of requiring a summation buffer to be kept.

Decode SMPTE Vertical Interval Time Code --- pxip8_smptevitcdecode



Summary 
int pxip8_smptevitcdecode(abortp, sip, pixfreq, mode, *vitcp);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source image
ulong               pixfreq;        // pixel clock frequency in kHz, or 0
int                 mode;           // Bit 0: 0:quick, 1:adaptive
                                    // Bit 1: 0:careful, 1:ignore errors
struct  pxip8smptevitc *vitcp;      // result information




struct  pxip8smptevitc
{
    int     frames;         // frame count
    int     seconds;        // seconds
    int     minutes;        // minutes
    int     hours;          // hours
    uchar   fieldmark;      // field mark
    uchar   dropmark;       // drop frame mark
    uchar   colormark;      // color frame mark
    uchar   bingroupflag;   // low two bits are Bit 55, 75 resp.
    uchar   bingroups[8];   // binary groups, low 4 bits per char
};



Description

The pxip8_smptevitcdecode extracts and decodes the Vertical Interval Time Code (VITC) as defined by the Society of Motion Picture and Television Engineers (SMPTE). This operation assumes that an image has been previously captured, with the video format adjusted so as to capture portions of the vertical blanking interval (i.e. several lines above the first line normally captured) so that the image referenced by sip contains one or more lines with VITC pulses.

The pixfreq specifies the frequency, in kHz, at which the image's pixels have been sampled. Alternately, pixfreq=0 may be used with good quality images. Specifying the actual pixel sampling frequency improves the operation's ability to detect the VITC in smeared or noisy images. When used with the 4MEG VIDEO or PIXCI® series of frame grabbers, the pixel sampling frequency can be found as: 

((ulong)pxvid_xformat(PXSDIGI)->hclkfreq*pxvid_xparm(PXSDIGI)->x.samples)
/(pxvid_xparm(PXSDIGI)->x.end-pxvid_xparm(PXSDIGI)->x.offset);
When used with the SILICON VIDEO® and SILICON VIDEO® MUX series of frame grabbers, the pixel sampling frequency can be found as: 
((ulong)pxvid_xformat(PXSDIGI)->xclkfreq*pxvid_xparm(PXSDIGI)->x.samples)
/(pxvid_xparm(PXSDIGI)->x.end-pxvid_xparm(PXSDIGI)->x.offset);
In both cases above, use of the PXSDIGI state for image acquisition is assumed (or use of the pxd_ functions, which use the PXSDIGI state).

If (mode&1)=1, adaptive thresholding is used to try to extract the VITC information from poor quality images. Using (mode&1)=0 selects the quicker nonadaptive mode for use with good quality images with VITC pulses at the specification's 0 IRE and 80 IRE amplitude levels.

If (mode&2)=0, success is returned only if the VITC code's embedded CRC is correct, and there are no other indications of error. If (mode&2)=2, the result of even garbled VITC codes is returned, regardless of correctness; this option should be used with caution, almost any image line can be interpreted as a garbled VITC code.

The pxip8_smptevitcdecode scans the image referenced by sip from top to bottom, stopping at the first line which meets the VITC specification. The VITC information is decoded and returned in the pxip8smptevitc structure referenced by vitcp.

The pxip8_smptevitcdecode returns the line Y coordinate plus 1, relative to sip, at which the VITC information has been found. Note that interlaced images contain four lines of VITC (each field containing two identical lines); the various VITC lines can be decoded by executing pxip8_smptevitcdecode once, noting the line coordinate returned, executing pxip8_smptevitcdecode again with the sip defined to skip the line previously defined, and repeating as desired.

The sip can be a full image or an area of interest. The image referenced by sip is not modified.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome, of uchar pixels, of 1 to 16 bits.



Returns

>0
Valid VITC found. Specifically, the line Y coordinate plus 1, relative to the area of interest referenced by sip, at which the valid VITC was found.

0
No valid line with VITC found.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).



Example

The first image frame buffer is examined for a valid VITC code. 

struct  pxip8smptevitc vitc;
int     i, j;


i = pxip8_smptevitcdecode(NULL,
                          #if 1         // w. XCLIB
                            pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                          #else         // w. SVOBJ,4MOBJ,XCOBJ
                            pxd_defimage(1,0,0,-1,-1),
                          #endif
                          0L, 0, &vitc);
if (i < 0)
    printf("Error %s\n", pxerrnomesg(i));
else if (i == 0)
    printf("No VITC found\n");
else {
    printf("VITC:\n")
    printf("\tHour:\t%d\n", vitc.hours);
    printf("\tMinute:\t%d\n", vitc.minutes);
    printf("\tSecond:\t%d\n", vitc.seconds);
    printf("\tFrame:\t%d\n", vitc.frames);
    printf("\tField:\t%d\n", vitc.fieldmark);
    printf("\tUser:\t");
    for (j = 0; j < 8; j++)
        printf("%c ", vitc.bingroups[j]
                      +(vitc.bingroups[j]<=9?'0':'A'-10) );
    printf("\n");
}
Spatial Quantization & Shrink --- pxip8_spatialquantize



Summary 
int pxip8_spatialquantize(abortp, sip, dip, xsize, ysize, shrink);
pxabortfunc_t       **abortp;       // premature termination function, or NULL
struct  pximage     *sip;           // source
struct  pximage     *dip;           // destination
int                 xsize;          // block size, x
int                 ysize;          // block size, y
int                 mode;           // bit0=0: no shrink, bit0=1: shrink
                                    // bit1=0: average, bit1=1: summation



Description

The image referenced by sip is spatially quantized and optionally shrunk, and the result placed in the image referenced by dip.

If bit 0 of mode=0, spatial quantization coarsens the image's spatial resolution; each block of pixels of size xsize by ysize is summed, and each pixel within the block set to either the block's average or the block's sum, according to whether bit 1 of mode is 0 or 1, respectively. The resulting image is the same size as the original, but with coarser or blockier appearance. If the specified block sizes do not evenly divide the respective image dimension, then a smaller block is used along the right edge and/or bottom edge, as required.

If bit 0 of mode=1, the operation is similar, but only one pixel is set to each block's average or each block's sum, according to whether bit 1 of mode is 0 or 1, respectively. The pixels set are tightly clustered in the upper left corner of the image; remaining pixels are set to value 0. The result image is smaller than the original.

When summation is used, by bit 1 of mode=1, sums greater than the maximum pixel value are bounded to the maximum value (255 for 8 bit pixels).

The spatial quantization can be used to improve the quality of digitized images from noisy sources. For example, a better quality 256x240 result image can be obtained by digitizing a 512x480 image and applying spatial quantization with xsize=ysize=2 and mode=1; each result pixel is the average of a 2x2 area of source pixels.

The sip and dip areas of interest must be of identical dimensions, and can reference the same image. The image referenced by sip is not modified, except by overlap with dip.

The operation will terminate prematurely if abortp≠NULL, and (*abortp)(...), tested periodically, returns a nonzero value.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits. Monochrome or color, of float or double pixels.

COC40
Monochrome or color, of uchar pixels, of 1 to 16 bits.



Returns

0
Operation complete.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.

PXERBREAK
Operation aborted due to abortp (may return other values as determined by abortp, PXERBREAK is suggested).

 

 

 

30. Bound COC40 Operations

The description of the bound functions for use with the COC40 option for the 4MEG VIDEO is available on request.

 

 

 

31. Primitive Operations

The following functions provide ''primitives'' upon which other image processing functions are built. For most common applications the following primitive functions are neither needed nor of interest; the needs of most applications will be met by the more sophisticated functions provided. However for those applications which must use customized operations, these primitives have been documented.

Draw Icon Primitive, Initialize --- pxip8_drawiconinit



Summary 
int pxip8_drawiconinit(ip, imxy, iconbit, icondim, iconorg, iconmode, handlepp);
struct  pximage     *ip;            // image
struct  pxy         *xyp;           // coordinate in ip for icon origin
uchar               iconbit[];      // icon's definition, bit map
                                    // use NULL for predefined cross-hair
struct  pxy         *icondim;       // icon's dimensions
struct  pxy         *iconorg;       // icon's origin
int                 iconmode;       // if xyp out of image window:
                                    //  0:  don't draw
                                    // 'p': draw pixels falling within window
void                **handlepp;     // *NULL, becomes *handle to icon (malloc'ed)



Description

The initialization phase of pxip8_drawicon is executed, resulting in an internal representation of the icon. The *handlepp must initially be NULL; the handle to the drawable representation of the icon is ''returned'' at *handlepp. The icon handle may be used with pxip8_drawiconhit and pxip8_drawiconhitw. The meaning of the ip, xyp, iconbit, icondim, iconorg, and iconmode are identical to the same parameters discussed for pxip8_drawicon. The image referenced by ip is not modified.

The low level pxip8_drawiconinit, pxip8_drawiconhit, pxip8_drawiconhitw, and pxip8_drawiconfree primitives are components of the pxip8_drawicon operation: pxip8_drawicon is effectively defined as: 

int     i;
void *handlep = NULL;


i = pxip8_drawiconinit(ip, xyp, iconbit, icondim, iconorg, iconmode, &handlep);
if (i < 0)
    return(i);
pxip8_drawiconhit(ip, handlep, mode, value, bufip);
pxip8_drawiconhitw(ip, handlep, PXAWAIT, mode, bufip);
pxip8_drawiconfree(ip, &handlep);
return(0);
Use of these lower level icon drawing functions can reduce execution overhead when an icon is to be repeatedly drawn, cleared, or changed at the same coordinates, at a slight expense of convenience. The lower level functions also offer an additional pixel modification mode not available with pxip8_drawicon; see pxip8_drawiconhit.


Supports

80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

≥0
Number of pixels to be modified by the icon.

PXERROR
Invalid parameters.

PXERMALLOC
Memory allocation error.

PXERNODATA
Pixel data type is not supported.

PXERNOCOLOR
Pixel color is not supported.



Example

The rectangular icon defined in pxip8_drawicon is drawn, centered, at image coordinate 100, 50 in the first image frame buffer. 

struct  pxy      dimxyp, orgxy, crdxy;
void    *handlep = NULL;
int     i;
uint    value = 64;


dimxy.x = 13;   dimxy.y = 5;
orgxy.x = 6;    orgxy.y = 2;
crdxy.x = 100;  crdxy.y = 50;
i = pxip8_drawiconinit(
                       #if 1       // w. XCLIB
                         pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                       #else       // w. SVOBJ,4MOBJ,XCOBJ
                         pxd_defimage(1,0,0,-1,-1),
                       #endif
                       &crdxy, bitmap, &dimxy, &orgxy, &handlep);
if (i < 0) {
    printf("Error\n");
    return;
}
pxip8_drawiconhit(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, '+', &value, NULL);
pxip8_drawiconhitw(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, PXAWAIT, '+', NULL);
The icon was drawn by adding 64 to each pixel value. An additional 64 is added to the same icon, giving the icon a fluttering appearance. 
for (i = 1; i < 100; i++) {
    pxip8_drawiconhit(
                       #if 1       // w. XCLIB
                         pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                       #else       // w. SVOBJ,4MOBJ,XCOBJ
                         pxd_defimage(1,0,0,-1,-1),
                       #endif
                       handlep, '+', &value, NULL);
    pxip8_drawiconhitw(
                       #if 1       // w. XCLIB
                         pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                       #else       // w. SVOBJ,4MOBJ,XCOBJ
                         pxd_defimage(1,0,0,-1,-1),
                       #endif
                       handlep, PXAWAIT, '+', NULL);
}
When done, the memory acquired by pxip8_drawiconinit must be free'ed (and not referenced again). 
pxip8_drawiconfree(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   &handlep);
Draw Icon Primitive, Modify Pixels --- pxip8_drawiconhit



Summary 
int pxip8_drawiconhit(ip, handlep, mode, value, bufip);
struct  pximage     *ip;            // image
void                *handlep;       // icon handle from pxip8_drawiconinit
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap buffer
                                    // 'r': restore after 's' mode
uint                value[];        // value(s) for '+', 's', 'x' modes
struct pximage      *bufip;         // new/old pixel values, only for 'b'



Description

Using the icon referenced by handlep, where handlep was previously obtained via pxip8_drawiconinit, the modify pixel phase of pxip8_drawicon is executed. The meaning of the ip, mode, value, and bufip are identical to the same parameters discussed for pxip8_drawicon, with an additional mode is available as described below.

The mode='r' mode can be used after an icon has been drawn with mode='s' to restore the original pixel values. This allows setting pixel values to a constant and subsequent restoration without having to provide a bufip. The value and bufip are ignored. The mode='r' is not available with the higher level pxip8_drawicon operation, as the internally used structures are free'ed at completion.

The pxip8_drawiconhit generally returns before the operation is complete; pxip8_drawiconhitw should be used for test or wait for completion. In particular, with mode='b', after return the bufip will not yet contain the modified pixels' previous values.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Always.



Example

The rectangular icon defined in pxip8_drawicon is drawn, centered, at image coordinate 100, 50 in the first image frame buffer setting the pixels to value 255. 

struct  pxy      dimxy, orgxy, crdxy;
void    *handlep = NULL;
int     i;
uint    value = 255;


dimxy.x = 13;   dimxy.y = 5;
orgxy.x = 6;    orgxy.y = 2;
crdxy.x = 100;  crdxy.y = 50;
i = pxip8_drawiconinit(
                       #if 1       // w. XCLIB
                         pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                       #else       // w. SVOBJ,4MOBJ,XCOBJ
                         pxd_defimage(1,0,0,-1,-1),
                       #endif
                       &crdxy, bitmap, &dimxy, &orgxy, &handlep);
if (i < 0) {
    printf("Error\n");
    return;
}
pxip8_drawiconhit(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, 's', &value, NULL);
pxip8_drawiconhitw(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, PXAWAIT, 's', NULL);
The previous pixel values are now restored. 
pxip8_drawiconhit(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, 'r', &value, NULL);
pxip8_drawiconhitw(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   handlep, PXAWAIT, 'r', NULL);
pxip8_drawiconfree(
                   #if 1       // w. XCLIB
                     pxd_defineImage(1,1,0,0,-1,-1,"Default"),
                   #else       // w. SVOBJ,4MOBJ,XCOBJ
                     pxd_defimage(1,0,0,-1,-1),
                   #endif
                   &handlep);
Draw Icon Primitive, Test Completion --- pxip8_drawiconhitw



Summary 
int pxip8_drawiconhitw(ip, pixlist, pixlistlen, wait, mode, bufip);
struct  pximage     *ip;            // image
void                *handlep;       // icon handle from pxip8_drawiconinit
int                 wait;           // PXAWAIT, PXASYNC
int                 mode;           // '+': add value, 's': set value,
                                    // 'x': xor value, 'b': swap buffer
                                    // 'r': restore after 's' mode
struct pximage      *bufip;         // new/old pixel values, only for 'b'



Description

Using the icon referenced by handlep, where handlep was previously obtained via pxip8_drawiconinit, the pxip8_drawiconhitw tests for completion of a previous asynchronous pxip8_drawiconhit pixel modification operation. If wait=PXASYNC, then pxip8_drawiconhitw always returns immediately, with either PXODONE if the previous pxip8_drawiconhit is complete or PXOPRUN if it is not. If wait=PXAWAIT, then PXODONE is returned, but as necessary the return is delayed until the previous pxip8_drawiconhit is complete.

When mode='b' is used, the bufip will be loaded with the modified pixels' previous values only when the PXODONE is returned.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

PXODONE
Previous operation complete, or if no operation requested.

PXOPRUN
Previous operation still in progress.
Draw Icon Primitive, Free Resources --- pxip8_drawiconfree



Summary 
int pxip8_drawiconfree(ip, pixlist, pixlistlen);
struct  pximage     *ip;            // image
void                **handlepp;     // *handle to icon



Description

The icon referenced by *handlepp is unloaded, and all memory used by the icon is free'ed. The handlepp must have been previously obtained via pxip8_drawiconinit.

After pxip8_drawiconfree the *handlepp is invalid, set to NULL, and must not be used with any function.


Supports


80x86
Monochrome or color, of unsigned integer pixels, of 1 to 16 bits.

COC40
Monochrome or color, of uchar pixels, of 1 to 32 bits.



Returns

0
Always.

 

 

 

32. Extra Services

The following functions provide services which should, logically, be part of DOS and/or the ''C'' compiler's library, but are not, and are useful for many applications using PXIPL under DOS. These functions may be withdrawn or modified, if (when!) ''C'' compiler libraries provide equivalent support for these services.

DOS Mouse: Initialize Access --- mouseinit
DOS Mouse: Get Clicks --- mousegetpress
DOS Mouse: Get Status --- mousegetstatpos
DOS Mouse: Get Motion --- mousemotioncount
DOS Mouse: Terminate Access --- mousedeinit



Summary 
#include "pxextras.h"


int  mouseinit();
int  mousegetpress(button);
int  mousegetstatpos();
void mousemotioncount(xp, yp);
void mousedeinit();


int                 button;         // which button to check
int                 *xp;            // pointer to returned x motion
int                 *yp;            // pointer to returned y motion



Description

The ''mouse'' functions provide access to Microsoft compatible mice. The mouse functions provide initialization, movement information, and key press information; all via polling. Use of the ''mouse'' functions assume familiarity with mouse and VGA nomenclature.

The mouseinit initializes the interface to the mouse driver, returning 0 if a Microsoft compatible mouse driver is not found, otherwise 1. If the VGA's video mode is to be changed, the mouseinit should be called after changing the video mode.

The mousegetpress returns the number of times that a specified button has been pressed since the last call; use button=MOUSE_LEFT to check on the left button, use button=MOUSE_RIGHT to check on the right button.

The mousegetstatpos returns the current state of the mouse buttons, the MOUSE_LEFT bit set if the left button is pressed, and/or the MOUSE_RIGHT bit set if the right button is pressed.

The mousemotioncount ''returns'', via xp and yp, the X and Y distance, respectively, that the mouse has moved since the last call.

The ''mouse'' functions are independent of the frame grabber's library; i.e. invoking mouse functions has neither explicit nor implicit impact on the frame grabber, library, or driver's state. These functions are considered a temporary addition, to be phased out when (or if) future releases of ``C'' compiler libraries provide standardized functions for mouse control.


Supports


80x86
Real mode DOS and Tenberry (Rational) DOS extenders.



Returns

As described above.


Example

Mouse control of the frame grabber's features is easily accomplished by combining frame grabber library functions with mouse functions. For example, linking the mouse to the frame grabber cursor (i.e. for frame grabbers with video display capability) is easily done by using a mouse library function to obtain the amount of mouse movement since last checked, and an frame grabber cursor function to move the cursor by the specified amount: 

    #include    <stdlib.h>          // C library, for min, max


    pxcoord_t   currentx, currenty; // current cursor coordinates


    void movemouse(void)
    {
        int     x, y;


        mousemotioncount(&x, &y);   // get recent mouse movement
        x += currentx;
        y += currenty;
        x = max(0, x);              // coordinates bounded ..
        y = max(0, y);              // by image dimensions ..
        x = min(x, pxd_xdim()-1);
        y = min(y, (pxd_ydim()<<pxd_ylace())-1);
        if (x != currentx || y != currenty) {
            pxd_drcurs(1, x, y);    // draw cursor at new position
            currentx = x;
            currenty = y;
        }
    }
Repeatedly invoking the above function applies mouse movements to the video cursor. The current x and y coordinates are left available in the global currentx and currenty variables.

It is neither necessary nor desirable to move the cursor to each coordinate between the cursor's current position and its new position. The observer's visual processing will follow the motion and create the illusion of continuous movement.

A similar technique can be used to interactively threshold an image, controlling the output lookup tables (i.e. for frame grabbers with video display capability and output lookup tables) by mouse movements. An example is: 

    int     current_threshold;


    void lutthreshold(value)
    {
        uchar   buf[256*3];
        int     i;


        for (i = 0; i < 256; i++)
            buf[i] = buf[i+256] = buf[i+512] = (i<=value? 0: 255);
        pxd_lut(buf, 'w', 0);
        current_threshold = value;
    }


    void lutmouse(void)
    {
        int     x, y;


        mousemotioncount(&x, &y);
        x += current_threshold;
        x = max(0, min(255, x));
        if (x != current_threshold)
            lutthreshold(x);
    }
The lutmouse function is repeatedly invoked; translating left and right mouse motion into a varying image threshold level.
DOS S/VGA: Set Mode and Initialize Access --- vga_open
DOS S/VGA: Terminate Access --- vga_close



Summary 
#include "pxextras.h"


uint vga_open(mode, xres, yres, bits, setpal, vgaip, palip);
void vga_close(vgaip, palip);


uint                mode;           // a VGA or VESA video mode number
int                 xres;           // desired pixels per line
int                 yres;           // desired pixels per column
int                 bits;           // bits per pixel: 4, 8, or 24
int                 setpal;         // 1: set palette, 0: don't set palette
struct pximage      *vgaip;         // reference to vga display surface
struct pximage      *palip;         // reference to vga palette, or NULL



Description

The vga_open provides access to EGA, VGA, and most S/VGA graphic display cards. Use of vga_open assumes familiarity with S/VGA nomenclature, such as video modes and supported resolutions.

If mode≠0, the graphic displayed card is set to the specified video mode. Otherwise, the card is set to a mode which provides a resolution of xres pixels by yres lines, with bits per pixel. If the current S/VGA card doesn't support the specified mode, or the specified combination of xres, yres, and bits isn't supported, an alternate mode is attempted.

As per S/VGA card conventions, and unlike conventions used for frame grabbers, the bits is the total number of bits per graphics pixel; supported values are 4 (16 color), 8 (256 color) and 24 (16777216 color). Use of 8 bits is suggested for display of monochrome imagery, use of 24 bits is suggested for display of color, or colorized, imagery.

If mode and xres are both zero, vga_open provides access to the S/VGA's current mode. This is intended to allow PXIPL functions to operate in conjunction with graphics libraries which may have already set the S/VGA card's mode.

If setpal=1, and the selected, or current, video mode uses a palette, the palette is set to be suitable for display of images. Specifically, if the video mode provides 4 bits per pixel: 

    value   result color
    -----   ------------
    0       grey level 0
    1       grey level 15
        ...
    14      grey level 239
    15      grey level 255
using all 16 ''colors'' for grey levels. If the video mode provides 8 bits per pixel: 
    value   result color
    -----   -------------------------------------------
    0       grey level 0
    1       grey level 2
        ...
    126     grey level 252
    127     grey level 254
    128+0   standard graphics color attribute 0 (black)
    128+1   standard graphics color attribute 1 (blue)
        ...
    128+14  standard graphics color attribute 14 (yellow)
    128+15  standard graphics color attribute 15 (white)
    128+16  undefined
        ...
    254     undefined
    255     white
providing 128 grey levels, and additional colors for screen graphics.

After use of vga_open, the pximage referenced by vgaip provides access to the S/VGA display surface, and the pximage referenced by palip provides access to the S/VGA palette. All PXIPL functions which operate upon pximage's may be used upon the S/VGA and its palette. The resolution that vga_open was able to obtain from the S/VGA can be deduced from: 

    vgaip->imdim.se.x
    vgaip->imdim.se.y
    vgaip->d.pixies
    vgaip->d.u.i.bitsused
If the S/VGA could not be put into a graphical mode, the *vgaip is set to a NULL pximage with dimension of 0. Similarly, if the video mode does not support a palette, the *palip is set to a NULL pximage with dimension of 0.

The vga_close restores the S/VGA to the mode in effect before use of vga_open. The *vgaip and *palip are set to NULL pximage's, and should not be used thereafter.

Support of Super VGA modes requires that the S/VGA card support the VESA S/VGA BIOS standards. In Super VGA modes, common ''C'' functions such as printf may not be supported by the S/VGA card's BIOS. Characters may be drawn by manipulating the pixels of vgaip, or by use of and similar functions.

The vga_open must not be called before successfully establishing access to the frame grabber, via or similar functions.


Supports


80x86
Real mode DOS and Tenberry (Rational) DOS extender. Requires use of a C++ compiler, although the application program may be ''C''. Currently not available for Borland C/C++.



Returns

The vga_open returns the video mode to which the S/VGA has been set.


Example

An frame grabber's buffer is displayed on the S/VGA. The frame grabber is assumed already opened and an image captured. 

struct  pximage vga;


vga_open(0, 800, 600, 24, 1, &vga, NULL);       // access vga and for 4 and 8 bit
                                                // modes, set the palette
pxio8_vgadisplay(NULL,
        #if XCLIB   // w. XCLIB
          pxd_defineImage(1, 1, 0, 0, -1, -1, "Grey"), // for monochrome image buffers
        //pxd_defineImage(1, 1, 0, 0, -1, -1, "BGR"),  // for color image buffers
        #else       // w. SVOBJ,4MOBJ,XCOBJ
          pxd_defimage(1L, 0, 0, -1, -1),              // for monochrome image buffers
        //pxd_defimagecolor(1L, 0, 0, -1, -1, "BGR"),  // for color image buffers
        #endif
        NULL,                                       // no palette
        vga.d.pixies==3? 8:                         // vga 24 bit? use all bits per pixie
            vga.d.u.i.bitsused==8? 7:               // vga 8 bit? reduce to 7 bits as expected
                       vga.d.u.i.bitsused,          // by palette, else all 4 bits
        'n',                                        // resize w. nearest neighbor
        0,                                          // no extra grey levels
        0,                                          // no ignore odd lines
        &vga,                                       // display here
        NULL, NULL, NULL);                          // no cursor

 

 

 

33. Release Notes



RELEASE NOTES: PXIPL for XCLIB Version 3.0

  1. Fixed Feature. The DLL's Windows Properties reports a version of ''[02.02.20]'' and ''for Win NT/2000/XP''. (16-Mar-2007)

  2. Added Feature: New functions pxipf_pixthresholdcnt and pxirpf_pixthresholdcnt compute the number of pixels above a specified threshold, for float and double data types. (24-Nov-2007)

  3. Added Feature: New functions pxip8_pixrotl, pxip8_pixrotr, pxirp8_pixrotl, and pxirp8_pixrotr, perform left or right rotatation of the pixel value's binary representation. (23-Oct-2015)

  4. Added Feature: New function pxip8_geotranpincushion2 performs pincushion and barrel warping, distortion and correction of an image. (09-Jun-2016)

  5. Added Feature: New function pxip8_pixelstatsbufs computes mean, standard deviation, or variance of corresponding pixels of an image sequence. (14-Dec-2016)

  6. Improved Feature: The pxip8_geotranpincushion2 option for using fifth order polynomial can now include use second and fourth order coefficients, in addition to fifth amd third order coefficients. (09-Jan-2018)

  7. New Feature: The pxio8_pgmgwrite, pxio8_pgmwriteseq, pxio8_pgmwriteseqinit, pxio8_pgmwriteseqadd, pxio8_pgmwriteseqdone, pxio8_pgmread, and pxio8_pgmreadseq functions allow saving and loading images to/from Portable Bit Map, Portable Gray Map, and Portable Pixel Map image file formats. (03-Sep-2018)

  8. Improved Feature: The pxip8_pairadd and pxip8_pairsub now have an option so as to use only one line of the source image, replicated. This allows convenient image nromalization given a one line ''black level''. (30-May-2019)

  9. New Feature: The new pxip8_copyreplicate is similar to pxip8_copyreplic, but also allows re-orienting of the image and decimation instead of replication. (27-Aug-2021)

  10. Improved Feature: The improved pxio8_tifwrite, pxio8_tifread, pxio8_tifwriteseq, pxio8_tifreadseq, pxio8_tifwriteseqinit, pxio8_tifwriteseqadd, and pxio8_tifwriteseqdone now allows reading and writing BigTIFF format files, as well as the original TIFF format. (25-Jul-2022)

  11. New Feature: The new pxio8_fitsreadseq, pxio8_fitswriteseq, pxio8_fitswriteseqinit, pxio8_fitswriteseqadd, and pxio8_fitswriteseqdone now allows creating and reading image sequences in FITS format. (14-Oct-2022)

  12. New Feature: The pxio8_aviread, pxio8_avireadseq, pxio8_aviwriteseq, pxio8_aviwriteseq2, pxio8_aviodmlwriteseq, pxio8_aviwriteseqinit, pxio8_aviodmlwriteseqinit, pxio8_aviwriteseqadd, and pxio8_aviwriteseqdone now support creating and reading AVI files using a ''MJPG'' codec, with lossy JPEG compression. (04-Nov-2022)



RELEASE NOTES: PXIPL for XCLIB Version 2.2

  1. Modified Feature: The the PXIPL DLL files distributed with XCLIB did not have correct, or did not have any, version information shown with the files' properties (such as via the Windows Explorer). Further, the PXIPL version specification, being different than the version specification of the XCLIB with which it works, is confusing. Henceforth, the PXIPL version specification will be identical to that of the XCLIB specification, even tho this means jumping from 
        PXIPL V2.6
    to 
        PXIPL for XCLIB V2.2
    Further, the PXIPLDST.TXT file mistakenly states that it supports XCLIB V2.1 rather than XCLIB V2.2, and limits mention of supported versions of Windows to 95 and NT. (20-Feb-2002).

  2. Added Feature: Functions pxio8_fitswrite and pxio8_fitsread allow saving and loading images in the FITS file format. (01-Apr-2002)

  3. Fixed Feature: The pxio8_DirectXDisplay used with a S/VGA in 32 bit mode and the cursip option returned a PXERNOCOLOR error. (04-Apr-2002).

  4. Added Feature: The pxio8_avireadseq allows loading a sequence of images from an AVI format file. (26-Apr-2002).

  5. Improved Feature: The pxio8_tifwrite, pxio8_tifread, and sequence variations now support image lengths and widths greater than 65535 when used in 32 bit programming environment. (25-Aug-2002).

  6. Improved Feature: The pxio8_aviwriteseq, pxio8_aviwriteseq2, pxio8_avireadseq, pxio8_tifwriteseq, and pxio8_tifreadseq now support image file sizes up to 4 GiByte under 32 bit Windows, instead of 2 GiByte. (04-Nov-2002).

  7. Fixed Feature: The pxio8_binreadseq, with skip2=0 and a file shorter than the image sequence, may read the file into the applicable image buffers correctly, but then write excess data into the following image buffer. (10-Jun-2003).

  8. Added Feature: The new pximage_memmalloc2 and pximage3_memmalloc2 provide a similar result as the existing pximage_memmalloc and pximage3_memmalloc, namely an image buffer along with a pximage, but are much easier to call from non-C/C++ programming environments. The new pximage_setwind and pximage3_setwind allow setting the area of interest window of any pximage or pximage3 without utilizing structures, and are much easier to call from non-C/C++ programming environments. (20-Jun-2003)

  9. Added Feature: The new pxip8_geotranwarp2 is similar to pxip8_geotranwarp, but warps the entire image with a single set of polynomials, rather than partioning the image into quadrilaterals. (20-Jul-2003)

  10. Fixed Feature: Recent versions (prior 3 months) of pxip8_pixthreshold3 and pxirp8_pixthreshold3 produce an error when either invalue or outvalue is NULL. (03-Sep-2003).

  11. Improved Feature: The pxip8_copyinterpolate now supports color pixels, and supports ''ushort'' pixels. (04-Sep-2003).

  12. Improved Feature: The pxio8_avireadseq pxio8_aviwriteseq are now available in all environments, not just Windows. (15-Nov-2003).

  13. Fixed Feature. The pxip8_correlateprof and pxip8_correlatefind may not operate properly with pixel values larger than 255. (15-Dec-2003).

  14. Added Feature: The pxio8_tifwriteseqinit, pxio8_tifwriteseqadd, pxio8_tifwriteseqdone, pxio8_aviwriteseqinit, pxio8_aviwriteseqadd, pxio8_aviwriteseqdone, pxio8_binwriteseqinit, pxio8_binwriteseqadd, and pxio8_binwriteseqdone allow saving an image sequence incrementally, one image at a time, to a single TIFF format, AVI format, or binary format file, respectively. (27-Feb-2004).

  15. Added Feature: The ''struct pximregion'', and the functions that use it, now support rotated rectangles and ellipses, and variations of rectangles and ellipses which utilize floating point parameters instead of integers, allowing for more precise specification of the rectangles or ellipse. (26-Apr-2004).

  16. Improved Feature: The pxio8_print now supports formatting of grey level images for printing on PostScript compatible printers. (01-Jun-2004).

  17. Added Feature: The pxio8_DIBCreate copies an image into a Windows Device Independent Bitmap (DIB) in Windows global memory. (02-Aug-2004).

  18. Improved Feature: The pxio8_aviwriteseqinit, pxio8_aviwriteseqadd, and pxio8_aviwriteseqdone, now allows creating a sequence whose length is not pre-specified, and which may be shorter or longer than specified as the nimages parameter to pxio8_aviwriteseqinit. (29-Dec-2004)

  19. Improved Feature: The pxio8_tifwrite, pxio8_tifread, pxio8_tifwriteseq, pxio8_tifreadseq, and pxio8_tifwriteseqadd now support LZW compression of mono and color images. (30-Jan-2005)

  20. Fixed Feature: The pxio8_aviwriteseqinit and pxio8_aviwriteseqadd do not work correctly with pixels larger than 8 bits. (13-May-2005).

  21. Added Feature: New functions pxio8_aviodmlwriteseqinit and pxio8_aviodmlwriteseq support the AVI 2.0 file format, allowing files larger than 4 GiByte, subject to support by the underlying operating system. (30-Dec-2005).

  22. Fixed Feature: The pxirp8_drawboundary and other region oriented functions, when using an annulus or annulus arc region with certain pathological parameters (e.g. diameter close to 0) may take a very long time to execute and/or may provide incorrect results. (23-May-2006).

  23. Modified Feature: The cntp parameter of pxip8_drawchars3, pxip8_drawchars4, pxip8_drawchars5, pxip8_drawline, pxip8_drawbox, pxip8_drawarrow, pxip8_drawellipse, pxip8_drawellipsesect, pxip8_drawicon, pxirp8_drawboundary, pxip8_drawbezier, pxirp8_drawpath, and pxirp_regionarea has been changed from long to pxim2size_t for consistent sizing under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different name and sign. Similarly, the cntp parameter of pxip8_pixthresholdcnt, pxirp8_pixthresholdcnt, pxip8_morperode, pxip8_morpdilate, pxip8_morpopen, pxip8_morpclose, pxip8_morphitmiss, and pxip8_binmaxisthin has been changed from ulong to pxim2size_t. (02-Sep-2006).

  24. Modified Feature: The skip parameter of pxio8_binread pxio8_bin1read pxio8_binreadseq and pxio8_bin1readseq has been changed from ulong to off_t for proper sizing under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different type name and sign. (16-Oct-2006)

  25. Modified Feature: The count parameter of pxip8_histab, pxip8_histab2, pxip8_histabpair, pxirp8_histab, pxirp8_histab2, and pxirp8_histabpair has been changed from ulong to pxim2size_t for consistent sizing under various 64 bit compilers. The ncount parameter has been changed from uint to size_t. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different type name. Similarly, the countp parameter of pxip8_findpixelmax and pxip8_findpixelmin has been changed from ulong to pxim2size_t. Similarly, the seed parameter of pxip8_noiseadd has been changed from ulong to uint32. Similarly, the map parameter of pxip8_pixmaps, pxip8_pixmapl, pxirp8_pixmaps, and pxirp8_pixmapl has been changed from ushort and ulong to uint16 and uint32, respectively. (18-Oct-2006)

  26. Modified Feature: The ''video time'' parameters used in pxio8_vgawaterfall, pxio8_WaterfallToDevice, and pxio8_GDIWaterfall has been changed from ulong to uint32 for consistent sizing under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different type name. (26-Oct-2006).

  27. Modified Feature: The cn parameter of pxip8_drawchars5 has been changed from int to size_t for ease of use under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers. (04-Feb-2007)

  28. Modified Feature: The cnt parameter of the printfunc of pxio8_print has been changed from uint to size_t for ease of use under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers. (06-Feb-2007)

  29. Modified Feature: The value parameter of pxip8_pixset and pxirp8_pixset has been changed from ulong to uint32 for consistent sizing under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers. (28-Feb-2007)

  30. Modified Feature: The nbadblobs parameter of pxip8_bloblist, pxip8_bloblist3, and pxip8_bloblist2 has been changed from ulong to pxim2size_t for consistent sizing under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers. (28-Feb-2007)

  31. Modified Feature: The pxip8_pixmap, pxip8_pixmaps, pxip8_pixmapl, pxirp8_pixmap, pxirp8_pixmaps, pxirp8_pixmapl, pxip8_findpixel pxip8_normalizespecklemask, and pxirp8_connectregion now require an additional parameter confirming the number of elements of the map provided, allowing improved detection of usage errors. (28-Feb-2007)

  32. The ndata parameter of pxip8_radialmass and pxip8_radialmassf has been changed from int to size_t for ease of use under various 64 bit compilers. Similarly, the nfiduc parameter of pxip8_geotranwarp and pxip8_geotranwarp2 has been changed. Similarly the npoints parameter of pxip_fitellipse has been changed. Similarly the nrslts of pxip8_correlatefind has been changed. Similarly the anblob, firstblob, results, nresults, and nextblob parameters of pxip_particleflow has been changed. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different type name and sign. (28-Feb-2007)

  33. Modified Feature: The nblobs parameter of pxip8_bloblist, pxip8_bloblist3, and pxip8_bloblist2 has been changed from uint to size_t for ease of use under various 64 bit compilers. This should not affect existing 16 or 32 bit programs, and the old and new types are the same size integers, albeit with a different type name. (28-Feb-2007)

  34. Added Feature: New function pxip8_copyconvert allows copying between different data types, such as uchar, ushort, ulong, float, or double. New function pxip8_copyslice allows copying one pixie of each pixel, as an alternative to using the pximage_colorslice filter. (10-Jul-2007)

  35. Added Feature: New functions pxip8_masscenterpow and pxirp8_masscenterpow compute center of mass of N'th power of the pixel value, to reduce the effects of low level but non-zero backgrounds. (17-Jul-2007)

  36. Fixed feature: Function pxip8_copyinterpbilinear does not operate correctly on color pixels when the 0x80 option (i.e. reflection about vertical) is used. (24-Jun-2008)

  37. Fixed feature: Function pxip8_copyinterpnearest does not operate correctly with the 'd' or 'r' option. (18-Jul-2008)

  38. Fixed feature: On 64 bit systems, functions pxip8_geotranwarp2 and pxip_calibxyhv (with order=3) may cause the application to abort. (21-Aug-2008)

  39. Added Feature: New functions pxip8_xlacecolumntoNsection, pxip8_xlaceNsectiontocolumn, pxip8_ilacelinetoNfield, and pxip8_ilaceNfieldtoline are similar to existing functions pxip8_xlacecolumntohalves, pxip8_xlacehalvestocolumn, pxip8_ilacelinetofield, and pxip8_ilacefieldtoline, but generalize from 2 fields or halves to N fields or sections. (15-Jul-2009)

  40. Added Feature: New function pxip8_copycolorconvert allows copying and converting color spaces, as an alternative to using the pximage_colorconverter filter. (04-Nov-2010)

  41. Added Feature: New function pxip8_geotranrotate2 is similar to pxip8_geotranrotate, but also allows incorporates (27-Nov-2010)

  42. New Feature: PXIPL now includes an HTML version of the manual. (01-Nov-2011)



RELEASE NOTES: PXIPL — Version ?.?

  1. Fixed feature: The pxip8_copyskewlr, pxip8_copyskewud, and pxip8_copyreverse did not work properly on color images with pixies larger than 1 byte. (07-Sep-2000).

  2. Fixed feature: The pxio8_tifread and pxio8_tifreadseq did not correctly load TIFF images saved in Motorola byte order with more than 8 bits per pixel. (Note: Images saved by PXIPL were always in Intel byte order, and are not affect by this problem.) (05-Oct-2000).

  3. Modified feature: The pxio8_vgadisplay, pxio8_vgawaterfall, pxio8_GDIDisplay, pxio8_GDIWaterfall, pxio8_DirectXDisplay functions now allow displaying an image in PXHINTRGB or PXHINTRGBX format, avoiding having to explicitly convert such an image to PXHINTBGR. (01-Jan-2001).

  4. Documented feature: Missing documentation for the existing pximage3_memory function has been restored. (22-Jan-2001).

  5. Fixed Feature: The pxip8_patternfiducial, pxip8_patternalign, and pxip8_testpattern did not work properly with the new XCLIB's pxd_defineImage. (23-Jan-2001).

  6. Added feature: Functions pximage_def3from2 and pximage_def2from3 allow creating a 3-D reference to a 2-D image, or a 2-D reference to a ''slice'' of a 3-D image, respectively. (06-Feb-2001).

  7. Improved Feature: The struct pximfileinfo has been enlarged so that pxio8_fileinfo can return the image's aspect ratio in the same format as used in a pximage. Programs which use struct pximfileinfo must be recompiled before using newer DLL's. (13-Feb-2001).

  8. New Feature: The pxip8_drawchars, pxip8_drawchars3, and pxip8_drawchars5 allows drawing text using any supplied Windows font. (26-Feb-2001).

  9. New Feature: The pxip8_findpixelmin and pxip8_findpixelmax allow finding the minimum or maximum pixel value in an AOI.

  10. Improved Feature: The pxip8_copyinterpnearest, pxio8_vgadisplay, pxio8_GDIDisplay, and pxio8_DirectXDisplay now provide a ''near neighbor deflicker'' interpolation which reduces display artifacts due to the image being interlaced (horizontally and/or vertically). (05-May-2001).

  11. Fixed Feature: The pxio8_bmpread would cause a memory protection fault if the specified file name does not exit. (16-Jul-2001).

  12. Fixed Feature: The pxip8_NxNdynthreshold may cause a memory protection fault under Windows NT. (19-Jul-2001).

  13. Improved Feature: The pxio8_vgadisplay, pxio8_vgawaterfall, pxio8_GDIDisplay, pxio8_GDIWaterfall, and pxio8_DirectXDisplay now allow the optional palette to be applied at the image's bit depth instead of at the display's bit depth. The distinction is only important with images with more than 8 bits per pixel component; the former option allows using the palette to view the pixel's low order bits, the latter option is quicker.

  14. New version released in conjunction with XCLIB V2.2, adding support for Windows XP. (03-Dec-2001).

  15. Improved Feature: The pxio8_vgadisplay, pxio8_GDIDisplay, and pxio8_DirectXDisplay now allow rendering of only odd (or even) image lines into only odd (or even) S/VGA lines, allowing interlaced rendering of an interlaced image. (08-Jan-2002).

  16. Added Feature: The pxio8_DrawDibDisplay allows rendering of an image via the Video for Windows API. This API may be slightly slower on some computers than other API's, but may reduce the appearance of ''band'' artifacts due to the S/VGA and PIXCI® frame grabber being asynchronous. (21-Jan-2002).

  17. Fixed Feature: Images with highly saturated pixels loaded with pxio8_jpegread may show color speckles. (12-Feb-2002).

  18. New Feature: The pxip8_histabpair and pxirp8_histabpair allow computation of a histogram of signed differences of corresponding pixels of two images or image regions. (08-Oct-2002).

  19. Improved Feature: The pxio8_tifwriteseq and pxio8_tifwriteseq under Windows 95/98/ME/NT/2000/XP now support file sizes up to 4 GiByte, rather than 2 GiByte. (29-Oct-2002).



RELEASE NOTES: PXIPL — Version 2.6

  1. Release for use with XCLIB V2.1, supporting 32 bit extended DOS and Windows 95/98/NT/2000 32 bit environments. (15-Aug-2000).

  2. Modified feature: A fourth and new parameter has been added to pxip_fractedges allowing threshold the edge strengths before being ordered by the mode. Existing programs may simply add a parameter of 0.

  3. New feature: Functions pxip8_drawchars3 and pxip8_drawchars4 allow drawing text on an angle, drawing with options provided with other graphics style functions, and drawing with user supplied fonts.

  4. Modified feature: Function pxio8_GDIDisplay now allows drawing images on a VGA which is in 16 bits per pixel mode. New function pxio8_GDIDirectXDisplay allows drawing images on Direct Draw ''surfaces''.

  5. Modified feature: A thickness parameter has been added to pxip8_drawline, pxip8_drawbox, pxip8_drawellipse, pxip8_drawbezier, pxirp8_drawpath, pxirp8_drawboundary, and pxip8_drawarrow. Existing code should simply insert a value of 0 following the dotspacing parameter.

  6. New feature: Function pxip8_drawellipsesect allows drawing sections, or arcs, of a rotated ellipse.

  7. New feature: Region types of annulus, arc of annulus, and rectangular frame have been added.

  8. New feature: Function pxio8_aviwriteseq allows writing a sequence of images to a Windows Video (.avi) format file.

  9. New feature: Functions pxip8_radialmass and pxip8_radialmassf compute a table of the sum of pixels values versus their distance from an origin.

  10. New feature: Function pxip8_noiseadd adds psuedo-random noise with a variety of distributions to an image. The pxip8_dithernormal is deprecated; new applications should use pxip8_noiseadd.

  11. Modified feature: Function pxip8_spatialquantize now supports color images.

  12. Modified feature: A fourth and new parameter has been added to pxio8_fileinfo. Existing programs may simply add a parameter of 0. (04-Oct-1999).

  13. New feature: Functions pxio8_jpegread and pxio8_jpegwrite allows writing and reading images in JPEG/JFIF format with selectable quality and compression. (04-Oct-1999).

  14. New feature: Region type of window has been added. Unlike the existing type of ''PXIMREGWIND'', a window type is clipped by the pximage.wind, and may be partly or entirely out of the image's bounds. (22-Nov-1999).

  15. New feature: Region types of negative ellipse, negative rectangle, negative polygon, negative path, negative annulus, negative annulus arc, negative frame, and negative window have been added which is the complement of the underlying region's area, bounded by the pximage.wind. (22-Nov-1999).

  16. New feature: Functions pxip8_xlacecolumntohalves and pxip8_xlacehalvestocolumn exchange pixels on each line, from odd and even locations to left-half and right half locations; a horizontal analog to pxip8_ilacelinetofield and pxip8_ilacefieldtoline. (22-Nov-1999).

  17. New function pxip8_recursiveaverage implements recursive averaging of corresponding pixels. (26-Nov-1999).

  18. New functions pxirp_regionexport and pxirp_regionimport allow exporting and importing the pximregion structure. (22-Dec-1999).

  19. The pxip8_geotranrotate did not work correctly on color images, interchanging colors. (22-Dec-1999).

  20. When used with color images, pxio8_tgawrite may swap the red and blue pixel components. (17-Jan-2000).

  21. Modified feature: The pxip8_integratebufs and pxip8_averagebufs now support color images. (29-Feb-2000).

  22. Manual Correction: The pxip8_drawellipse and pxip8_drawellipsesect were described as accepting x and y radius parameters. The functions actually used the parameters as the x and y diameter. (10-Jul-2000).

  23. Fixed feature: The pxip8_spatialquantize produced incorrect results for color images for the rightmost and/or bottom-most bin, where rightmost and/or bottommost bin was not a full xsize and/or ysize blocksize.

  24. Fixed feature. The pxirp_regionshapef produced invalid results or page faults for regions of type PXIMREGWINDOW; an uncommon, but legal, shape due to its trivial analysis. (14-Aug-2000).



RELEASE NOTES: PXIPL — Version 2.5

  1. Manual update: A new second and third parameter has inserted for pxio8_vgawaterfall, pxio8_WaterfallToDevice, and pxio8_GDIWaterfall, allowing specification of alternate function to indicate video timing. Existing programs may simply define: 
        ulong _cfunfcc vbtime(void *unused)
    {
        return(pxdrv_xvbtime());
    }
    and use ''vbtime'' and ''NULL'' as the second and third parameters.

  2. New function pxip_particleflow tracks multiple particles across a sequence of images.

  3. Functions pxio8_tiffwrite, pxio8_tiffread, pxio8_tiffparm, pxio8_tiffparmr, and pxio8_tiffreadrsz have been superseded by of pxio8_tifwrite, pxio8_tifread, and pxio8_fileinfo which offer improved support for color images, palettes whose size may not be 256x3 8 bit entries, provide additional resizing options, and Pack Bits compression for pixels with more than 1 bit. The old style functions are available by appending ''_old'' to the name, e.g. ''pxio8_tiffread_old''.

    New functions pxio8_tifwriteseq and pxio8_tifreadseq provide convenient saving and loading of image sequences to/from a single TIFF file.

    New functions pxio8_pcxwrite and pxio8_tgawrite allow saving an image in PCX and Targa formats, respectively.

  4. A tenth parameter, currently reserved, has been added to pxip8_drawicon; a value of NULL must be used.

  5. Under DOS and under Tenberry (Rational) DOS extender, the new vga_open and vga_close support access to a S/VGA via the standard pximage methods. The vga_ functions are available for Microsoft and Watcom C/C++ compilers, but currently not available for Borland C. New functions pxio8_vgadisplay, pxio8_vgacoord, pxio8_vgacursor, and pxio8_vgawaterfall provide convenient, and optimized, routines to display images, with optional palette or lookup table modifications, with optional nondestructive cursor, onto the S/VGA.

    Under Windows, the pxio8_CopyToDevice, pxio8_CopyToDeviceCoord, and pxio8_WaterfallToDevice have been superseded by pxio8_GDIDisplay, pxio8_GDICoord, pxio8_GDICursor, and pxio8_GDIWaterfall. The new functions support palette or lookup table modifications, improved API efficiency for cursor drawing, and explicit support for erasing and redrawing a cursor over an already displayed image. The previous functions remain available.

  6. For TIFF format files, pxio8_fileinfo would always set tiff.resolutionunits to 0. (24-Apr-1999).

  7. Many PXIPL functions now support processing of color images.

  8. The pxio8_bmpread and pxio8_tifread do not work correctly on images with palettes, where the number pixel bits resulting from the palette was no the log of the number of palette entries (e.g. a palette of 8 bit values indexed by 8 bits is ok, a palette of 8 bit values indexed by 1 or 4 bits is not ok). (05-Aug-1999).



RELEASE NOTES: PXIPL — Version 2.2

  1. Most PXIPL functions now support processing 10, 12, 14 or 16 bits per pixel images.

  2. To allow shared use of PXIPL functions in a multi-tasking environment, support for premature termination has been changed. The previous pxip_breakfunc function, which set a termination function address, is no longer provided. Instead, each PXIPL function which supports premature termination now requires an additional parameter (always the first parameter), which is the address of the address of the termination predicate function.

    Old code which doesn't require the premature termination feature can be easily converted by adding a NULL as a first parameter.

  3. Taking advantage of the move to 32 bit code, many PXIPL functions are now faster, albeit achieved at the expense of larger code.

  4. The name of PXIPL's master include file has been changed from PXIP8.H to PXIPL.H, to be more representative of its function. To allow compilation of old programs without change, PXIP8.H is now a stub which includes PXIPL.H.

  5. A new structured and object oriented method of accessing image data uses functions associated with the pximage structure (C++ people would term it a virtual class, but the implementation is also available in C). Among other advantages, the PXIPL functions, which accept pximage references, can now be led into operating upon images stored in PC memory, as well as frame grabber memory, and support pixels larger than 8 bits.

  6. The pxio8_CopyToDevice and pxio8_WaterfallToDevice now have a second unused parameter following the first, which should also be NULL.

  7. The pxirp8_connectregion is now, approximately, two times faster. A new option, to assume convex shapes (such as for blobs), allows pxirp8_connectregion to run, additionally, two times faster.

  8. New functions pxip8_findpixelv and pxirp8_connectregionv are similar to pxip8_findpixel and pxirp8_connectregion, respectively, but allow specifying a comparison and value (such as ''>=120'') rather than specifying a table and bit test. The new functions avoid the user having to set up a table, and are slightly faster than the table versions.

  9. New functions pxip8_pixthreshold2 and pxirp8_pixthreshold2 provide an alternate pixel thresholding, avoiding, in some applications, having to use pxip8_pixthreshold and pxirp8_pixthreshold twice.

  10. New functions pxip8_normalizelinemean and pxip8_normalizecolmmean normalize lines or columns of pixels based upon each line's or column's mean.

  11. The pxio8_print now supports printing on the Alden 9315 Continuous Tone (i.e. grey level) printers.

  12. The pxip8_normalizespecklemask is clarified to use horizontally adjacent pixels, is improved to correct with a next to adjacent good pixel, and is faster.

  13. The pxip8_ilacepairswap now allows swapping pairs of columns, as well as lines.

  14. The pxio8_hexrite now allow specifying a character to be written after each line of pixels. The pxio8_hexread now ignores non-hexadecimal characters, except when occurring within the group of characters representing a pixel's value (which causes an error).

  15. The pxip8_spatialquantize, when used in shrink mode, now fills the image area beyond the shrunken image with pixel value 0.

  16. To accommodate 16 bit pixels, the value element of the pxip8histperc structure is now ''uint'', rather than ''uchar''.

  17. The pxirp8_paintregion, pxip8_pclfontdraw, and pxip8_drawchars have been modified; their ''background'' parameter was both a value and type code. To allow a greater range of pixel values, a separate ''groundtype'' parameter has been added (preceding the ''background'' parameter). Also, their background and foreground parameters are now uint arrays (of dimension 1, for grey levels). Existing programs may be easily converted by listing the currently used value for ''background'' twice (i.e. using the same parameter for ''groundtype''), and using the ''&'' (address of) on the background and foreground uint variables.

  18. The pxio8_fmbwrite, pxio8_fmbread, pxvib_gotrig, pxvib_gotrig2, pxvib_gotrigseq, pxvib_gosequence, pxvib_gosequencesh, pxip8_copyintoradrs, and pxip8_copyfromradrs are no longer part of the PXIPL, but instead are included with SVOBJ or 4MOBJ. For the sake of consistency, the pxvib_gotrig, pxvib_gotrig2, pxvib_gotrigseq, pxvib_gosequence, and pxvib_gosequencesh functions have been modified to accept the same style of premature termination parameter as added to other PXIP functions.

  19. The pxip8_fft, pxip8_ffti, pxip8_fftlogmag, pxip8_fftlmagscale, and pxip8_fftfilterz have been improved so that the complex coefficients can be stored in any suitable pximage (see above), rather than being limited to frame grabber memory. The old style functions are available by appending ''_old'' to the name, e.g. ''pxip8_fft_old''; however, the _old functions no longer support premature termination.

    The new pxip8_fftsetcimage allows convenient access to the complex coefficients.

  20. The pxip8_averagebufs and pxip8_integratebufs have been improved to allow operation on any 3-d pximage (see above), rather than being limited to frame grabber memory. The old style functions are available by appending ''_old'' to the name, e.g. ''pxip8_averagebufs_old''; however, the _old functions no longer support premature termination.

  21. The pxip8_momentsf and pxirp8_momentsf now accept two distinct maprefp parameters; one for the mapzifunc and the second for the mapxyhvfunc. Allowing distinct mapzifunc simplifies the user provided mapzifunc and mapxyhvfunc functions.

  22. The pxip8_drawline, pxip8_drawbox, pxip8_drawarrow, pxip8_drawellipse, pxip8_drawbezier, pxirp8_drawboundary, and pxirp8_drawpath have been improved so that in modes 'b' and 'R' pixels are exchanged or written to a second pximage, rather than a uchar buffer. This supports non-uchar pixels, and prevents overwriting the uchar buffer. Also, the functions are improved to allow ''returning'' a ''long'' pixel count. The old style functions are available by appending ''_old'' to the name, e.g. ''pxip8_drawline_old''.

  23. The PXIPL library now supports the TI TMS320C40 C Compiler, for use with the 4MEG VIDEO and COC40. Functions which save/load images to/from disk, or display images on the VGA are, of course, not supported.

    The most popular functions are also available in ''bound'' versions, host callable routines which automatically load and execute a TMS320C40 image processing program to perform the specified operation. The bound routines can be used without the TMS320C40 C compiler.

  24. New function pxirp8_followregionv follows an image region's perimeter, and encodes the path into a pximregion.

  25. New function pxip8_correlateprof performs a correlation of a mask on an image, creating an image with a correlation profile.

  26. New function pxip8_seqtile allows reducing a sequence of images into a single image.



RELEASE NOTES: PXIPL — Version 2.0

  1. Release for use with SVOBJ V7.0 and 4MOBJ V3.0, supporting 16 bit DOS, 32 bit extended DOS, and 16 bit Windows environments.

  2. New function pxio8_print provides image printing on Hewlett-Packard and other popular printers, with the same features as is found in the 4MIP/SVIP Image Printing menus.

  3. New function pxio8_CopyToDevice copies an image buffer or area of interest to a Windows device context (i.e. displays an image on the (S)VGA). New function pxio8_WaterfallToDevice displays a sequence of lines, taken from a sequence of video fields, in waterfall fashion on a Windows device context.

  4. The pxio8_tiffwrite, pxio8_tiffread, and pxio8_tiffreadrsz now support the same compression options as provided in 4MIP/SVIP.

  5. The pxip8_geotranrotate is now, approximately, two times faster.

  6. A new pxip8_smptevitcdecode option allows reporting garbled VITC codes.

  7. The subfile parameter of pxio8_tiffwrite, pxio8_tiffread, pxio8_tiffparm, and pxio8_tiffreadrsz is now a ''long'' instead of an ''int''. A copyright notice, as per V6 of the TIFF specification, can now be saved via pxio8_tiffwrite and observed via pxio8_tiffparm.

  8. The function modifier of library functions has changed. Instead of the default ''_cdecl'', functions are now defined to be type ''_cfunfcc'', ''_cfunvcc'', ''_cfunacc''. These types are predefined, and vary in different environments (e.g. DOS, Windows, and various compilers). This allows, for example, the Windows DLL to be composed of _PASCALL functions, or callback functions to be more efficient. As the include files declare all library functions appropriately, the change is transparent except for users of library functions which invoke callback functions; the function called back must be of type ''_cfunfcc''. The affected functions are: pxip_breakfunc, pxvib_gosequence, pxvib_gosequencesh, pxvib_gotrig, pxvib_gotrig2, pxip8_momentsf, pxirp8_momentsf, pxip8_histstatf, and pxirp_regionshapef.

  9. New function pxip8_pairor does Inclusive-OR of corresponding pixels of two images.

  10. New function pxirp_xlatetopath translates a region into a path along the region's outer boundary.

  11. Additional modes for pxip8_pairsub allow doing operations in both forms: 
            B <- B-A
and     B <- A-B
    without having to copy one or more image buffers.

  12. The pxip_fractedges now allows specifying a priority ordering for multiple edges of the same strength, or reporting all edges without ordering.

  13. The ''(*abort)(void)'' callback function to pxvib_gosequence, pxvib_gosequencesh, pxvib_gotrig, pxvib_gotrig2, and pxvib_gotrigseq is now ''(*abort)(void*)'', which is called with an ''abortrefp'' as passed to the ''pxvib_'' functions; allowing the called back function to receive an arbitrary object, state, or stack frame reference.



RELEASE NOTES: PXIPL — Version 1.8

  1. Release for use with SVOBJ V6.8 and 4MOBJ V2.8, 2.8.1.

  2. As object code, for use with Microsoft C V7.0 and V8.0 (Visual C V1.0) or Borland C++ V3.1 in M and L models for DOS 3.0+ and for Windows V3.0+. Also provided as a Windows compatible DLL.

  3. New function pxip8_normalizebackground performs ''flat-field'' background normalization.

  4. New function pxip_fractedges performs subpixel accuracy edge measurements.

  5. Functions pxio8_tiffwrite, pxio8_tiffreadrsz, pxio8_tiffread, pxio8_tiffparm, pxio8_fmbwrite, pxio8_fmbread, pxio8_binread, pxio8_binwrite, pxio8_hexread, pxio8_hexwrite, pxio8_bin1read, and pxio8_bin1write are now more network ''friendly'', opening files in a mode which allows shared reading and exclusive writing, rather than the default DOS ''compatibility'' mode.

  6. Function pxip8_spatialquantize now allows summing of blocks of pixels, as an alternative to averaging blocks of pixels.

  7. Functions pxip8_fft and pxip8_ffti, when used on images with power of 2 dimensions, are now approximately twice as fast. The fft functions now require approximately 50% less image memory space for the frequency domain's complex coefficients.

  8. Function pxip8_averagebufs now allows averaging a decrementing sequence of buffers, placing the result in the highest buffer of the sequence.

  9. New function pxip8_integratebufs allows integrating a sequence of buffers, averaging a sequence of buffers, or weighted results between integration and averaging.

  10. Function pxip8_findpixel now allows searching for pixels in the up, down, left, or right directions, in addition to the previous left to right, top to bottom scan.

  11. Functions pxip8_drawicon, pxip8_drawbezier, pxip8_drawiconhit, pxip8_drawarrow, pxip8_drawellipse, pxirp8_drawpath, pxirp8_drawboundary, pxip8_drawline, and pxip8_drawbox now support an XOR mode of pixel modification.

  12. New mode for pxip8_pairsub permits subtraction with the difference divided by 2 and added to 128; producing a more visually useful difference image.

  13. New functions pxip8_pixthresholdcnt and pxirp8_pixthresholdcnt count the number of pixels that are greater than or equal to a threshold, and are faster than obtaining similar information from pxip8_histab or pxirp8_histab.

  14. New function pxirp_regionarea provides the pixel area of an image region, faster than functions such as pxirp_regionshapef or pxirp8_moments which also compute other information.

  15. New function pxip8_patterngaussian draws 2-D Gaussian patterns.

  16. The pxip8_masscenter and pxirp8_masscenter are now 25 to 50% faster.

  17. The pxirp8_connectregion is now 2 to 4 times faster when used with video turned off. Various ''pxirp8_'' functions, when used with a non-simple region (such as a path which intersects itself) are also faster.

  18. New functions pxip8_morperode3x3 and pxip8_morpdilate3x3 perform erosion and dilation with 3x3 structure elements. These functions are faster than pxip8_morperode and pxip8_morpdilate, but don't allow arbitrary structure elements and don't report result counts.

  19. The mass parameter of pxip8_masscenter and pxirp8_masscenter has been changed from a 32 bit integer to a double float, to prevent overflow of the computed mass of large images.

  20. The pximregion structure has been simplified. The various regions that define a private member of structure for start or origin xy coordinate, now use a common origin member of structure. Thus for rectangles, ellipses, or paths change 
    instance.region.rectangle.origin
instance.region.ellipse.origin
instance.region.path.start
    all to 
    instance.origin
    The polygon region vertices are now relative to the origin; old code may be simply adapted with: 
    instance.origin.x = 0;
instance.origin.y = 0;
    These changes promote easier manipulation of regions as an object; the position can be changed by a common method.

    A new scan list type, PXIMREGSCANLISTB, defines a scan list which is relative to the instance.origin, and which may be clipped by the instance.image.wind. The original PXIMREGSCANLIST is not changed; defined in absolute coordinates, and assumed not clipped.

  21. New function pxvib_gotrig2 is similar to pxvib_gotrig, but provides an option of not waiting for a trigger signal.

  22. The previous method of hooking an abort option into image processing functions, by (re)defining the dosbroke function, has been changed. Instead, pxip_setbrokefunc should be invoked with a pointer to the desired predicate function. This change is necessary to support DLL versions of the library.

    Existing programs which use the dosbroke feature can be easily converted by invoking: 

    pxip_breakfunc(dosbroke, NULL, NULL, NULL);
    once, before any image processing functions are used.



RELEASE NOTES: PXIPL — Version 1.7

  1. Release for use with SVOBJ V6.7 and 4MOBJ V2.7.

  2. For use with Microsoft C V6.00a and V7.00 or Borland C++ V2.0 and V3.1 in M and L models for DOS 3.0+. For use with Microsoft C V7.00 or Borland C++ V3.1 for Windows V3.0+.

  3. New function pxip8_copyinterpnearest performs image resizing by nearest neighbor interpolation, and is 2 to 6 times faster than pxip8_copyinterpbilinear.

  4. New function pxvib_gotrig allows capturing an image buffer in response to an external trigger. The pxvib_gotrig can also be used to trigger an external device, generating a trigger in sync with video timing, and then capturing an image buffer.

  5. New function pxio8_tiffreadrsz allows loading and resizing a TIFF image to fit the image buffer (or window), rather than being cropped. While a TIFF image smaller than an image buffer could always be loaded and later expanded, the new feature allows loading a TIFF image which is larger than an image buffer.

  6. New function pxirp8_moments computes moments, central moments, scale invariant moments, rotation invariant moments, and center of mass of a nonrectangular image region.

  7. The pxip8_drawchars now allows drawing characters by adding a grey level value to each pixel, in addition to the previous mode of setting each pixel to a grey level. The new mode provides easier erasure of characters.

  8. New function pxip8_histfit modifies an image so as to have a uniform histogram, or a histogram of a specified shape.

  9. New function pxip8_histstatf computes histogram statistics using an arbitrary interpretation of pixel values, rather than the pixel's binary value. The pxip8histstat.sum has been changed from type ''ulong'' to type ''double'' to allow supporting pxip8_histstatf.

  10. New function pxip8_momentsf computes moments using an arbitrary interpretation of pixel values, and an arbitrary interpretation of pixel coordinates. New function pxirp8_momentsf is similar to pxip8_momentsf, but also allows use of a nonrectangular image region.

  11. New function pxip8_smptevitcdecode decodes SMPTE Vertical Interval Time Code information stored in an image buffer.

  12. File pxmp.h is now effectively included by pxip8.h. The pxmp.h, previously required for use of pxio8_ and other functions, should no longer be included.

  13. Functions which read or wrote files previously returned a PXERDOSIO code to indicate any file I/O error. FILE I/O errors are now differentiated, with the applicable functions returning a) PXERNOFILE when a file to be read can't be found, b) PXERNEWFILE when a file can't be created, or c) PXERDOSIO for other DOS I/O problems such as insufficient disk space while writing or bad media.

  14. New function pxip8_copyreplic performs image enlargement (zoom) by pixel replication.

  15. New function pxip8_geotranrotate performs image warping as defined by two corresponding sets of fiducial coordinates.

  16. New function pxip8_xlaceshuffle and pxip8_xlaceunshuffle perform pixel shuffling within pairs of lines, somewhat analogous to the shuffling of lines performed by pxip8_ilacelinetofield or pxip8_ilacefieldtoline.

  17. Functions pxip8_drawarrow, pxip8_drawbezier, pxip8_drawellipse, pxip8_drawline, pxip8_drawbox, pxirp8_drawboundary, and pxirp8_drawpath now offer modes 'R' and 0, in addition to previous modes '+', 's', and 'b'. Mode 'R' allows reading pixels under the curve, mode 0 returns the number of pixels that would be read or modified by the other modes.

  18. Edge detection functions pxip8_3x3sobel pxip8_3x3kirsch pxip8_2x2roberts and pxip8_3x3sobela when used in any mode except mode=1, now set boundary pixels to 0, indicating no edge, instead of duplicating the nearest neighbor. In mode=1, unsharp masking, boundary pixels are still set to the nearest neighbor's value. Similarly, pxip8_NxNconvolve and pxip8_NxNconvolvef when used with modes and coefficients which represent edge detection, now set boundary pixels to 0 instead of duplicating the nearest neighbor.

  19. New function pxirp_regionshape provides shape statistics describing nonrectangular image regions, such as width, height, major axis length and angle, etc.

  20. Improved handling of nonrectangular image regions defined as PXIMREGPATH allows paths in which the border overlaps or crosses itself.

  21. New function pxip8_copyexchange exchanges the content of two image buffers, without requiring a third image buffer, or a file, for temporary storage.

  22. New functions pxip_calibxyhv, pxip_calibxyhvdone, pxip_calibzi, pxip_calibzidone, pxip_calibzimap, pxip_calibxyhvmap, and pxip_calibhvxymap support spatial and intensity calibration, mapping X, Y coordinates into user-defined H, V coordinates, and mapping pixel values into arbitrary intensity or density units.


RELEASE NOTES: PXIPL — Version 1.6

  1. Release for use with SVOBJ V6.6 and 4MOBJ V2.6.

  2. For use with Microsoft C V6.00a or Borland C++ V2.0, in M and L models, for DOS V3.0+ or Windows V3.0 environments.

  3. New function pxip8_drawbezier draws curves defined by Bezier polynomials, of up to 10'th order. New function pxip8_drawellipse draws an ellipse of selectable width, height, and rotation.

  4. New function pxip8_copyskewlr skews an image left and right, new function pxip8_copyskewud skews an image up and down. These functions approximate the effect of a small image rotation, but are significantly quicker than rotation.

  5. A new series of functions allows operations on nonrectangular image regions. New functions pxirp8_histab, pxirp8_pixmap, pxirp8_pixand, pxirp8_pixor, pxirp8_pixxor, pxirp8_pixneg, pxirp8_pixadd, pxirp8_pixscale, pxirp8_pixthreshold, pxirp8_pixcontrast, pxirp8_pixcontrastperc, pxirp8_pixset, pxirp8_masscenter, pxirp8_binmasscenter, and pxirp8_copy respectively compute histogram, map pixels via lookup table, AND pixels w. constant, OR pixels w. constant, XOR pixels w. constant, complement pixels, add constant to pixels, multiply pixels with constant, threshold of pixels, contrast modify pixels, contrast modify pixels as per histogram percentiles, set pixels to constant, compute center of mass, compute binary center of mass, and copy pixels. New functions pxirp_xlaterecttopoly, pxirp_xlatetoscanlist, pxirp8_connectregion and pxirp_regionbounds perform utility operations on definitions of image regions. New function pxirp8_drawboundary draws region boundaries. New function pxirp8_paintregion allows painting and filling of image regions, with selectable two-tone patterns. New functions pxirp8_drawpath, pxirp_pathcreate, pxirp_pathextend, and pxirp_pathcompress support regions defined by arbitrary paths.

  6. New functions pxip8_pcfontload, pxip8_pcfontdraw, pxip8_pcfontinfo, pxip8_pcfontcinfo, and pxip8_pcfontunload allow drawing characters in an image, with fonts defined in H-P PCL (LaserJet II) compatible font files.

  7. New functions pxip8_pairprod and pxip8_pairratio respectively compute the product and compute the ratio, of corresponding pixels of a pair of images.

  8. New function pxip8_moments computes moments, central moments, scale invariant moments, rotation invariant moments, and center of mass of an image.

  9. The pxip8_copyinterpbilinear function now allows 90 degree rotations and mirror image flips. Setting the added fourth parameter to 0 provides compatibility with the previous version of the function.

  10. New function pxip8_drawarrow draws an arrow of specified length and angle, with selectable head and tail arrow length and angle, all corrected for aspect ratio to maintain consistent appearance regardless of rotation.

  11. Function pxip8_geotranrotate is now 3 to 8 times faster than the previous version when used with video on.

  12. New function pxip8_NxNconvolvef performs NxN convolutions using floating point coefficients.

  13. New function pxip8_findpixel searches for specified pixel values. Combined with pxirp8_connectregion, the two functions can be used to search for and quantify image ''blobs''.

  14. New functions pxip8_bloblist and pxip8_bloblist2 provide a simpler method of searching for, and listing, blobs in an image.

  15. An added mode parameter to pxip8_pixadd allows selecting bounded or modulo arithmetic. Use of mode=2 provides the same effect as the previous version.

  16. The pxip8_drawiconinit now requires that the initial pixblt parameter be *NULL, the pxip8_drawiconfree now requires the pixblt to be ** rather than *, so that it can set pixblt to be *NULL. The modifications promote safer and more robust malloc'ed memory handling.

  17. Reading and writing TIFF files is now 2 to 6 times faster. An added stripsize parameter to pxio8_tiffwrite aids import of TIFF files into other programs which do not support standard TIFF strip sizes. The stripsize should be 0 for compatibility with the previous version, forcing use of the strip size recommended by the TIFF specification.

  18. New functions pxip8_3x3ranklow and pxip8_3x3rankhigh perform high and low rank filtering, grey level analogs to the morphological erosion and dilation operations.

  19. New function pxip8_normalizeintensity corrects images which should exhibit a uniform intensity of background, but exhibit shading effects due to nonuniform illumination.



RELEASE NOTES: PXIPL — Version 1.5

  1. Release for use with SVDRV V6.5 and 4MDRV V2.5.

  2. Compiled under Microsoft C V5.1, M model and L model.

  3. New functions pxvib_gosequence and pxvib_gosequencesh support acquisition and display of sequences of image buffers.

  4. New functions pxip8_morperode, pxip8_morpdilate, pxip8_morpopen, pxip8_morpclose, pxip8_morphitmiss and pxip8_binmaxisthin provide morphological and thinning operations.

  5. New function pxip8_copyinterpbilinear provides bilinear interpolation which is up to an order of magnitude faster than pxip8_copyinterpolate. The pxip8_copyinterpolate remains the preferred interpolation when the image size (either horizontal or vertical) is being reduced by more than a factor of 2.

  6. New functions pxip8_ilacelinetofield and pxip8_ilacefieldtoline convert interlaced images stored as consecutive lines to consecutive fields, or vice versa. New function pxip8_ilacepairave eliminates interlace flicker, at the expense of resolution, by averaging corresponding pixels of each odd/even line pair together. New function pxip8_ilacemodsingular reduces interlace flicker caused by fine line graphics, while minimizing the loss of resolution. New function pxip8_ilacepairswap is a utility to swap the odd/even lines.

  7. New functions pxip8_copyintoradrs and pxip8_copyfromradrs perform copying from image buffers to raw image memory addresses. Typical use is copying images before or after image memory has been repartitioned by a change of video resolution.

  8. New function pxip8_copyreverse performs left/right and/or top/bottom reversals of an image. New function pxip8_copyshift shifts an image left/right and/or up/down.

  9. New functions pxip8_pixset set pixels to a constant value, and pxip8_pixadd adds a constant value to pixels.

  10. All functions with names of the form pxip8_line*, which were previously invoked by specifying the pxip8_line* name as an parameter to pxi8_nbyn, have been renamed and are now invoked directly. The affected functions are: 
    Old Name                    New Name
-------------------------------------------------
pxip8_line3kirsch           pxip8_3x3kirsch
pxip8_line2roberts          pxip8_2x2roberts
pxip8_line3sobel            pxip8_3x3sobel
pxip8_line3ksrthin          pxip8_3x3ksrthin
pxip8_line3median           pxip8_3x3median
pxip8_line3medianw          pxip8_3x3medianw
pxip8_line3binmedian        pxip8_3x3binmedian
pxip8_line3lowpass          pxip8_3x3lowpass
pxip8_line3lowpassmear      pxip8_3x3lowpassmear
pxip8_linedynthreshold      pxip8_NxNdynthreshold
pxip8_lineconvolve          pxip8_NxNconvolve
    Use and effect of the new and old functions are identical (with additional enhancements to pxip8_NxNconvolve, pxip8_3x3kirsch, pxip8_2x2roberts, and pxip8_3x3sobel, see below) but with simplification of the parameters; the updated documentation should be consulted. This change reduces confusion in proper invocation of these operations, and promotes consistency among all library functions.

  11. Additional NxN convolution parameter for pxip8_NxNconvolve, allows specifying an offset to be added to the sum of products before division. A second parameter allows specifying the divisor; or use of the standard ''sum of coefficients''. Both parameters should be 0 for compatibility with previous versions.

  12. Additional functions to perform special cases of 3x3 convolutions are added. The pxip8_3x3lowpassf performs a low pass filter, or average, with fixed mask coefficients. The pxip8_3x3sharpenl performs image sharpening, or high pass filter, using laplacian mask coefficients.

  13. The pxip8_3x3kirsch, pxip8_2x2roberts, and pxip8_3x3sobel accept an additional mode, assigning the unscaled magnitude to the result image. New function pxip8_3x3sobela performs Sobel operations using absolute values, which is quicker than the pxip8_3x3sobel which performs root-mean-square.

  14. New function pxip8_geotranrotate performs image rotation about an arbitrary origin, including correction for aspect ratio.

  15. Added pxip8_NxNcontrastinvert to perform inverse contrast ratio mapping.

  16. New functions pxip8_fft, pxip8_ffti, pxip8_fftlogmag, pxip8_fftmagscale, and pxip8_fftfilterz perform Discrete Fourier Transform (and FFT) image processing operations, conversions between spatial and frequency domains, display of a magnitude plot of the frequency domain, root and Gaussian filters, and filtering of the frequency domain by scaling of complex coefficients. A math coprocessor is strongly recommended.

  17. New function pxip8_drawicon draws cursors and arbitrary bitmap defined icons into an image. New lower level functions pxip8_drawiconinit, pxip8_drawiconhit, pxip8_drawiconhitr, and pxip8_drawiconfree which execute various phases of pxip8_drawicon are also available.

  18. Modified pxip8_drawline to clip line segments in reference to a rectangular area of interest. New function pxip8_drawbox draws rectangular boxes in an image, generally faster than four invocations of pxip8_drawline.

  19. New functions pxio8_binread and pxio8_binwrite load and save an image area of interest to/from a file in X/Y format as 1 pixel per byte. New functions pxio8_bin1read and pxio8_bin1write load and save an image in X/Y format as 1 pixel per bit. New functions pxio8_hexread and pxio8_hexwrite load and save an image in X/Y format as 1 pixel per 2 hexadecimal ASCII characters. New functions pxio8_tiffread, pxio8_tiffwrite, pxio8_tiffparm, and pxio8_tiffparmr load and save an image area of interest, and optionally an associated color palette, to/from a file in the TIFF file format at 1 to 8 bits per pixel.

  20. The pxip8_drawchars has been improved to draw characters with no background fill, as well as with background fill. Antialiasing can now be done with both a foreground and background grey level specified. Old code using this function should be modified.


RELEASE NOTES: PXIPL — Version 1.1
RELEASE NOTES: PXIPL — Version 1.2

  1. Initial release for use with SVDRV V6.4 and 4MDRV V2.4.

  2. Compiled under Microsoft C V5.1, M model and L model.

  3. Function pxip8_dithernormal does not appear in printed documentation. The pxip8_dithernormal is similar to pxip8_dither, but adds noise with a normal (Gaussian) distribution. Arguments and return values are the same as pxip8_dither, except instead of ditherbits the third parameter is a double variance, defining the variance of the noise. A math coprocessor is suggested.

 

 

 

34. Distribution Contents

DISTRIBUTION KIT:


        Image Processing C/C++ Library for
            SVOBJ Version 7.5
            4MOBJ Version 3.5
            XCOBJ Version 1.5
        or  XCLIB Version 3.0/3.7/3.8


The PXIPL distribution contains one or more of:


 1)                     PXIPL Library:
    PXIPM7DM.LIB          Microsoft C/C++ V7.0, M model, DOS V3.0+.
    PXIPM7DL.LIB          Microsoft C/C++ V7.0, L model, DOS V3.0+.
    PXIPM8DM.LIB          Microsoft C/C++ V8.0, M model, DOS V3.0+, (Visual C).
    PXIPM8DL.LIB          Microsoft C/C++ V8.0, L model, DOS V3.0+, (Visual C).


    PXIPB4DM.LIB          Borland C/C++ V4.0, M model, for DOS V3.0+.
    PXIPB4DL.LIB          Borland C/C++ V4.0, L model, for DOS V3.0+.
    PXIPB5DM.LIB          Borland C/C++ V5.0, M model, for DOS V3.0+.
    PXIPB5DL.LIB          Borland C/C++ V5.0, L model, for DOS V3.0+.


    PXIPW1DF.LIB          Watcom 32 Bit C/C++ V11.0, F model, Tenberry+DOS.


    PXSV75W3.DLL          DLL and import library for SVOBJ V7.5,
    PXSV75W3.LIB          for Windows 3.x (compiler independent).


    PX4M35W3.DLL          DLL and Import library for 4MOBJ V3.5
    PX4M35W3.LIB          for Windows 3.x (compiler independent).


    PXSV75W5.DLL          DLL and import library for SVOBJ V7.5,
    PXSV75W5.LIB          for Windows 95 (compiler independent).


    PX4M35W5.DLL          DLL and Import library for 4MOBJ V3.5,
    PX4M35W5.LIB          for Windows 95 (compiler independent).


    PXXC15W5.DLL          DLL and Import library for XCOBJ V1.5,
    PXXC15W5.LIB          for Windows 95 (compiler independent).


    PXIPLW95.DLL          DLL and Import library for XCLIB V3.0,
    PXIPLW95.LIB          for Windows 95/98/ME (compiler independent).


    PX4M35WT.DLL          DLL and Import library for 4MOBJ V3.5,
    PX4M35WT.LIB          for Windows NT V4.0 (compiler independent).


    PXXC15WT.DLL          DLL and Import library for XCOBJ V1.5,
    PXXC15WT.LIB          for Windows NT V4.0 (compiler independent).


    PXIPLWNT.DLL          DLL and Import library for XCLIB V3.0,
    PXIPLWNT.LIB          for Windows NT/2000/XP/Vista/7/8/10 32-Bit (compiler independent).


    PXIPLW64.DLL          DLL and Import library for XCLIB V3.0,
    PXIPLW64.LIB          for Windows XP/Vista/7/8/10/11 64-Bit (compiler independent).


    PXIPM2W5.LIB          Library, static link for XCLIB V3.0,
                          for Windows 95/98/ME,
                          Microsoft V12 (Visual Studio V6).


    PXIPM2WT.LIB          Library, static link for XCLIB V3.0,
                          for Windows NT/2000/XP/Vista 32-Bit,
                          Microsoft V12 (Visual Studio V6).


    pxipl_i386.a          Library, static link, for Linux,
    pxipl_i386_pic.a      Intel i386, and GNU 'C'; compiled with and
                          without PIC option.
    pxipl_i386.so         Library, shared object, for Linux,
                          Intel i386.


    pxipl_x86_64.a        Libary, static link, for Linux,
    pxipl_x86_64_pic.a    Intel x86_64, and GNU 'C'; compiled with and
                          without PIC option.
    pxipl_x86_64.so       Library, shared object, for Linux,
                          Intel x86_64.




 2) pxipl.h             Master C include file for programs using PXIPL.


    pxi8hist.h          Various C include files for PXIPL.
    pxi8mmnt.h          Included by inclusion of PXIPL.H.
    pxi8pcl.h   pxiplver.h
    pxi8vitc.h  pximfile.h
    pximregn.h  pximshap.h
    pximage.h   pximages.h
    pxerrno.h   pxextras.h


    pxip8.h             Old name of PXIPL.H, prototypes of obsolete functions.


 3) PXIPC4S1.LIB        PXIPL Native Libraries, for 4MOBJ and COC40,
    PXIPC4S2.LIB        Texas Instruments TMS320C40 C Compiler.
    PXIPC4S3.LIB
    PXIPC4S4.LIB


 4)                     PXIPL Bound Libraries, for 4MOBJ and COC40:
    PXC4M7DM.LIB          for Microsoft C/C++ V7.0, M Model, DOS 3.0+.
    PXC4M7DL.LIB          for Microsoft C/C++ V7.0, L Model, DOS 3.0+.
    PXC4M8DM.LIB          for Microsoft C/C++ V8.0, M Model, DOS 3.0+.
    PXC4M8DL.LIB          for Microsoft C/C++ V8.0, L Model, DOS 3.0+.


    PXC4B4DM.LIB          for Borland C/C++ V4.0, M Model, DOS 3.0+.
    PXC4B4DL.LIB          for Borland C/C++ V4.0, L Model, DOS 3.0+.
    PXC4B5DM.LIB          for Borland C/C++ V4.0, M Model, DOS 3.0+.
    PXC4B5DL.LIB          for Borland C/C++ V4.0, L Model, DOS 3.0+.


    PXC4W0DF.LIB          for Watcom 32 Bit C/C++ V10.0, Tenberry+DOS.
    PXC4W1DF.LIB          for Watcom 32 Bit C/C++ V11.0, Tenberry+DOS.


    PXC435W3.DLL          DLL and inport library for Windows 3.x
    PXC435W3.LIB          (compiler independent).


    PXC435W5.DLL          DLL and inport library for Windows 95
    PXC435W5.LIB          (compiler independent).


    PXC435WT.DLL          DLL and inport library for Windows NT V4.0
    PXC435WT.LIB          (compiler independent).


    M4C4PXIP.H          Include file for COC40 bound functions.


 5) PXIPLW95_VB.TXT     Declarations for Visual Basic, VB.NET, LabView,
    PXIPLW95_VBNET.TXT  and Matlab for Windows 95/98/ME.
    PXIPLW95_IMPORT.H
    PXIPLW95_LABVIEW.H
    PXIPLWNT_VB.TXT     Declarations for Visual Basic, VB.NET, LabView, Matlab,
    PXIPLWNT_VBNET.TXT  and C# for Windows NT/2000/XP/Vista/7/8/10 32-Bit.
    PXIPLWNT_IMPORT.H
    PXIPLWNT_LABVIEW.H
    PXIPLWNT_CSHARP.TXT
    PXIPLW64_VB.TXT         Declarations for VB.NET, LabView, Matlab, and C#
    PXIPLW64_VBNET64.TXT    for Windows XP/Vista/7/8/10/11 64-Bit.
    PXIPLW64_IMPORT.H
    PXIPLW64_LABVIEW.H
    PXIPLW64_CSHARP64.TXT
    pxipl_i386_import.h     Declarations for LabView & Matlab
    pxipl_i386_labview.h    for Linux Intel i386.
    pxipl_x86_64_import.h   Declarations for LabView & Matlab
    pxipl_x86_64_labview.h  for Linux Intel x86_64.




 6) *.txt               One or more ASCII text files containing distribution
                        information, release notes, manual updates, etc.


 7) pxipl.htm           Complete Image Processing C/C++ Library Reference Manual, in HTML format.


 A) Image Processing C/C++ Library Reference Manual.




Items 1 through 7 distributed on diskettes or CD/DVD.
Item A distributed on paper.

35. Footnotes

[1]
Provided that the frame grabber's architecture and current operating mode does not prohibit such access.
[2]
These compatible declarations are useful only in conjunction with a single frame grabber. The pxd_defineImage or pxd_defineImage3 should be used with multiple frame grabbers.
[3]
The include file(s) attempt to automatically identify C++ environments and thereby eliminate the need of using ''extern'', but the automatic detection may not work with all compilers or all compiler options. Inclusion of the explicit ''extern'' is recommended.
[4]
Aficionados of C++ will recognize this description as a ''virtual class'', and may think of it as such. However, for compatibility with ''C'' programs, the pximage is implemented as a structure from which member functions (methods) are called via function pointers. Unlike typical class objects, the pximage may be freely copied and destroyed; there are no class destructors.
[5]
E.g. must be ''constructed'', for C++ aficionados.
[6]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[7]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[8]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[9]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[10]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[11]
A ''z-slice'' being a two-dimensional image defined by common Z coordinate.
[12]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[13]
Current EPIX® imaging software does not create TIFF images with a different number of bits per pixel component; the infop->fi.tiff.bitspersample[] may be helpful in understanding TIFF images created by foreign programs.
[14]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[15]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[16]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[17]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[18]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[19]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[20]
A ''z-slice'' being a two-dimensional image defined by common Z coordinate.
[21]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[22]
Being private compression methods, images saved with PXIMTIFF_Compress_EPIX_LsLs or PXIMTIFF_Compress_EPIX_LsLsHP can't be read by non-EPIX® imaging software.
[23]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[24]
A ''z-slice'' being a two-dimensional image defined by common Z coordinate.
[25]
A reminder regarding file path names: C/C++ interprets any reverse solidus (''\'') in a character string as a special escape character (see section 2.3 of The C Programming Language by Kernighan & Ritchie or section 2.4.3 of The C++ Programming Language by Stroustrup). Either use two (''\'') characters which C/C++ translates to a single reverse solidus, or use a solidus (''/''), accepted by DOS and Windows in liu of a reverse solidus. The file path name may contain directory and disk prefixes, or may be relative to the current working directory.
[26]
A nibble is 4 bits.
[27]
Machines with CHAR_BIT (see ''C'' compiler documentation) larger than 8 (bits) have proportionally more nibbles per ''uchar''. There are 8 nibbles per 32 bit ''uchar'' on the TMS320C40.
[28]
This examples assumes a ''uchar'' size of 8 bits.
[29]
This restriction is due solely to Window's architecture and may not apply to all versions of Windows.
[30]
A region is convex if a rubber band stretched around the perimeter contacts the entire perimeter without gaps. A region contains a hole if it totally encloses one or more pixels that are not part of the region.

The letter 'O' contains a hole, and is convex. The letter 'C' does not contain a hole, and is not convex. A period ('.') does not contain a hole, and is convex.

[31]
UINT_MAX is defined by the ``C'' library as 65535 in 16 bit environments, or 4294967295 in 32 bit environments.
[32]
A region is convex if a rubber band stretched around the perimeter contacts the entire perimeter without gaps. A region contains a hole if it totally encloses one or more pixels that are not part of the region.

The letter 'O' contains a hole, and is convex. The letter 'C' does not contain a hole, and is not convex. A period ('.') does not contain a hole, and is convex.

[33]
Use of mode&PXIP8BLOB_NOCLEAR, is useful only if nblobs=1, allowing use of pxip8_bloblist to extract information about one blob in the image.
[34]
The ''baseline'' is the lowest point of nondescending characters.
[35]
The ''baseline'' is the lowest point of nondescending characters.
[36]
The terms ''surface'', ''primary surface'', and ''overlay surface'' are defined by Direct Draw.
[37]
Such as the VGA 16 and 256 color modes, where the pixel value is used as an index into a palette.
[38]
The pxio8_vgadisplay does not, itself, set the S/VGA's palette.
[39]
Such as the VGA 16 and 256 color modes, where the pixel value is used as an index into a palette.
[40]
The pxio8_vgadisplay does not, itself, set the S/VGA's palette.
[41]
The terms ''Display'', ''Drawable'', ''TrueColor'', and ''DirectColor'' are defined by XWindows/X11.

36. Index

  • ::pxlib.initFilteredPximage
  • ::pxlib.initFilteredPximage3
  • ::pxlib.initPximage
  • ::pxlib.initPximage3
  • _cfunacc
  • _cfunfcc
  • _cfunvcc
  • Add Pixels of Image Pair
  • Add Pseudo-Random Noise
  • AND Pixels of Image Pair
  • AND Pixels with Mask in Region
  • AND Pixels with Mask
  • Average Image Sequence
  • Average Pixels of Image Pair
  • AVI 1.0 File, Save Image Sequence
  • AVI 1.0 File, Save Image Sequence
  • AVI 1.0 File, Save Sequence - Init
  • AVI 2.0 File, Save Image Sequence
  • AVI 2.0 File, Save Sequence - Init
  • AVI File, Load Image Sequence
  • AVI File, Load Image Sequence
  • AVI x.0 File, Save Sequence - Add Image
  • AVI x.0 File, Save Sequence - Done
  • Binary File, Save Sequence - Add Image
  • Binary File, Save Sequence - Done
  • Binary File, Save Sequence - Init
  • Bit Reverse Pixel Values in Region
  • Bit Reverse Pixel Values
  • Blend Pixels of Image Pair
  • BMP File, Load Image
  • BMP File, Save Image
  • Calibrate Intensity/Density Mapping
  • Calibrate Spatial Mapping
  • Compilation
  • Complement Pixel Values in Region
  • Complement Pixel Values
  • Compress Region Path
  • Compute Center of Mass
  • Compute Center of Mass of N'th Power
  • Compute Center of Mass of N'th Power of Region
  • Compute Center of Mass of Region
  • Compute Center of Mass, Binary Image
  • Compute Center of Mass, Binary Image Region
  • Compute Histogram
  • Compute Histogram on Region
  • Compute Histogram on Region
  • Compute Histogram on Region
  • Compute Histogram Statistics
  • Compute Histogram Statistics
  • Compute Histogram Statistics w. Interpretation
  • Compute Histogram Statistics w. Interpretation
  • Compute Moments
  • Compute Moments of Region
  • Compute Moments of Region w. Interpretation
  • Compute Moments w. Interpretation
  • Compute Radial Mass
  • Compute Radial Mass w. Interpretation
  • Compute Shape Statistics of Image Region
  • Compute Tabulated Histogram
  • Compute Tabulated Histogram
  • Compute Tabulated Histogram of Differences
  • Compute Tabulated Histogram of Differences on Region
  • Construct PXIMAGE: 2-D Slice of 3-D Image
  • Construct PXIMAGE: 3-D Representation of 2-D Image
  • Construct PXIMAGE: Access Freq. Domain Complex Image
  • Construct PXIMAGE: Access Image in File
  • Construct PXIMAGE: Access Image in File, Done
  • Construct PXIMAGE: Access Image in Host Memory
  • Construct PXIMAGE: Access Image in Host Memory
  • Construct PXIMAGE: Access Imaging Board Buffer
  • Construct PXIMAGE: Access Imaging Board Buffer
  • Construct PXIMAGE: Allocate Image in Malloc'ed Memory
  • Construct PXIMAGE: Allocate Image in Malloc'ed Memory
  • Construct PXIMAGE: Converted Color Space of Image
  • Construct PXIMAGE: Release Image in Malloc'ed Memory
  • Construct PXIMAGE: Release Image in Malloc'ed Memory
  • Construct PXIMAGE: Slice of Color Image
  • Construct PXIMAGE3: Access Image Sequence in Host Memory
  • Construct PXIMAGE3: Access Image Sequence in Host Memory
  • Construct PXIMAGE3: Access Imaging Board Buffers
  • Construct PXIMAGE3: Allocate Image Sequence in Malloc'ed Memory
  • Construct PXIMAGE3: Allocate Image Sequence in Malloc'ed Memory
  • Construct PXIMAGE3: Release Image Sequence in Malloc'ed Memory
  • Construct PXIMAGE3: Release Image Sequence in Malloc'ed Memory
  • Contrast Enhance By Percentile
  • Contrast Enhance
  • Contrast Enhance Real Pixels
  • Contrast Enhance Region By Percentile
  • Contrast Enhance Region
  • Contrast Enhance Region Real Pixels
  • Contrast Match Image Pair
  • Copy & Area Interpolation
  • Copy & Bilinear Interpolation w. Orientation
  • Copy & Convert Color Space
  • Copy & Convert Data Types
  • Copy & Exchange Image Buffers
  • Copy & Nearest Neighbor Interpolation w. Orientation
  • Copy & Skew Image Left/Right
  • Copy & Skew Image Up/Down
  • Copy & Spatial Replicate/Decimation
  • Copy Image Buffer
  • Copy Image Buffer Region
  • Copy Image Buffer with Reversal
  • Copy Image Buffer with Shift
  • Copy Image with Pincushion/Barrel Warping
  • Copy Image with Rotation & Offset
  • Copy Image with Rotation
  • Copy Image with Warping
  • Copy Image with Warping
  • Copy Pixel Components in Region
  • Copy Pixel Components
  • Copy Slice of Image Buffer
  • Correct Image as per Speckle Mask
  • Correct Image as per Speckle Mask
  • Correlation Peak
  • Correlation Profile
  • Count Pixels by Threshold
  • Count Real Pixels by Threshold
  • Count Region Pixels by Threshold
  • Count Region Real Pixels by Threshold
  • ddch.cnt
  • ddch.len
  • De-Flicker Interlace: Line Pair Average
  • De-Flicker Interlace: Line Pair Duplicate
  • De-Flicker Interlace: Modify Singularities
  • Decode SMPTE Vertical Interval Time Code
  • Difference for Insert of Image Pair
  • Dither Pixels, Uniform
  • DOS Mouse: Get Clicks
  • DOS Mouse: Get Motion
  • DOS Mouse: Get Status
  • DOS Mouse: Initialize Access
  • DOS Mouse: Terminate Access
  • DOS S/VGA: Set Mode and Initialize Access
  • DOS S/VGA: Terminate Access
  • Draw 2-D Cosine Product Pattern
  • Draw 2-D Fiducial Pattern
  • Draw 2-D Gaussian Pattern
  • Draw 2-D Separable Patterns
  • Draw Alignment Pattern
  • Draw Arrow
  • Draw Box
  • Draw Characters
  • Draw Circle
  • Draw Curved Line defined as Bezier Polynomial
  • Draw Ellipse
  • Draw Ellipse Section
  • Draw Icon or Cursor
  • Draw Icon Primitive, Free Resources
  • Draw Icon Primitive, Initialize
  • Draw Icon Primitive, Modify Pixels
  • Draw Icon Primitive, Test Completion
  • Draw Line Segment
  • Draw Region Boundary
  • Draw Region Path
  • Draw Test Pattern
  • Draw Text from Font Map
  • Draw Text
  • Edge Detection, Kirsch
  • Edge Detection, Roberts
  • Edge Detection, Sobel Absolute
  • Edge Detection, Sobel
  • Edge Gradient, Thin
  • Ellipse Fitting Measurement
  • Errors: Translate Error Code to String
  • Exclusive OR Pixels of Image Pair
  • Export Region to File
  • Extend Region Path
  • Extend Region Path
  • FFT: Filter Frequency Domain
  • FFT: Get Dimensions of Freq. Domain Representation
  • FFT: Inverse Transform Image
  • FFT: Log Magnitude Plot of Freq. Domain
  • FFT: Scale Freq. Domain by Log Magnitude Plot
  • FFT: Transform Image
  • Field Interlaced Image Line Shuffle
  • Field Interlaced Image Line UnShuffle
  • FIFO Average
  • Filter, Low Pass, Fixed
  • Filter, Low Pass, Low Smear
  • Filter, Low Pass, Weighted
  • Filter, Median
  • Filter, Median, Binary Images
  • Filter, Median, Weighted
  • Filter, Rank High (Dilate)
  • Filter, Rank Low (Erode)
  • Filter, Sharpen, Laplacian
  • Find Blobs and List
  • Find Blobs and List
  • Find Blobs, Analyze and List
  • Find Region's Enclosed Area
  • Find Region's Enclosing Window
  • FITS File, Load Image
  • FITS File, Load Image Sequence
  • FITS File, Save Image
  • FITS File, Save Image Sequence
  • FITS File, Save Sequence - Add Image
  • FITS File, Save Sequence - Done
  • FITS File, Save Sequence - Init
  • Flat field Normalization
  • Follow and Collect Region Boundary by Value
  • Free Region
  • Gamma Correction
  • Get PXIMAGE: Access Frame Grabber Image Buffer
  • Get PXIMAGE: Access Frame Grabber Image Buffer
  • Get PXIMAGE: Access Imaging Board Buffer
  • Get PXIMAGE: Access Imaging Board Color Buffer
  • Get PXIMAGE: Release Access to Frame Grabber Image Buffers
  • Get PXIMAGE3: Access Frame Grabber Image Buffers
  • Get PXIMAGE3: Access Frame Grabber Image Buffers
  • Get PXIMAGE3: Access Imaging Board Buffers
  • Get PXIMAGE3: Access Imaging Board Color Buffers
  • Get PXIMAGE3: Release Access to Frame Grabber Image Buffers
  • Gray Code/Decode Pixel Values in Region
  • Gray Code/Decode Pixel Values
  • H-P PCL Font: Draw Line of Characters
  • H-P PCL Font: Load
  • H-P PCL Font: Obtain Character Info
  • H-P PCL Font: Obtain Information
  • H-P PCL Font: Unload
  • Halftone by Black/White Sum
  • Histogram Equalization
  • Image File, Obtain Information
  • Image File, Obtain Information on Subfiles
  • Image File, Release Information
  • Image Rotation
  • Image Rotation
  • Import Region from File
  • Inclusions
  • Initialize Region Path
  • Insert of Differences of Image Pair
  • Integrate Image Sequence
  • JPEG File, Load Image
  • JPEG File, Save Image
  • Left Rotate Pixel Values in Region
  • Left Rotate Pixel Values
  • Left Shift Pixel Values in Region
  • Left Shift Pixel Values
  • Libraries
  • Line Pair Pixel Shuffle
  • Line Pair Pixel UnShuffle
  • Linux
  • Linux: Display Cursor via XWindows/X11
  • Linux: Display Image via XWindows/X11
  • Load Image from File, Hex ASCII
  • Load Image from File, Packed Binary
  • Load Image from File, Unpacked Binary
  • Load Image Sequence from File, Packed Binary
  • Load Image Sequence from File, Unpacked Binary
  • Map Pixel Values in Region
  • Map Pixel Values
  • Map Uchar Pixel Values in Region
  • Map Uchar Pixel Values
  • Map uint16 Pixel Values in Region
  • Map uint16 Pixel Values
  • Map uint32 Pixel Values in Region
  • Map uint32 Pixel Values
  • Maximum of Pixels of Image Pair
  • Mean/Std.Dev/Variance of Image Sequence
  • Medial Axis Thinning
  • Minimum of Pixels of Image Pair
  • Modify Region Definition: Rectangle to Polygon
  • Morphological Boundary
  • Morphology Close
  • Morphology Dilation
  • Morphology Dilation w. 3x3 Element
  • Morphology Erosion
  • Morphology Erosion w. 3x3 Element
  • Morphology Hit-Miss
  • Morphology Open
  • Mouse
  • mousedeinit
  • mousegetpress
  • mousegetstatpos
  • mouseinit
  • mousemotioncount
  • MSB Extend Pixel Values in Region
  • MSB Extend Pixel Values
  • N-Field Interlaced Image Line Shuffle
  • N-Field Interlaced Image Line UnShuffle
  • Normalize Columns' Mean
  • Normalize Image as per Background Image
  • Normalize Lines' Mean
  • NxN Convolution, Integer
  • NxN Convolution, Real
  • NxN Dynamic Threshold
  • NxN Inverse Contrast Ratio Mapping
  • Obtain Filtered pximage Access into Frame Grabber Memory
  • Obtain Filtered pximage3 Access into Frame Grabber Memory
  • Obtain pximage Access into Frame Grabber Memory
  • Obtain pximage3 Access into Frame Grabber Memory
  • Offset Pixel Values in Region
  • Offset Pixel Values in Region
  • Offset Pixel Values
  • Offset Pixel Values
  • OR Pixels of Image Pair
  • OR Pixels with Mask in Region
  • OR Pixels with Mask
  • Overlay Pixels of Image Pair
  • Overlay Pixels of Image Pair
  • Paint within Region
  • PCX File, Save Image
  • Perform Intensity/Density Mapping
  • Perform Inverse Spatial Mapping
  • Perform Spatial Mapping
  • Portable Map File, Load Image
  • Portable Map File, Load Image Sequence
  • Portable Map File, Save Image
  • Portable Map File, Save Image Sequence
  • Portable Map File, Save Sequence - Add Image
  • Portable Map File, Save Sequence - Done
  • Portable Map File, Save Sequence - Init
  • Print Image
  • Product of Pixels of Image Pair
  • Product of Pixels of Image Pair
  • pxabortfunc_t
  • pxabortfunc_t
  • pxcoord_t
  • pxd_defimage
  • pxd_defimage3
  • pxd_defimage3color
  • pxd_defimagecolor
  • pxd_defineImage
  • pxd_defineImage3
  • pxd_definePximage
  • pxd_definePximage3
  • pxd_definePximage3Free
  • pxd_definePximageFree
  • pxerrnomesg
  • pxim1size_t
  • pxim2size_t
  • pxim3size_t
  • pximage, struct
  • pximage_colorconverter
  • pximage_colorslice
  • pximage_def2from3
  • pximage_def3from2
  • pximage_file
  • pximage_filedone
  • pximage_memfree
  • pximage_memfree2
  • pximage_memmalloc
  • pximage_memmalloc2
  • pximage_memory
  • pximage_memory2
  • pximage_s
  • pximage_setwind
  • pximage3, struct
  • pximage3_memfree
  • pximage3_memfree2
  • pximage3_memmalloc
  • pximage3_memmalloc2
  • pximage3_memory
  • pximage3_memory2
  • pximage3_s
  • pximage3_setwind
  • pximcnt_t
  • pximfileinfo, struct
  • pximfileinfo, struct
  • pximfileinfo, struct
  • pximfileinfo, struct
  • pximfileinfo, struct
  • pximfileinfo, struct
  • pximregion, struct
  • PXIMREGION: NonRectangular Image Region Specification
  • pxio8_aviodmlwriteseq
  • pxio8_aviodmlwriteseqinit
  • pxio8_aviread
  • pxio8_avireadseq
  • pxio8_aviwriteseq
  • pxio8_aviwriteseq2
  • pxio8_aviwriteseqadd
  • pxio8_aviwriteseqdone
  • pxio8_aviwriteseqinit
  • pxio8_bin1read
  • pxio8_bin1readseq
  • pxio8_bin1write
  • pxio8_bin1writeseq
  • pxio8_binread
  • pxio8_binreadseq
  • pxio8_binwrite
  • pxio8_binwriteseq
  • pxio8_binwriteseqadd
  • pxio8_binwriteseqdone
  • pxio8_binwriteseqinit
  • pxio8_bmpread
  • pxio8_bmpwrite
  • pxio8_DIBCreate
  • pxio8_DIBCreateDone
  • pxio8_DirectXDisplay
  • pxio8_DrawDibDisplay
  • pxio8_fileinfo
  • pxio8_fileinfodone
  • pxio8_fileinfoN
  • pxio8_fitsread
  • pxio8_fitsreadseq
  • pxio8_fitswrite
  • pxio8_fitswriteseq
  • pxio8_fitswriteseqadd
  • pxio8_fitswriteseqdone
  • pxio8_fitswriteseqinit
  • pxio8_GDICoord
  • pxio8_GDICoord1
  • pxio8_GDICursor
  • pxio8_GDIDisplay
  • pxio8_GDIWaterfall
  • pxio8_hexread
  • pxio8_hexwrite
  • pxio8_jpegread
  • pxio8_jpegwrite
  • pxio8_pcxwrite
  • pxio8_pgmgwrite
  • pxio8_pgmread
  • pxio8_pgmreadseq
  • pxio8_pgmwriteseq
  • pxio8_pgmwriteseqadd
  • pxio8_pgmwriteseqdone
  • pxio8_pgmwriteseqinit
  • pxio8_print
  • pxio8_tgawrite
  • pxio8_tifread
  • pxio8_tifreadseq
  • pxio8_tifwrite
  • pxio8_tifwriteseq
  • pxio8_tifwriteseqadd
  • pxio8_tifwriteseqdone
  • pxio8_tifwriteseqinit
  • pxio8_vgacoord
  • pxio8_vgacoord1
  • pxio8_vgacursor
  • pxio8_vgadisplay
  • pxio8_vgawaterfall
  • pxio8_X11Cursor
  • pxio8_X11Display
  • pxio8print, struct
  • pxip_calibhvxymap
  • pxip_calibxyhv
  • pxip_calibxyhvdone
  • pxip_calibxyhvmap
  • pxip_calibzi
  • pxip_calibzidone
  • pxip_calibzimap
  • pxip_fitellipse
  • pxip_fractedges
  • pxip_fractlines
  • pxip_particleflow
  • pxip8_2x2roberts
  • pxip8_3x3binmedian
  • pxip8_3x3kirsch
  • pxip8_3x3ksrthin
  • pxip8_3x3lowpass
  • pxip8_3x3lowpassf
  • pxip8_3x3lowpassmear
  • pxip8_3x3median
  • pxip8_3x3medianw
  • pxip8_3x3rankhigh
  • pxip8_3x3ranklow
  • pxip8_3x3sharpenl
  • pxip8_3x3sobel
  • pxip8_3x3sobela
  • pxip8_averagebufs
  • pxip8_binmaxisthin
  • pxip8_bloblist
  • pxip8_bloblist2
  • pxip8_bloblist3
  • pxip8_contrastmatch
  • pxip8_copy
  • pxip8_copycolorconvert
  • pxip8_copyconvert
  • pxip8_copyexchange
  • pxip8_copyinterpbilinear
  • pxip8_copyinterpnearest
  • pxip8_copyinterpolate
  • pxip8_copyreplic
  • pxip8_copyreverse
  • pxip8_copyshift
  • pxip8_copyskewlr
  • pxip8_copyskewud
  • pxip8_copyslice
  • pxip8_correlatefind
  • pxip8_correlateprof
  • pxip8_dither
  • pxip8_drawarrow
  • pxip8_drawbezier
  • pxip8_drawbox
  • pxip8_drawchars
  • pxip8_drawchars3
  • pxip8_drawchars4
  • pxip8_drawchars5
  • pxip8_drawellipse
  • pxip8_drawellipsesect
  • pxip8_drawicon
  • pxip8_drawiconfree
  • pxip8_drawiconhit
  • pxip8_drawiconhitw
  • pxip8_drawiconinit
  • pxip8_drawline
  • pxip8_fft
  • pxip8_fftcimage
  • pxip8_fftfilterz
  • pxip8_ffti
  • pxip8_fftlmagscale
  • pxip8_fftlogmag
  • pxip8_fftsizes
  • pxip8_fifoaverage
  • pxip8_findpixel
  • pxip8_findpixelmax
  • pxip8_findpixelmin
  • pxip8_findpixelv
  • pxip8_geotranpincushion2
  • pxip8_geotranrotate
  • pxip8_geotranrotate2
  • pxip8_geotranwarp
  • pxip8_geotranwarp2
  • pxip8_halftsum
  • pxip8_histab
  • pxip8_histab2
  • pxip8_histab3
  • pxip8_histabpair
  • pxip8_histfit
  • pxip8_histstat
  • pxip8_histstat2
  • pxip8_histstat2f
  • pxip8_histstatf
  • pxip8_ilacefieldtoline
  • pxip8_ilacelineshift
  • pxip8_ilacelinetofield
  • pxip8_ilacelinetoNfield
  • pxip8_ilacemodsingular
  • pxip8_ilaceNfieldtoline
  • pxip8_ilacepairave
  • pxip8_ilacepairdup
  • pxip8_ilacepairswap
  • pxip8_integratebufs
  • pxip8_masscenter
  • pxip8_masscenterbin
  • pxip8_masscenterpow
  • pxip8_moments
  • pxip8_momentsf
  • pxip8_morpclose
  • pxip8_morpdilate
  • pxip8_morpdilate3x3
  • pxip8_morperode
  • pxip8_morperode3x3
  • pxip8_morphitmiss
  • pxip8_morpopen
  • pxip8_noiseadd
  • pxip8_normalizebackground
  • pxip8_normalizeintensity
  • pxip8_normalizemeancolumn
  • pxip8_normalizemeanline
  • pxip8_normalizespecklemask
  • pxip8_normalizespecklemask2
  • pxip8_NxNcontrastinvert
  • pxip8_NxNconvolve
  • pxip8_NxNconvolvef
  • pxip8_NxNdynthreshold
  • pxip8_pairadd
  • pxip8_pairand
  • pxip8_pairave
  • pxip8_pairblend
  • pxip8_pairinsdiff
  • pxip8_pairinsert
  • pxip8_pairmax
  • pxip8_pairmin
  • pxip8_pairor
  • pxip8_pairoverlay
  • pxip8_pairprod
  • pxip8_pairratio
  • pxip8_pairsub
  • pxip8_pairxor
  • pxip8_patternalign
  • pxip8_patterncos
  • pxip8_patternfiducial
  • pxip8_patterngaussian
  • pxip8_patterns
  • pxip8_pclfontcinfo
  • pxip8_pclfontdraw
  • pxip8_pclfontinfo
  • pxip8_pclfontload
  • pxip8_pclfontunload
  • pxip8_pixadd
  • pxip8_pixand
  • pxip8_pixcontrast
  • pxip8_pixcontrastperc
  • pxip8_pixelstatsbufs
  • pxip8_pixgamma
  • pxip8_pixgraycode
  • pxip8_pixieave
  • pxip8_pixiecopy
  • pxip8_pixiemax
  • pxip8_pixiemin
  • pxip8_pixmap
  • pxip8_pixmapl
  • pxip8_pixmaplut
  • pxip8_pixmaps
  • pxip8_pixmsb
  • pxip8_pixneg
  • pxip8_pixor
  • pxip8_pixreverse
  • pxip8_pixrotl
  • pxip8_pixrotr
  • pxip8_pixscale
  • pxip8_pixset
  • pxip8_pixset3
  • pxip8_pixshl
  • pxip8_pixshr
  • pxip8_pixthreshold
  • pxip8_pixthreshold2
  • pxip8_pixthreshold3
  • pxip8_pixthresholdcnt
  • pxip8_pixxor
  • pxip8_radialmass
  • pxip8_radialmassf
  • pxip8_recursiveaverage
  • pxip8_recursiveaverage2
  • pxip8_seqtile
  • pxip8_smptevitcdecode
  • pxip8_spatialquantize
  • pxip8_testpattern
  • pxip8_xlacecolumntohalves
  • pxip8_xlacecolumntoNsection
  • pxip8_xlacehalvestocolumn
  • pxip8_xlaceNsectiontocolumn
  • pxip8_xlaceshuffle
  • pxip8_xlaceunshuffle
  • pxip8blob, struct
  • pxip8blob, struct
  • pxip8blob, struct
  • pxip8blob3, struct
  • pxip8corr, struct
  • pxip8histab, struct
  • pxip8histperc, struct
  • pxip8histstat, struct
  • pxip8pat, struct
  • pxip8pat, struct
  • pxip8pat, struct
  • pxip8pat, struct
  • pxip8smptevitc, struct
  • pxipf_pairoverlay
  • pxipf_pairprod
  • pxipf_pairratio
  • pxipf_pixadd
  • pxipf_pixcontrast
  • pxipf_pixscale
  • pxipf_pixset3
  • pxipf_pixthresholdcnt
  • pxipmoments, struct
  • pxirp_pathcompress
  • pxirp_pathcreate
  • pxirp_pathextend
  • pxirp_pathextend1
  • pxirp_regionarea
  • pxirp_regionbounds
  • pxirp_regionexport
  • pxirp_regionfree
  • pxirp_regionimport
  • pxirp_regionshapef
  • pxirp_xlaterecttopoly
  • pxirp_xlatetopath
  • pxirp_xlatetoscanlist
  • pxirp8_connectregion
  • pxirp8_connectregionv
  • pxirp8_copy
  • pxirp8_drawboundary
  • pxirp8_drawpath
  • pxirp8_followregionv
  • pxirp8_histab
  • pxirp8_histab2
  • pxirp8_histab3
  • pxirp8_histabpair
  • pxirp8_masscenter
  • pxirp8_masscenterbin
  • pxirp8_masscenterpow
  • pxirp8_moments
  • pxirp8_momentsf
  • pxirp8_paintregion
  • pxirp8_pixadd
  • pxirp8_pixand
  • pxirp8_pixcontrast
  • pxirp8_pixcontrastperc
  • pxirp8_pixgraycode
  • pxirp8_pixieave
  • pxirp8_pixiecopy
  • pxirp8_pixiemax
  • pxirp8_pixiemin
  • pxirp8_pixmap
  • pxirp8_pixmapl
  • pxirp8_pixmaplut
  • pxirp8_pixmaps
  • pxirp8_pixmsb
  • pxirp8_pixneg
  • pxirp8_pixor
  • pxirp8_pixreverse
  • pxirp8_pixrotl
  • pxirp8_pixrotr
  • pxirp8_pixscale
  • pxirp8_pixset
  • pxirp8_pixset
  • pxirp8_pixshl
  • pxirp8_pixshr
  • pxirp8_pixthreshold
  • pxirp8_pixthreshold2
  • pxirp8_pixthreshold3
  • pxirp8_pixthresholdcnt
  • pxirp8_pixxor
  • pxirpf_pixadd
  • pxirpf_pixcontrast
  • pxirpf_pixscale
  • pxirpf_pixthresholdcnt
  • pxirpshape, struct
  • pxvid_setpximage
  • pxvid_setpximage2
  • pxvid_setpximage3
  • pxy, struct
  • pxy_s
  • pxyd, struct
  • pxyd_s
  • pxydwindow, struct
  • pxydwindow_s
  • pxyf, struct
  • pxyf_s
  • pxypoint_s
  • pxypointz_s
  • pxypointz_s
  • pxypointz_s
  • pxywindow, struct
  • pxywindow_s
  • pxyz, struct
  • pxyz_s
  • pxyzwindow, struct
  • pxyzwindow_s
  • Ratio of Pixels of Image Pair
  • Ratio of Pixels of Image Pair
  • Recursive Average
  • Recursive Average
  • Release Intensity/Density Mapping State
  • Release Spatial Mapping State
  • Right Rotate Pixel Values in Region
  • Right Rotate Pixel Values
  • Right Shift Pixel Values in Region
  • Right Shift Pixel Values
  • S/VGA
  • S/VGA
  • S/VGA
  • S/VGA
  • S/VGA
  • S/VGA: Display Cursor
  • S/VGA: Display Image
  • S/VGA: Translate Image to Screen Coordinates
  • S/VGA: Translate Screen to Image Coordinates
  • S/VGA: Waterfall Line Display
  • Save Image Sequence to File, Packed Binary
  • Save Image Sequence to File, Unpacked Binary
  • Save Image to File, Hex ASCII
  • Save Image to File, Packed Binary
  • Save Image to File, Unpacked Binary
  • Scale Pixel Values in Region
  • Scale Pixel Values in Region
  • Scale Pixel Values
  • Scale Pixel Values
  • Scan, Connect, Collect Region by Table
  • Scan, Connect, Collect Region by Value
  • schar
  • Search for Largest Pixel Value
  • Search for Pixel by Table
  • Search for Pixel by Value
  • Search for Smallest Pixel Value
  • Set Color Pixel Values in Region
  • Set Color Pixel Values
  • Set Pixel Components to Maximum in Region
  • Set Pixel Components to Maximum
  • Set Pixel Components to Median in Region
  • Set Pixel Components to Median
  • Set Pixel Components to Minimum in Region
  • Set Pixel Components to Minimum
  • Set Pixel Values in Region
  • Set Pixel Values
  • Set PXIMAGE: Set 2-D Area of Interest Window
  • Set PXIMAGE3: Set 3-D Area of Interest Window
  • Set Real Pixel Values
  • Shift Image One-Half Line Up or Down
  • Shuffle Column Order to Even-Odd Halves
  • Shuffle Column Order to N Sections
  • Shuffle Even-Odd Halves to Column Order
  • Shuffle N Sections to Column Order
  • sint
  • size_t
  • slong
  • Spatial Intensity Normalization
  • Spatial Quantization & Shrink
  • sshort
  • Stack Overflow
  • Struct pximage
  • Struct pximage
  • Struct pximage3
  • Struct pximage3
  • Struct pximfileinfo
  • Struct pximfileinfo
  • Struct pximfileinfo
  • Struct pximfileinfo
  • Struct pximfileinfo
  • Struct pximfileinfo
  • struct pximregion
  • Struct pximregion
  • Struct pxio8print
  • Struct pxip8blob
  • Struct pxip8blob
  • Struct pxip8blob
  • Struct pxip8blob3
  • Struct pxip8corr
  • Struct pxip8histab
  • Struct pxip8histperc
  • Struct pxip8histstat
  • Struct pxip8pat
  • Struct pxip8pat
  • Struct pxip8pat
  • Struct pxip8pat
  • Struct pxip8smptevitc
  • Struct pxipmoments
  • Struct pxirpshape
  • Struct pxy
  • Struct pxy
  • Struct pxyd
  • Struct pxydwindow
  • Struct pxyf
  • Struct pxywindow
  • Struct pxywindow
  • Struct pxyz
  • Struct pxyz
  • Struct pxyzwindow
  • Struct pxyzwindow
  • Subpixel Edge Measurement
  • Subpixel Line Measurement
  • Subtract Pixels of Image Pair
  • Swap Line or Column Pairs
  • Targa File, Save Image
  • Threshold Pixel Values in Region
  • Threshold Pixel Values in Region
  • Threshold Pixel Values in Region
  • Threshold Pixel Values
  • Threshold Pixel Values
  • Threshold Pixel Values
  • TIFF File, Load Image
  • TIFF File, Load Image Sequence
  • TIFF File, Save Image
  • TIFF File, Save Image Sequence
  • TIFF File, Save Sequence - Add Image
  • TIFF File, Save Sequence - Done
  • TIFF File, Save Sequence - Init
  • Tile Image Sequence
  • Track Particle Motion
  • Translate Region Definition to Path
  • Translate Region Definition to Scan List
  • Type _cfunacc
  • Type _cfunfcc
  • Type _cfunvcc
  • Type pxabortfunc_t
  • Type pxabortfunc_t
  • Type pxcoord_t
  • Type pxim1size_t
  • Type pxim2size_t
  • Type pxim3size_t
  • Type pximcnt_t
  • Type schar
  • Type sint
  • Type size_t
  • Type slong
  • Type sshort
  • Type uchar
  • Type uint
  • Type uint16
  • Type uint32
  • Type uint8
  • Type ulong
  • Type ushort
  • uchar
  • uint
  • uint16
  • uint32
  • uint8
  • ulong
  • User-Defined Premature Termination Functions
  • ushort
  • vga_close
  • vga_open
  • Windows
  • Windows
  • Windows
  • Windows
  • Windows: Create Device Independent Bitmap (DIB)
  • Windows: Display Cursor via GDI
  • Windows: Display Image via DirectDraw
  • Windows: Display Image via GDI
  • Windows: Display Image via Video for Windows
  • Windows: Draw Text using FONT
  • Windows: Release Device Independent Bitmap (DIB)
  • Windows: Translate Device to Image Coordinates
  • Windows: Translate Image to Device Coordinates
  • Windows: Waterfall Line Display via GDI
  • XOR Pixels with Mask in Region
  • XOR Pixels with Mask