diff options
Diffstat (limited to 'pkg/xtools/doc/cogetr.hlp')
| -rw-r--r-- | pkg/xtools/doc/cogetr.hlp | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/pkg/xtools/doc/cogetr.hlp b/pkg/xtools/doc/cogetr.hlp new file mode 100644 index 00000000..416935c9 --- /dev/null +++ b/pkg/xtools/doc/cogetr.hlp @@ -0,0 +1,88 @@ +.help cogetr.hlp Feb86 xtools +.ih +NAME +.nf +comap -- Initialize buffered image column access +cogetr -- Get buffered image columns from 2D image +counmap -- Free memory used in image column access +.fi +.ih +SYNOPSIS +.nf +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) +.fi +.ih +DESCRIPTION +A pointer to a real image column vector between the limits \fIline1\fR +and \fIline2\fR 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: + +.nf +(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. +.fi + +The column access interface is initialized with the procedure +\fBcomap\fR. 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 \fBcogetr\fR 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 \fBcogetr\fR 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 \fBcogetr\fR. +The user must free the buffers with the procedure \fBcounmap\fR. +.ih +RETURNED VALUES +\fBComap\fR returns a pointer to a structure internal to the interface. +\fBCogetr\fR returns a pointer to a real vector containing the requested +image column. +.ih +TIMINGS +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). +.ih +SEE ALSO +xtsums +.endhelp |