====== obj.CopyObject ======

===== Motivation =====
While the object-oriented interface and calling convention for xff objects is suitable in most situations (e.g. a method that alters an object by, for instance, adding a volume-of-interest to a VOI file), there is the occasional need to create a temporary working copy of an object which, once the task is completed, can be discarded. Alternatively, it might be desired to create a derivate object (e.g. a VMR with a spatial filter applied) without changing the source object.

In both these situations, the ''obj.CopyObject'' call brings the desired solution.

===== Reference ('obj.Help('CopyObject')') =====
<file> AFT::CopyObject  - copy object to new
 
 FORMAT:       copied = obj.CopyObject;
 
 No input fields
 
 Output fields:
 
       copied      xff object with own storage in global xffcont
 
 TYPES: ALL</file>

===== Usage example =====
<code matlab obj_copyobject_example.m>% load a VMR
vmr = xff('new:vmr');

% create a copy (does NOT YET double the allocated memory!)
smoothed = vmr.CopyObject;

% smooth VMRData
smoothed.VMRData = uint8(floor(smoothdata3(double(vmr.VMRData), [2, 2, 2])));

% histogram of differences
hist(vmr.VMRData(vmr.VMRData ~= 0) - smoothed(vmr.VMRData ~= 0), 100);</code>

===== Notes =====
Just as mentioned in the example above, due to Matlab's internal (and genially coded) logic, the memory requirements of a copy object are almost 0 (only the pointers in the global struct need a new copy). Only when a member in the copied object (in this case the VMRData field) is altered, will the memory manager of Matlab allocate a new chunk of memory. This is particularly useful if the copied object is only created because some text or other minor alteration is made for compatibility reasons for internal processing!