HELP BOUNDSLIST_UTILS David Young February 1992 revised March 2000 Utilities for manipulating boundslist-type lists specifying rectangular regions of arrays (in any number of dimensions). See HELP * ______ARRAYS for information about boundslists. Wherever these procedures can take a list as an argument they can also take an array, and will extract and use its boundslist, except where noted. The fact that some are prefixed with array_ and others with region_ is accidental and has no meaning. region_size(____list) -> ___int Returns the number of values in the region specified by ____list. region_centre(____list) -> (____num1, ____num2, ...) Returns the coordinates of the centre of the region specified by ____list, as floating point numbers on the stack. The number of values returned is equal to the number of dimensions of the region. (____num1, ____num2, ...) -> region_centre(_____list1) -> _____list2 (____num1, ____num2, ...) -> region_centre(_____list1, ____bool) -> _____list2 Returns a new list with the same size on each dimension as _____list1 but centred on the coordinates given by ____num1, ____num2 etc. The values in the list are not rounded unless the second form is used and the boolean argument is . The form region_centre(list1) -> region_centre(list2) -> list3 returns a region the same size and shape as _____list2 but centred on the region given by _____list1. region_nonempty_check(____list) Mishaps unless ____list represents a non-empty region. array_dimsizes(_____list1) -> _____list2 Returns a list of the array dimensions (i.e. the size along each dimension. array_dimbases(_____list1) -> _____list2 Returns a list of the array lower limits. array_dimtops(_____list1) -> _____list2 Returns a list of the array upper limits. array_dimprods(_____list1) -> _____list2 Returns a list of the array dimension products. See also array_stepsize below. region_rep(____list) -> ____proc Returns a repeater which will then return successive sets of coords from the region represented by ____list, putting them in a vector, thus ____proc() -> ___vec The contents of the ___vec must not be altered between calls. ____proc returns when it has finished. The first index changes fastest on succesive calls to ____proc. Can be used to replace nested for-loops in programs where the number of dimensions of an array is not known in advance. Largely superseded by the *in_array and *in_region for-forms. region_randsample(____list) -> ____proc Returns a repeater which will return successive sets of coords from the region representated by ____list, putting them on the stack thus ____proc() -> (_x, _y, _z, ...) so that ____proc returns as many results as the region has dimensions. The coordinates are chosen randomly from a uniform distribution across the region (using *erandom) and are returned without rounding. array_indexer(____list [,_____check]) -> ____proc Returns a procedure ____proc that takes the same arguments as the array whose bounds are given, but which when called just returns the corresponding index into the arrayvector, thus ____proc(__x1, __x2, ... , __xn) -> ___int If the second optional argument _____check is not false, then ____proc checks that its arguments are within the original bounds. If ____list is actually an array, any offset into the arrayvector is properly dealt with. nthbounds(____list, _n) -> (__b1, __b2) (__b1, __b2) -> nthbounds(____list, _n) The forward procedure returns the bounds on the _n'th dimension of the region represented by ____list. The updater updates the bounds on the _n'th dimension of the region represented by ____list. In this case, ____list cannot be an array. array_stepsize(____list, _n) -> ___int Returns the step in the arrayvector of the array specified by ____list, corresponding to an increment of 1 along the _n'th dimension. (Same as array_dimprods(____list)(_n).) region_expand(_____list1, _n) -> _____list2 Returns the region specified by _____list1 expanded by _n in all directions (shrunk if _n is negative). I.e. an _n-element border is added on all the way round. region_containspoint(_____list1, _____list2) -> ____bool region_containspoint(____num1, [____num2, ____num3, ...,] _____list2) -> ____bool Returns if the point specified by _____list1 or (____num1, ...) is inside or on the border of the region specified by _____list2, otherwise returns . In the first form _____list1 must be a list containing the coordinates of the point, and must be half as long as _____list2; in the second form the coordinates of the point must be on the stack and again there must be one for each dimension of the region given by _____list2. region_inclusion_check(_____list1, _____list2) Mishaps unless the region specified by _____list1 contains that specified by _____list2. region_intersect(_____list1, _____list2) -> ____list Returns the intersection of the regions specified by _____list1 and _____list2. region_bounding(_____list1, _____list2) -> ____list Returns the minimal region that includes the regions specified by _____list1 and _____list2. region_conv_output(_____list1, _____list2) -> ____list If the region given by _____list1 is convolved with a mask with the dimensions given by _____list2, then output data will be placed in the region given by the result ____list. region_conv_input(_____list1, _____list2) -> ____list If the region given by _____list1 is to be filled with data as a result of a convolution with a mask with dimensions _____list2, then the input region will have to have the dimensions given by ____list. region_map(_____list1, _____list2) -> (_____map12, _____map21) Returns two procedures. _____map12 maps linearly from the region specified by _____list1 to the region specified by _____list2 and _____map21 goes in the other direction. If the regions are _n-dimensional, then the map procedures each take _n arguments and return _n results. The results are generally not integers, so have to be rounded to get indexes to the nearest point in an array. region_scale(_____list1, _____list2) -> (_____map12, _____map21) Like region_map, but the procedures returned just scale their arguments according to the relative sizes of the regions, rather than shifting the origin as well. (So can be applied to relative positions, whereas region_map applies to absolute positions.) region_arrvec(_____array, ____list) -> (__i1, _n) If the data in the the region represented by ____list forms a continuous block in the arrayvector of _____array, then returns __i1, the index into the arrayvector of the starting point of the data, and _n, the number of values in the region. If the data are not continuous, both __i1 and _n are returned as . Mishaps if the region is not inside the array. _____array can be a procedure returned by array_indexer, or a list or array. --- $_________popvision/help/boundslist_utils --- Copyright University of Sussex 1992. All rights reserved. ----------