comap -- Initialize buffered image column access cogetr -- Get buffered image columns from 2D image counmap -- Free memory used in image column access
SYNOPSIS
pointer im # IMIO pointer pointer co # COGETR pointer int maxbuf # Maximum buffer size int col # Column int line1 # First image line of column vector int line2 # Last image line of column vector pointer buf # Returned pointer pointer immap() # Map the image pointer comap() # Map the column access pointer cogetr() # Get columns im = immap (image, mode, 0) co = comap (im, maxbuf) buf = cogetr (co, col, line1, line2) call counmap (co)
DESCRIPTION A pointer to a real image column vector between the limits line1 and line2 is returned. Internally the image data is buffered as a scrolled two dimensional section to minimize the number of image reads. This interface is designed to be efficient when:
(1) The columns are accessed sequentially. (2) The number of lines does not change. (3) The first and last lines change slowly with the column accessed.
The column access interface is initialized with the procedure comap. At this time the maximum size of the internal buffer is set. The buffer should be reasonably large.
When the first column access is made with cogetr a buffer is created containing the number of lines requested and as many columns as will fit within the maximum buffer size. When the number of lines is small then the number of columns buffered will be large (as large as the image if possible). When the number of lines is large then the columns may be buffered in blocks across the image. A pointer to the real column vector requested is returned. Subsequent calls to cogetr will return columns from the buffer without reading the image until a new buffer is required provided that the line limits do not change. If the columns are accessed sequentially (usually from the first column to the last column) then the image will be accessed a minimum number of times consistent with the buffer size.
One type of application accesses entire columns from the image so that the first and last lines do not change. Another type allows the line limits to change in such a way that the total number of lines does not change and the changes are only a few lines between calls. In this case only the new lines are added to the scrolled buffer without the entire buffer needing to be filled. Applications of this type occur when following a feature across an image such as objects in long slit spectra or echelle orders.
The buffer is created and initialized when the buffer pointer is null or when the number of lines requested is changed. Both the buffer and the column data pointer are allocated by cogetr. The user must free the buffers with the procedure counmap.
Comap returns a pointer to a structure internal to the interface. Cogetr returns a pointer to a real vector containing the requested image column.
When used in applications requiring sequential column access with the line limits changing slowly or not at all this interface provides access nearly as efficiently as accessing lines. The actual difference with the same application applied to lines depends on the number of buffer reads required (i.e. on the size of the image).