[272] | 1 | ;+ |
---|
| 2 | ; |
---|
| 3 | ; @file_comments |
---|
| 4 | ; get the land/sea mask array from a NetCDF file |
---|
| 5 | ; |
---|
| 6 | ; @categories |
---|
| 7 | ; Read NetCDF file |
---|
| 8 | ; |
---|
| 9 | ; @param fileid {in}{required}{type=salar string or long} |
---|
| 10 | ; if fileid is a scalar string then it is the name of the file (with |
---|
| 11 | ; the full path) to be opened (in that case, the file will be opened |
---|
| 12 | ; and closed within ncdf_getmask). |
---|
| 13 | ; if fileid is a scalar then it is the id of the file return by a call |
---|
| 14 | ; to ncdf_open outside of ncdf_getmask (in that case, the file will |
---|
| 15 | ; NOT be opened and closed within ncdf_getmask) |
---|
| 16 | ; |
---|
| 17 | ; @keyword ADDSCL_BEFORE {default=0}{type=scalar: 0 or 1} |
---|
| 18 | ; put 1 to apply add_offset ad scale factor on data before looking for |
---|
| 19 | ; missing values when using USEASMASK keyword |
---|
| 20 | ; |
---|
| 21 | ; @keyword INVMASK {default=0}{type=scalar: 0 or 1} |
---|
| 22 | ; Inverse the land/sea mask (that should have 0/1 values for land/sea): mask = 1-mask |
---|
| 23 | ; |
---|
| 24 | ; @keyword MASKNAME {type=string} |
---|
| 25 | ; A string giving the name of the variable in the file |
---|
| 26 | ; that contains the land/sea mask |
---|
| 27 | ; |
---|
| 28 | ; @keyword MISSING_VALUE {type=scalar} |
---|
| 29 | ; To define (or redefine if the attribute is |
---|
| 30 | ; already existing) the missing values used with USEASMASK |
---|
| 31 | ; keyword |
---|
| 32 | ; |
---|
| 33 | ; @keyword USEASMASK {type=scalar string} |
---|
| 34 | ; A string giving the name of the variable in the file |
---|
| 35 | ; that will be used to build the land/sea mask. In this case the |
---|
| 36 | ; mask is based on the first record (if record dimension |
---|
| 37 | ; exists). The mask is build according to : |
---|
| 38 | ; 1 the keyword missing_value if existing |
---|
| 39 | ; 2 the attribute 'missing_value' if existing |
---|
| 40 | ; 3 NaN values if existing |
---|
| 41 | ; |
---|
| 42 | ; @keyword |
---|
| 43 | ; _EXTRA to be able to call ncdf_getmask with _extra keyword |
---|
| 44 | ; |
---|
| 45 | ; @returns |
---|
| 46 | ; the land/sea mask 2D or 3D array or -1 in case of error or mask absence |
---|
| 47 | ; |
---|
| 48 | ; @examples |
---|
| 49 | ; |
---|
| 50 | ; IDL> mask = ncdf_getmask('HadISST1_1m_187001_200702_sst_reg1m.nc',useasmask = 'sst', missing_value = -1.00000e+30) |
---|
| 51 | ; |
---|
| 52 | ; IDL> mask = ncdf_getmask('meshmaskORCA2.nc', maskname = 'tmask') |
---|
| 53 | ; |
---|
| 54 | ; @history |
---|
| 55 | ; August 2007: Sebastien Masson (smasson\@lodyc.jussieu.fr) |
---|
| 56 | ; |
---|
| 57 | ; @version |
---|
| 58 | ; $Id$ |
---|
| 59 | ; |
---|
| 60 | ;- |
---|
| 61 | ; |
---|
| 62 | FUNCTION ncdf_getmask, fileid, ADDSCL_BEFORE = addscl_before, MASKNAME = maskname, USEASMASK = useasmask $ |
---|
[306] | 63 | , MISSING_VALUE = missing_value, INVMASK = invmask, _EXTRA = ex |
---|
[272] | 64 | ; |
---|
| 65 | compile_opt idl2, strictarrsubs |
---|
| 66 | ; |
---|
| 67 | IF NOT (keyword_set(maskname) OR keyword_set(useasmask)) AND keyword_set(romsgrid) THEN maskname = 'mask_rho' |
---|
| 68 | IF NOT (keyword_set(maskname) OR keyword_set(useasmask)) THEN return, -1 |
---|
| 69 | ;---------------------------------------------------------- |
---|
| 70 | ; should we open the file? |
---|
| 71 | IF size(fileid, /type) EQ 7 THEN cdfid = ncdf_open(fileid) ELSE cdfid = fileid |
---|
| 72 | ; what is inside the file |
---|
| 73 | inq = ncdf_inquire(cdfid) |
---|
| 74 | ; name of the variables |
---|
| 75 | namevar = strarr(inq.nvars) |
---|
| 76 | for varid = 0, inq.nvars-1 do begin |
---|
| 77 | invar = ncdf_varinq(cdfid, varid) |
---|
| 78 | namevar[varid] = strlowcase(invar.name) |
---|
| 79 | ENDFOR |
---|
| 80 | ;---------------------------------------------------------- |
---|
| 81 | CASE 1 OF |
---|
| 82 | keyword_set(maskname):mskid = (where(namevar EQ strlowcase(maskname)))[0] |
---|
| 83 | keyword_set(useasmask):mskid = (where(namevar EQ strlowcase(useasmask)))[0] |
---|
| 84 | ENDCASE |
---|
| 85 | ; |
---|
| 86 | if mskid NE -1 THEN BEGIN |
---|
| 87 | mskinq = ncdf_varinq(cdfid, mskid) |
---|
| 88 | ; is the mask variable containing the record dimension? |
---|
| 89 | withrcd = (where(mskinq.dim EQ inq.recdim))[0] |
---|
| 90 | IF withrcd NE -1 THEN BEGIN |
---|
| 91 | ; in order to read only the first record |
---|
| 92 | ; we need to get the size of each dimension |
---|
| 93 | count = replicate(1L, mskinq.ndims) |
---|
| 94 | FOR d = 0, mskinq.ndims -1 DO BEGIN |
---|
| 95 | IF d NE withrcd THEN BEGIN |
---|
| 96 | ncdf_diminq, cdfid, mskinq.dim[d], name, size |
---|
| 97 | count[d] = size |
---|
| 98 | ENDIF |
---|
| 99 | ENDFOR |
---|
| 100 | ; read the variable for the first record |
---|
| 101 | ncdf_varget, cdfid, mskid, mask, count = count |
---|
| 102 | ENDIF ELSE ncdf_varget, cdfid, mskid, mask |
---|
| 103 | ; check if we need to applay add_offset and scale factor |
---|
| 104 | ncdf_getatt, cdfid, mskid, add_offset = add, scale_factor = scl, missing_value = miss |
---|
| 105 | IF n_elements(missing_value) NE 0 THEN miss = missing_value |
---|
| 106 | |
---|
| 107 | IF keyword_set(addscl_before) THEN BEGIN |
---|
| 108 | IF scl NE 1 THEN mask = mask * scl |
---|
| 109 | IF add NE 0 THEN mask = mask + add |
---|
| 110 | ENDIF |
---|
| 111 | |
---|
| 112 | IF keyword_set(useasmask) THEN BEGIN |
---|
| 113 | IF n_elements(miss) NE 0 THEN BEGIN |
---|
| 114 | ; we have to take care of the float accuracy |
---|
| 115 | CASE 1 OF |
---|
| 116 | miss GE 1.e6:mask = mask LT (miss-10) |
---|
| 117 | miss LE -1.e6:mask = mask GT (miss+10) |
---|
| 118 | abs(miss) LE 1.e-6:mask = abs(mask) GT 1.e-6 |
---|
| 119 | ELSE:mask = mask NE miss |
---|
| 120 | ENDCASE |
---|
| 121 | ENDIF ELSE BEGIN |
---|
| 122 | mask = finite(mask) |
---|
| 123 | IF min(mask) EQ 1 THEN BEGIN |
---|
| 124 | ras = report( 'missing or nan values not found...') |
---|
| 125 | mask = -1 |
---|
| 126 | ENDIF |
---|
| 127 | ENDELSE |
---|
| 128 | ENDIF |
---|
| 129 | |
---|
| 130 | mask = byte(round(mask)) |
---|
| 131 | if keyword_set(invmask) then mask = 1b-mask |
---|
| 132 | |
---|
| 133 | ENDIF ELSE mask = -1 |
---|
| 134 | |
---|
| 135 | IF size(fileid, /type) EQ 7 THEN ncdf_close, cdfid |
---|
| 136 | |
---|
| 137 | return, mask |
---|
| 138 | END |
---|