earthobj.m

Univ. of Calgary CREWS的免费地震研究软件

%		river'
%
% There are four other items which are specific to each data field and can be 
% set using the 4 argument syntax for objset. These are:
%
% 'dataname' .... the name of a data field. This is useful when you want to 
%	change the name of an existing data field:
%	myObject = objget(myObject,'dataname','Peace River','peace river');
%		will cause the datafield known as 'peace river' to henceforth
%		be 'Peace River'
%	myObject = objget(myObject,'dataname','Merry Christmas',5);
%		will cause the fifth data field to be named 'Merry Christmas'
% 'datacreate' .... the creation data of a data field. Set automatically by 
%	OBJSET whenever a new data field is added. (See 'objcreate' above 
%	for a description of the date format.)
% 'datamodified' .... the date the data field was last modified. Updated 
%	automatically by OBJSET whenever a datafields values are changed.
%	(See 'objcreate' above for a description of the date format.)
%
% D)  Local and Global Coordinates in Earth Objects 
%
%   Generally, resource exploration requires maps using a global 
% coordinate system such as UTM; however, because these coordinates are 
% typically numbers around a million or more, many numerical algorithms 
% will loose precision or even abort if such coordinates are used. To cope 
% with this problem, Earth Objects are designed to store a local coordinate 
% system, typically numbers between 0 and 100, as well as the information 
% necessary to compute global coordinates whenever necessary. If x and y 
% represent such local coordinates and xgnot, ygnot, xysc, and xyrot are the 
% numbers stored in 'globorigin', 'xyscale', and 'xyrotate' respectively, then 
% the global coordinates xglob and yglob are related to x and y through:
%
%	x = (xglob-xgnot)/xyscale  
%	and  
%	y=(yglob-ygnot)/xyscale ... if xyrot == 0.0
%	
%	or, if xyrot is non-zero:
%	
%	x =  cos(theta)*(xglob-xgnot)/xyscale 
%		+ sin(theta)*(yglob-ygnot)/xyscale
%	and
%	y = -sin(theta)*(xglob-xgnot)/xyscale 
%		+ cos(theta)*(yglob-ygnot)/xyscale
%	where theta = pi*xyrot/180.
%
%   So, the strategy is to store x,y coordinates in the object that are 
% local together with the information necessary to recompute the global 
% coordinates and use objget to obtain the global (or local) coordinates 
% whenever needed.
%
% E) Information Retrieval from Random and Gridded Objects with "objget"
%
% 	itemValue = objget(object, item)
% 	itemvalue = objget(object, item, datanum)
% 	itemvalue = objget(object, item, dataname)
%
%    OBJGET performs the inverse operation to OBJSET in that it 
% retrieves data from an EarthObject (created by RANDOBJ, GRIDOBJ) Most 
% invocations will use the first syntax. 
% Examples: 
%	objget(myobject,'name') ... returns the object's name
%	objget(myobject,'x') ... returns the object's x coordinates
%	objget(myobject,'fred') ... returns the data field named fred
%	objget(myobject,5) ... returns the fifth dataset in the object
%
%   The second syntax is provided to obtain fields specific to of a 
% dataset when only its name or number are known. For example, the name of 
% the 5th dataset is obtained with:
%	objget(myobject,'dataname',5) ... will return the name of the 5th data
%		grid 
% If the returned name is 'peace river' for example, then its last 
% modification date can be obtained by either of:
%	objget(myobject,'datamodified',5); ... 'peace river' is the 5th dataset
%	objget(myobject,'datamodified','peace river'); ... ask for it my name
%
% Argument definitions:
%	object = the EarthObject to be interrogated
%	item = a string identifying the item to be retrieved, or an integer
%		denoting the index of the item. This last case is useful if 
%		a query such as objget( object, 'fieldnames') has first been
%		made to determine the names of available fields in the object.
%		Any field can then be obtained by simply specifying it's number
%		(the first is number 1 etc...)
%	datanum = an integer referring to one of the data fields in the 
%		object. Valid numbers are 1 through m where m is the number 
%		of data fields stored. (and the number of rows returned by 
%		objget(myObject,'namesmatrix') )
%	dataname = a string giving the name of a dataset stored in the 
%		object. Blanks are important: the string 'leduc' will not match 
%		' leduc' or 'leduc '
%
%	itemValue =  the returned value of the item. The form of itemValue
%		may be any of scalar, vector, or matrix depending on what was 
%		stored.
%
%
%    Possible specifications for item strings include any of the 
% following:
% string ........... returned itemValue
% ------------------------------------------------------------
% 'fieldnames' .... a string vector containing the names of the data
%	fields in the object. The names are separated by
%	the | character.
% 'namesmatrix' ... a matrix of strings containing the field names. The
%	names of each data field are rows in the matrix.
% 'objvernum' .... a version number referring to the object software which
%	created the object. Older objects may not work directly with newer 
%	software and will require conversion.
% 'objcreate' .... object creation date returned as a sequence of 6 integers. 
%	The key is: yy mm dd hh mn ss where yy is year, mm is month, dd is 
%	day, hh is hour mn is minute, and ss is seconds. Thus a returned date 
% 	of 1993 11 4 13 20 16 is November 4, 1993 at 1:20:16 pm
% 'objmodified' .... date the object was last modified. 
%	See 'objcreate' above for a description of the date format.
% 'objtype' .... short string giving the object type (grid or rand etc)
% 'datatype'.... short string giving the data type (seis, mag, grav etc)
% 'username' .... 6 character string giving a user id assicuated with the 
% 	object
% 'name'.... possibly long string giving the object name
% 'xaxisname' ... max of 10 characters giving the name of the x axis
% 'yaxisname' ... max of 10 characters giving the name of the y axis
% 'north' ... azimuth angle in degrees of true north. 0 is along the
%	x axis and 90 along the y axis
% 'east' ... azimuth angle in degrees of true east.
% 'datacols'.... the number of columns in the data matrix
% 'datarows'.... the number of rows in the data matrix
% 'delx'.... the spacing between columns in physical units (local coords)
%	Not relevent for Random objects
% 'dely'.... the spacing between rows in physical units (local coords)
%	Not relevent for Random objects
% 'xnot'... the coordinate of the first column in physical units (local coords)
%	Not relevent for Random objects
% 'ynot'.... the coordinate of the first row in physical units (local coords)
%	Not relevent for Random objects
% 'globorigin' .... a vector of length 2 giving the coordinates of the first row 
%	and column in global coordinates
% 'xyscale' .... a scalar giving the scale factor between local and global 
%	coordinates.If local coordinates are kilometers and global are 
%	meters, then this should be 1000.
% 'xyrotate' .... a scalar giving the rotation angle between local and global 
%	coordinates in degrees
% 'x' .... a vector of the local column coordinates in physical units
%	For gridded objects, this is generated automatically from xnot and 
%	delx. For random objects, it is only available if a dataset named 'x' 
%	has been set.
% 'xglobal' .... a vector giving the global column coordinates.
% 'y' .... a vector of the local row coordinates in physical units
%	For gridded objects, this is generated automatically from xnot and 
%	delx. For random objects, it is only available if a dataset named 'x' 
%	has been set.
% 'xglobal' .... a vector giving the global column coordinates.
% 'xg' ... a grid the same size as the data with the local x coordinates 
%          of each point. Only available for gridded objects
% 'yg' ... a grid the same size as the data with the local y coordinates 
%          of each point. Only available for gridded objects
%
% Additionally, any of the strings returned by 'fieldnames' or 'namesmatrix' 
% maybe used as item strings. For example, suppose 
% objget(myObject,'fieldnames')
% returns the string: wabamun|peace river|leduc|nordegg. Then, the dataset 
% named 'peace river' may be stored in the Matlab variable z by either of
%	z = objget(myObject,'peace river'); ... ask for it by name
%	z = objget(myObject,2); ... because its the second dataset
%
% There are four other items which are specific to each dataset and can be
% retrieved using the 3 argument syntax for objget. These are:
% 
% 'dataname' .... the name of a dataset. This is useful when you know the 
%	sequential dataset number and need the name. For example, using the 
%	object referred to above, 
%	objget(myObject,'dataname',3) 
%	will return the string 'leduc'
% 'datacreate' .... the creation data of a dataset.
%	(See 'objcreate' above for a description of the date format)
% 'datamodified' .... the date the dataset was last modified.
%	(See 'objcreate' above for a description of the date format.)
% 'protect' ... the data protection flag. 1 indicates the dataset is protected 
%	and may not be overwritten, while 0 indicates no protection. Of 
%	course, protected data can be unprotected using objset.
%
% A copy of this documentation may be found in the following text file:
%	~vgmar/matlab/earthobj.txt
%
% For further information contact Gary Margrave, CREWES Project, University
% of Calgary
%
% NOTE: It is illegal for you to use this software for a purpose other
% than non-profit education or research UNLESS you are employed by a CREWES
% Project sponsor. By using this software, you are agreeing to the terms
% detailed in this software's Matlab source file.
 
% BEGIN TERMS OF USE LICENSE
%
% This SOFTWARE is maintained by the CREWES Project at the Department
% of Geology and Geophysics of the University of Calgary, Calgary,
% Alberta, Canada.  The copyright and ownership is jointly held by 
% its author (identified above) and the CREWES Project.  The CREWES 
% project may be contacted via email at:  [e-mail]
% 
% The term 'SOFTWARE' refers to the Matlab source code, translations to
% any other computer language, or object code
%
% Terms of use of this SOFTWARE
%
% 1) Use of this SOFTWARE by any for-profit commercial organization is
%    expressly forbidden unless said organization is a CREWES Project
%    Sponsor.
%
% 2) A CREWES Project sponsor may use this SOFTWARE under the terms of the 
%    CREWES Project Sponsorship agreement.
%
% 3) A student or employee of a non-profit educational institution may 
%    use this SOFTWARE subject to the following terms and conditions:
%    - this SOFTWARE is for teaching or research purposes only.
%    - this SOFTWARE may be distributed to other students or researchers 
%      provided that these license terms are included.
%    - reselling the SOFTWARE, or including it or any portion of it, in any
%      software that will be resold is expressly forbidden.
%    - transfering the SOFTWARE in any form to a commercial firm or any 
%      other for-profit organization is expressly forbidden.
%
% END TERMS OF USE LICENSE