Trace ensemble gathers

Trace gathers are linked sequences of seismic trace ensemles. Ensembles are implemented as objects of class ENSEMBLE; their primary purpose is implementing support for multicomponent seismic data. Similarly to traces, they are practically always accessed using pointers.   Ensembles can combine traces of different types and contain no information other than trace ordering. Class ENSEMBLE provides several identifiers and methods for accessing and manipulating their traces:

ENSEMBLE    *e;

e->num_traces;		// int - the number of traces in the ensemble 

e->first_trace;		// TRACE* - pointer to the first trace of the ensemble

e->last_trace;		// TRACE* - pointer to the last trace of the ensemble

e->next, e->pred;	// ENSEMBLE* - pointers to the preceding and next ensembles 

			// within the same gather

e->sequence;		// GATHER* - pointer to the parent trace ensemble gather

e->add_trace();		// add a trace to the end of the ensemble; formatting of the trace

			// is controlled by the parent ensemble gather

e->add_first_trace();	// add a trace to the beginning of the ensemble; 

			// formatting of the trace

			// is controlled by the parent ensemble gather

e->closed();		// boolean - function that returns TRUE if the last trace in the

			// ensemble has the "last trace" flag set

e->close();		// void - sets the "last trace" 

Similarly to the traces, new ensembles are usually created by their parent objects, trace gathers:

GATHER   *g = SIA_output();

ENSEMBLE *e = g->add_ensemble();	// this adds a trace ensemble to the output gather

Although the call above is possible and may seem appealing, it is not easy to tell from it to which ensemble the trace belongs, what is its sample interval, etc. Such initializations are thus discouraged in application programming.

To delete a trace gracefully (to delete all of its traces, deallocate its memory and to update the parent gather) , use simply:

delete e;

When the last trace in an ensemble is deleted , the ensemble is also removed automatically. Therefore, there is very rarely any need in explicit deletions of ensembles. All ensembles created in the input and output gathers (and that is where you will typically want to create them!) are removed automatically during and after processing.