functions in cubeview.i -
cubeview
|
cubeview,data Cubeview is an almost graphical package base on the Tiny Widget Set (TWS), intended to allow easy access to spectroimaging data, or any 3D data. The only mandatory argument, DATA, is either a 3D array, or the name of a FITS file containing such a cube. The spectral dimension must be the third. Actually if you don't specify DATA, the program will let you try to select a file, which is really fine only under ytk, in which case the tcl/tk file selection box is used. I don't find the text-only file selection helper really useable. Cubeview uses three windows, selectable through optional keywords: slice_wid=(0) : the slice window spectrum_wid=(1): the spectrum window cmd_wid=(2) : the command window, or tool bar. So Cubeview displays a slice of the cube, which is really an image made as the sum of a few planes of the cube and a spectrum, which is the sum of a few individual spectra. The slice can also be an RGB image if you click on "3 color slice". The third window is used to display a few buttons. The labels should be self-explanatory, but you can get help by right clicking on one of the buttons. Some buttons, like the ones that let you select the spectrum or the slice, remain active (the text of the button is then blue) untill you finish the action by either right-clicking in the relevant window, or clicking any button in any non-relevant window. The "Slice properties" and "Spect. properties" buttons are a little special: when they are clicked, the command window is replaced by a dialog box in which you can choose some eye candy properties for the slice display, and the axis type for the spectra. There's no context help available in these window, right clicking them reverts to the normal command box. Using the graphical frontend to cubeview disables Yorick's standard zooming abilities. You can suspend Cubeview by clicking on the appropiate button to re-enable them, or to perform any task on yorick's command line (like make a hardcopy of the windows...). You then go back to your running Cubeview session by typing "cv_resume", or "cv" which is an alias to cv_resume. The "limits" set this this way are kept whil running cubeview, that may not be what you want. You can free the limits again, or only the Y axis limits of the spectra, by clicking the appropriate buttons. Cubeview now supports hooking user function to its drawing routines. See source of cv_*_hook for sample usage. See CV_LIBRARY for documentation about the internals. All defaults can be set through cv_defaults, and overriden passing keywords to cubeview. These keywords are the member names of the struture type CV_Interns. KEYWORDS: see CV_Interns, see postinit in cv_init. | |
SEE |
ALSO:,
cv_library,,
cv_init,,
cv_defaults,,
CV_Defaults,, cv_interns, |
cv_3colslice
|
cv_3colslice & Cubeview's "3 color slice" radio button If you click on this button or call this routine, all slices from then on will be of type "3 color". See cv_normalslice & Cubeview's "Normal slice" radio button. |
cv_blank
|
cv_blank Puts zeros in the currently selected 3D box. Useful for cleaning. |
cv_circmas
|
cv_circmas(sx,sy,x0,y0,r,inv=) returns a circular mask, i.e. a 2D array MASK of size SXxSY, of type int, such that for any (x,y), - if INV is not set (or null): (MASK(x,y)==1) <=> sqrt((x-x0)^2+(y-y0)^2)<=r. - if INV is set, (MASK(x,y)==1) <=> sqrt((x-x0)^2+(y-y0)^2)>r; |
cv_cmd_win_init
|
cv_cmd_win_init Initializes Cubeview's almost graphical user interface. Not a user function: is intended to be called by CUBEVIEW. |
cv_current_zaxis
|
cv_current_zaxis() Returns as a vector the spectral axis currently used by Cubeview, considering the current state of cv_interns.zaxistype. |
cv_cutreg
|
cv_cutreg On Cubeview's slice window (CV_INTERNS.SLICE_WID), select with mouse rectangular area which contrast is to be maximized. | |
SEE ALSO: | cv_cutsel, cv_cutregonce, cv_library |
cv_cutregonce
|
cv_cutregonce or cv_cutregonce,x0,y0,x1,y1 Adjust contrast on the output image by setting its min/max value to min/max of selected square region, specified by corners (x0,y0) and (x1,y1). If not specified, the entire image is used. Then redraws the slice. | |
SEE ALSO: | cv_cutreg, cv_library |
cv_cutsel
|
cv_cutsel On Cubeview's slice window (CV_INTERNS.SLICE_WID), click from minimum pixel to maximum pixel to draw. | |
SEE ALSO: | cv_cutreg, cv_library |
cv_defaults
|
cv_defaults Instance of CV_Defaults defining defaults for Cubeview. cv_defaults=CV_Defaults(slice_wid=0, sp_wid=1, cmd_wid=2, depth=24, origin=[1,1,1], scale=[1,1,1], overs=1, slboxcol=248, zwlwise=0, sltype="Normal", slpalette="stern.gp", slinterp="spline", zaxistype="PIX", refwl=2.166120, pixel=1); | |
SEE ALSO: | CV_Defaults, cubeview, cv_library |
CV_Defaults
|
CV_Defaults struct CV_Defaults /* DOCUMENT CV_Defaults Structure to handle defaults for cubeview. The members are the ones of CV_Interns for which setting a default makes sense. The external variable cv_defaults is normally the only variable of type CV_Defaults. You may set defaults by accessing this variable, that is erased when you #include cubeview. { long slice_wid,sp_wid,cmd_wid,depth; double origin(3),scale(3),overs,vlsr,spsmooth,slsmooth,blank,xyaspect; char slboxcol,zwlwise,pixel; string sltype,slpalette,slinterp,hook,aperture_type; GraphK spkeywords; } |
cv_freeylimits
|
cv_freeylimits Frees Y limits, hence the name... Indeed, calls LIMITS to uset every limits, then sets back X limits. Very useful if you've set limits using the mouse and want to explore data only within the selected range. Normally called through cubeview's "Spectrum Y limits" button. |
cv_gauss_smooth
|
sm=cv_gauss_smooth(sp,fwhm) Gaussian smoothing of a spectrum or image. | |
SEE ALSO: | box_smooth |
cv_graphicwindows
|
cv_graphicwindows : redraw Keywords: NOKILL: if set, the windows are not killed and re-initialized. EXTRACT: re-extract spectrum and slice. |
cv_handler
|
cv_handler(uname,button) Cubeview event handler. Not a user function, normally called only by TWS_HANDLER. |
cv_help
|
cv_help =help,cubeview |
cv_init
|
cv_init,"file.fits" or cv_init,3D_array It's probably better not to call directly CV_INIT and let the almost graphical tool CUBEVIEW do it. Initiates Cubeview. If called with a fits file name, includes "fits.i" and reads the file. Feeds all items of the external variable CV_INTERNS, and displays a first slice and a first spectrum. After, you could use cv_spsel and cv_slsel. Cubeview has a kind of graphical user interface that can be launched with "cubeview,data", or "cv_resume" once CV_INIT has been called. cv_init takes as keyword any member of CV_Defaults, override the defaults. In addition to this, cv_init will include any .i file specified as POSTINIT keyword. | |
SEE ALSO: | cubeview, cv_library, cv_defaults |
cv_interns
|
extern cv_cube, cv_interns cv_cube is an external variable holding the data cube being viewed in Cubeview. cv_interns is a structure of type CV_Interns, containing all other variables shared by Cubeview routines. cv_valids is a mask indicating which cells in cv_cube are valid data. It is used to speed up various treatments, unless the cube "isbig". The most usefull items for the user are .slice and .spectrum, pointers to eponym arrays. .spbox is a 4 elements array containing the coordinates of the corners of the region defining the spectrum aperture, and likewise .sllims contains the limits of the spectral region defining the slice. .slice is either a NxM indexed color array, or a 3xNxM RGB array. | |
SEE ALSO: | CV_Interns, cubeview, cv_library |
CV_Interns
|
CV_Interns struct CV_Interns { /* DOCUMENT CV_Interns: structure type use internally by cubeview. { pointer slice; // pointer to the current slice, either indexed color or RGB, // so either NxM or 3xNxM. pointer spectrum; // pointer to the current spectrum, of size P. pointer zaxis; // spectral axis, in pixels pointer waxis; // wavelength spectral axis, in microns pointer faxis; // frequency spectral axis, in cm-1 pointer vaxis; // velocity spectral axis, in km/s pointer root; // pointer to cubeview's TWS_Root widget. See tws.i and // tws_root.i long slice_wid,sp_wid,cmd_wid; // Cubeview windows identifiers long sllims(2); // indices of the first and last z-planes of the current slice long depth; // depth of the slice image in 3 color mode: 8 or 24 long big_size; // if cubes has more voxels than that, sopme treatements will // be memory-optimized. double spbox(4); // integer pixel coordinates of the spectrum aperture if rectangular or square, center x, center y, radius and nothing if circular double cmin,cmax; // lower and upper cut for displaying the slice double origin(3); // 3D position of the data cell (1,1,1) in you prefered // coordinate system double scale(3); // scales of the data in the three // dimensions double slpos(4); // "real world" coordinates of the 4 corners of the field double overs; // oversampling factor to display the slice double refwl; // reference wavelength in microns for conversion into velocity double vlsr; // true "systemic" velocity in the local standard of rest if its observed velocity is 0. double spsmooth ; // smoothing box for the displayed spectrum double slsmooth ; // smoothing box for the displayed slice char slboxcol; // color index to draw the box inicating the slice bandpass // when in normal mode char zwlwise; // 0 zaxis is frequency-wise, 1 if it is wavelength-wise string sltype; // String containing the type of slice, either "Normal" or "3 // color". Used by most cv_ routines that access the slice. string slpalette; // palette to use for the slice when in normal mode string zaxistype; // type of Z-axis to use: "PIX", "WAVE", "FREQ" or "VELOCITY" string slinterp; // use interp or spline to interpolate? spline is much better // and... slower. Should not be a problem, except if you // work on really big data. string aperture_type; // rectangular, square, circular string hook; // name of a function to call from time to times (basically each // time a window is updated). Format not well defined yet. One // (or several?) general interest hook is provided. See cv_*_hook. GraphK spkeywords; // graphic keywords to plot the spectra. See graphk.i. double xyaspect; // aspect ratio X/Y of the viewport in the slice window. // by default, depends on the dimensions of the data. // Set to 0 for this behavior, or to a scalar. } |
cv_library
|
cubeview, cv_init, cv_spsel, cv_slsel, cv_cutsel and cv_cutreg are the main user level routines. Cubeview is a set of routines intended to ease visualization of spectroimaging data. It is consistant in its goals with the eponym IDL package from the BEAR project. cubeview,data starts an almost graphical user interface. If you just want to look at 3D data, just kick it off, and right-click buttons to get context help. Left click them to use them. Data are shared between routines through an external variable, cv_interns, of type CV_Interns. Function names begin with "cv_". Defaults are defined in an external variable, cv_defaults, of type CV_Defaults. The main goal is to display both a slice and a spectrum in two windows. It is possible to hook a user routine to some events. To do this, just set cv_interns.hook to a string containing the name of the user routine (say, "MyHook"). This can be done by means of the HOOK keyword to cubeview and cv_init. Each time a cv_ function that supports hooking is called, the user function with get called with the name of the caller routine as a single argument: for instance MyHook("cv_spdraw") whenever the spectrum gets redrawn. The user function should make use of cv_interns to get any data it needs. Grep the source for cv_callhook to find out which routines support hooking. Main routines: cv_init,data: initiates external variables and windows. Data should be either a FITS file name or a 3D data cube. cv_spsel: select spectrum in a rectangular area with mouse. cv_slsel: select slice on the spectrum with mouse. cv_cutsel: select minimum and maximum value to show (see CMIN and CMAX in bytscl). cv_cutreg: enclose a rectangular area with mouse, CMIN and CMAX will be min and max in this area. cv_cutregonce: same as cv_cutreg, but just once and not interactively. Intermediate level routines: cv_slextract,begin,end: explicitely extract a slice from plane BEGIN to plane END cv_spextract,corners: explicitely extract a spectrum from a given rectangular aperture cv_sldraw and cv_spdraw: explicitely redraw slice or spectrum. Can extract as well. cv_slwin and cv_spwin: explicitely select slice or spectrum window. cv_cutregonce: same as cv_cutreg, but just once and not interactively. Helper routines: cv_slpnm,filename: write the current slice to a PNM file. cv_blank: "blank" selected volume (setting it to the value specified by the BLANK card of the fits file). For the low level routines, use the source. Cubeview GUI is based on the Tiny Widget Set (TWS). Note: cv_library itself is a function that does nothing more than showing its own DOCUMENT comment. | |
SEE ALSO: |
cubeview,
cv_interns,
cv_defaults,
CV_Interns, CV_Defaults, cv_library |
cv_newrefwl
|
cv_newrefwl,refwl Change Cubeview's reference wavelength: set cv_interns.refwl and *cv_interns.vaxis. |
cv_normalslice
|
cv_normal slice & Cubeview's "Normal slice" radio button If you click on this button or call this routine, all slices from then on will be of type "Normal", that is standard Yorick indexed color image. See cv_3colslice & Cubeview's "3 color slice" radio button. |
cv_plfi
|
cv_plfi,im cv_plfi,im,x1,y1 cv_plfi,im,x0,y0,x1,y1 Draws an RGB image using plf. Syntax similar to PLI, except im has to be 3xNxM of thype char (an RGB image). This is to work around a bug that prevents RGB images from being properly output to eps (or ps or epsi...) when using pli. | |
SEE ALSO: | plf, pli |
cv_pnm
|
cv_pnm,"filename" Writes current slice to pnm file. |
cv_popup2_init
|
cv_cmd_win_init Initializes Cubeview's almost graphical user interface. Not a user function: is intended to be called by CUBEVIEW. |
cv_popup2_init
|
cv_popup_init,cv_popuphandler & Cubeview's "Spect. properties" button Clicking on the button in Cubeview's command window makes this window be replaced by a dialog box allowing to set a few parameters for spectrum display: type of Z axis, reference wavelength. You get out of this dialog box by right clicking in it (there is no context help there). | |
SEE ALSO: |
cubeview,
cv_interns,
cv_defaults,
cv_library |
cv_popup2handler
|
cv_popuphandler(uname,button) Cubeview event handler for a popup. Not a user function, normally called only by TWS_HANDLER. |
cv_popup_init
|
cv_popup_init,cv_popuphandler & Cubeview's "Slice properties" button Clicking on the button in Cubeview's command window makes this window be replaced by a dialog box allowing to set a few parameters for slice display: oversampling factor, depth of "3 color" slice (8 or 24), and palette for "normal" slice. You get out of this dialog box by right clicking in it (there is no context help there). | |
SEE ALSO: |
cubeview,
cv_interns,
cv_defaults,
cv_library |
cv_popup_init
|
cv_cmd_win_init Initializes Cubeview's almost graphical user interface. Not a user function: is intended to be called by CUBEVIEW. |
cv_popuphandler
|
cv_popuphandler(uname,button) Cubeview event handler for a popup. Not a user function, normally called only by TWS_HANDLER. |
cv_putslbox
|
cv_putslbox Displays a colored box representing the spectral region corresponding to the slice in Cubeview's spectral window. |
cv_putspbox
|
cv_putspbox Puts a box arround the region defining the current spectrum in cubeview's slice window. |
cv_readbb
|
box=cv_readbb(filename) returns bounding box of an eps file. |
cv_rgb2indexed
|
cv_rgb2indexed, image, red, green, blue Converts RGB image to indexed color image. This function is identical to pnm_display in pnm.i, except it does not plot, but returns the image and palette components. This routines intends not to touch the display in anyway (for instance it does not set the palette.) RED, GREEN and BLUE are returned arrays to feed PALETTE with. (Unlike in PNM_DISPLAY, they are not returned in an external variable.) | |
SEE ALSO: | pnm_display, cv_library |
cv_rgbeps
|
cv_rgbeps & Cubeview "Slice -> epsi" button. cv_rgbeps,prefix In the second form, outputs Cubeview's current slice to an epsi file PREFIX.epsi (.epsi is appended to PREFIX). In the first form, prompts for PREFIX and performs. When prompted, action is canceled if you type "cancel" as a prefix. cv_rgbeps uses a number of external programs, so works only on UNIX, if the programs are installed: convert (from ImageMagick), jpeg2ps, latex, dvips and ps2epsi. A number of temporary files are written, but not deleted: (in the following, ~ means PREFIX) ~_axes.ps, ~_im.pnm, ~_im.jpg, ~_im.eps, ~.tex, ~.aux, ~.dvi, ~.ps and ~.epsi. The file your looking for is PREFIX.epsi. Afterwards, you can modify PREFIX_im.eps and run latex on PREFIX.tex again... So the intermediate files can come in handy. And as a side effect, you also get pnm, jpg and eps versions of the image without the axes... The point of all this is that, at least on my machine, Yorick does not produce good RGB eps files, or I don't know how to do it. So I cheat a little bit. By the way, this is mostly usefull for 3 color slices. It works on normal slices, producing RGB eps (using pnm_colorize), that may or may not be what you want. For normal slices, I suggest suspending Cubeview, switching to the slice window with CV_SLWIN, and using the standard EPS function. Note that you can also tell Cubeview to display 3 color images at 8 bit depth (by setting cv_interns.depth to 8 instead of 24). In that case, running EPS manually as mentioned above works great. The colors may be less impressive when a large dynamic is needed, but this way you can also get the spectrum window with its nice rainbow slice box... So in a word, this is here to take care of the most complicated case, but there are other simpler means to get the picture, that may be preferable in most cases. Here is a cookbook to get things at 8bit depth: 1) get your picture interactively at 24bit depths, including the cuts. 2) suspend Cubeview. 3) switch to 8bit depth: cv_interns.depth=8 (3bis: at this point, you may notice that the cut aren't to great, you can resume Cubeview(cv) to fix them, and suspend again. Screen update does not work to great at 8bit though) 4) redraw both windows: cv_graphicwindows 5) zoom in with the mouse if you whish... 6) switch to slice window: cv_slwin 7) dump it to eps file: eps,"filename_slice" 8) switch to spectrum window: cv_spwin 9) dump it to eps file: eps,"filename_spectrum" 10) get back to 24bit display: cv_interns.depth=24 ; cv_graphicwindows; 11) resume Cubeview: cv |
cv_save_sel
|
NT cv_save_sel, filename Save the subecube currecntly selected in cubeview (both spectral and spatial dimension) to file FILENAME, updating the FITS header if possible. |
cv_sldraw
|
cv_sldraw Displays current Cubeview slice (CV_SLICE) in the right window (pointed at by CV_SLICE_WID). Displays a box around the spectrum region. |
cv_slextract
|
cv_slextract,begin,end Extracts new Cubview slice (*CV_INTERNS.SLICE) by summing up CV_CUBE planes from range BEGIN to range END. Updates a few items in CV_INTERNS, and can also return the slice. If cv_interns.sltype=="3 color", the slice is a 3xNxM array, all 3 planes being sums of CV_CUBE planes from BEGIN to END with different ponderations. This keeps some velocity information in the image displayed... (blueshifted regions can appear in blue and so...) |
cv_sllims
|
cv_sllims & Cubeview's "Slice limits" button Sets the limits of Cubeview's slice window so that the full field is viewed, with squared pixels, and east on the left. |
cv_slpnm
|
cv_slpnm Write current slice, affected by current cuts and palette (for a "Normal slice"), to an RGB PNM file (PPM), using PNM_WRITE. The box is saved in "axes_"+filename+".epsi", so that you can get the original image with axes using xfig for instance, so LaTeX programming would probably be better. For this kind of purpose, I recommend using any tool to convert the slice to JPEG, then jpeg2ps. That allows to keep JPEG compression for the bitmap part. |
cv_slsel
|
cv_slsel, Cubeview's "Select slice" button Choose rectangle on Window 0 with left mouse button, extracts corresponding splice CV_INTERNS.SLICE from CV_INTERNS.DATA, draws it to window CV_INTERNS.SLICE_WID. CV_SLSEL loops until you hit any other button than the left in the slice window, or any button in any other window. |
cv_slwin
|
cv_slwin Switches to windows CV_INTERNS.SLICE_WID |
cv_spdraw
|
cv_spdraw Displays current Cubeview spectrum (*CV_INTERNS.SPECTRUM) in the right window (pointed at by CV_INTERNS.SP_WID). Displays the spectral region defining the slice on a colored background. |
cv_spextract
|
cv_spextract,corners Extracts new Cubeview spectrum (*CV_INTERNS.SPECTRUM) by summing up *CV_INTERNS.DATA spectra included in rectangular area difined by CORNERS=[X0,Y0,X1,Y1]. Updates CV_INTERNS accordingly. |
cv_spsel
|
cv_spsel, Cubeview's "Select spectrum button". Choose rectangle on Window 0 with left mouse button, extracts corresponding spectrum *CV_INTERNS.SPECTRUM from CV_CUBE, draws it to window CV_INTERNS.SP_WID. CV_SPSEL loops until you hit any other window. |
cv_spwin
|
cv_slwin Switches to windows CV_INTERNS.SP_WID |
cv_suspend
|
Cubeview SUSPEND button. Click button to suspend Cubeview. You can resume afeterwards using CV_RESUME. |
cv_tws
|
cv_tws or cv Resume a Cubeview almost graphical user interface session. While the event handler is runing, you don't have access to the command line to do anything not implemented in the GUI. Cubeview allows you to suspend a session by right clicking in its toolbar, and resume whenever you want by calling this simple routine. It may not work if you do weird things such as trying to run another session of Cubeview or any other TWS base software (that is only Cubeview for now...) If the keyword GRAPHIC_WINDOWS is set to a non zero value, then the slice and spectrum windows are reset, which is not a good idea if you've just spent half an hour trying to get the best zoom. cv is an alias to cv_resume |
cv_ui
|
cv_ui = "gtk" or cv_ui = "tws" or cv_ui = "text" Which ui should cubeview use? This is the initial default, the last one used is remembered for the duration of the session. |
cv_vpaspect
|
cv_vpaspect,x,y or cv_vpaspect,x/y or cv_vpaspect,data Set the viewport of current graphic window so that it has the appropriate aspect ratio to display an XxY image. In the third form, data may be a 2-or-more dimensional array, and it is equivalent to cv_vpaspect,dimsof(data(2)),dimsof(data(3)). Note that the new viewport always fits in the old one, so that the viewport gets smaller and smaller as you set it again and again with cv_vpaspect. Use vpset to change the size of the viewport. | |
SEE ALSO: |
vpset,
coords,
i,
style,
i,
get_style,
set_style |
cv_zoom
|
cv_zoom A zoom similar to that provided directly by yorick. left, middle and left click zoom-in, pan and soom-out respectively; when control is hold, button 1 zooms on drawn rectangle, buttons 2 and 3 zoom out so that viewport is downscaled to drawn rectangle (unlike default zoomer). When control is hold, normal zoom is perform dragging low-left to high-right: other combination cause one or both of the axes to be inverted (unlike default zoomer). Click in another window to stop. See also: limits |
round
|
long=round(float) // from mathbast.i Acts as expected : return long(x+0.5*((x>0)*2-1)); |