regions primer

QUESTIONS

  • 1. What is a region?
  • 2. How to I get a region in TCL?
  • 3. What pixel types are allowed in regions?
  • 4. How can I find out what is in an existing region?
  • 5. How can I act on pixel values?
  • 6. How can I act on header values?
  • 7. How can I act on mask values?
  • 8. What other operations are available?
  • 9. How do I access the pixels from a C program?
  • 10. How much faster is this than the TCL version?
  • ANSWERS

    1. What is a region? A region is a collection of three components: pixel values, header lines, and a mask. Subregions can be sliced from a region and are similar to regions, except that the actual pixel values can not be changed in a subregion. 2. How to I get a region in tcl? The command regNew creates a new region for you. regReadAsFits reads a FITS file into the region. dervish> regReadAsFits [regNew] $INT_DIR/fits/m51.fits h0 The handle "h0" is used to access the region. 3. What pixel types are allowed in regions? The 2-dimensional array may have the following data types: signed integers or unsigned integers; 8, 16, or 32 bits. floating point: 32-bit. 4. How can I find out what is in an existing region? The command regInfoGet lists the basic information: dervish> regInfoGet h0 {nrow 512 } {ncol 512 } {type U16 } {name h0 } {row0 0 } {col0 0 } {modCntr 0 } {isSubReg 0 } {isPhysical 0 } {pxAreContiguous 1 } {hasHeader 1 } {headerModCnt r 1 } {nSubReg 0 } 5. How can I act on pixel values? A set of TCL extensions does this. regSetWithDbl sets all the pixels to the same value. There are verbs for arithmetic (regSub, regAdd, regMult, regDiv) In tcl, you read an individual pixel value with regPixGet. dervish> regNew 100 100 h1 dervish> regSetWithDbl h1 3.14159 dervish> regMultiplyWithDbl 2.0 h1 dervish> regPixGet h1 10 10 6 Note that the default type for pixels is unsigned 16-bit integers. If we want 2 pi more significant digits, we specify the data type when we create the region. dervish> regNew -type=FL32 100 100 h2 dervish> regSetWithDbl h2 3.14159 dervish> regMultWithDbl 2.0 h2 dervish> regPixGet h2 10 10 6.283180 Getting at pixels is very slow with this tcl verb. In general, actions on an entire picture should be done in c, as described below. 6. How can I act on header values? This is done with the set of regHdr... verbs. For example: dervish> regHdrGetAsAscii h0 OBJECT m51 B 600s dervish> regHdrMakeLineWithAscii FLATS DOME1 "We used dome flats 1 " FLATS = 'DOME1 ' / We used dome flats 1 dervish> regHdrInsWithAscii h0 FLATS DOME1 "We used dome flats 1 " dervish> regHdrGetAsAscii h0 FLATS DOME1 dervish> help regHdr . . a complete list of regHdr... commands . . 7. How can I act on mask values? the regMask... verbs are similar to the regPix... verbs. For example: dervish> regMaskSetAsPix h0 10 20 7 8. What other operations are available? Look in help for a description of: regMap, regModeFind, regStatsFind, regGaussiansAdd, regConvolve, regSkyFind. dervish> regSetWithDbl [regNew 100 100] 100 dervish> regGaussiansAdd h0 {40 50 60} {45 55 65} {200 300 200} dervish> regSkyFind h0 99.2892 dervish> help regModeFind regModeFind USAGE: regModeFind region -min -max Histogram all of the pixels in a region and find the most common value. dervish> regModeFind h0 100. dervish> help regStatsFind regStatsFind USAGE: regStatsFind region Find region statistics dervish> regStatsFind h0 {mean 100.439600} {sigma 7.300791} {high 334.000000} {hrow 49} {hcol 54} {low 1 00.000000}{lrow 0} {lcol 0} 9. How do I access the pixels from a C program? First, use shTclRegAddrGetFromName(interp, regName, ®Ptr), which takes a region name (regName) and returns the pointer (regPtr) to that region. Then there are two ways to do this. If you are not uptight about speed, then use: shRegPixGetAsDbl(regPtr, i, j) which returns the value of the pixel at (i,j) as a double, regardless of the pixel data type. If you want to access the pixels directly, then you need to determine the data type (it is in regPtr->type) and then use the correct pointers. For example, if the pixel type turns out to be U16, then the value of pixel (i,j) is regPtr->rows_u16[i][j]. These two methods are illustrated in the subdirectory $INT_DIR/regions, in the files privateTclVerbs.c, dervish_template.c, and Makefile. This defines two new verbs, privateRegAvg and privateRegAvgFast. The timing results are: MYVERB> regSetWithDbl [regNew 100 100] 200 MYVERB> time {privateRegAvg h1} 1000 27300 microseconds per iteration MYVERB> time {privateRegAvgFast h1} 1000 18880 microseconds per iteration So the "fast" version is not even twice as fast. 10. How much faster is this than the TCL version? $INT_DIR/regions/pra.tcl defines the procedure pra: proc pra {handle} { set regInfo [regInfoGet $handle] set regNrow [keylget regInfo nrow] set regNcol [keylget regInfo ncol] set sum 0 loop icol 0 $regNcol { loop irow 0 $regNrow { set sum [expr {$sum + [regPixGet $handle $irow $icol]} ] } } expr { $sum / ($regNrow * $regNcol) } } For comparison: MYVERB> time {pra h1} 100 2545077 microseconds per iteration The "tcl" version is an order of magnitude slower than C versions. Note that this time is for a region that is 100x100 pixels.