Concepts: Depth Control

Depth control allows the user to specify the depth at which each object is placed within a frame. The default depth of items can be configured such that certain items always appear at different depths. For instance, label annotations can be set to always appear above curves or contours. Alternatively, items can all be set to the same depth so that the order in which they are added dictates how they overlap.

Management of depths includes the ability to reindex a depth (change a depth to a different value), to collapse depths (merge several depths into a single depth), control the visiblity of individual depths, and list all the objects associated with a particular depth. Additionally, methods exist to allow the user to modify the order of objects within each depth. The depth section of the values concept document lists the values that can be used to set and change the depth of an object.

Setting An Object's Depth

Initial Depth Value

When objects are created, they are assigned a depth value. The depth to which an object is assigned, along with the order that the objects were added to the depth, determines the rendering order of the frame. Depths are rendered from the lowest depth value greater than 0 to the highest depth value in use. Objects within each depth are rendered, by default, in the order in which they were created. The order may be explicitly changed, as explained in the Changing Position within a Depth section.

Each object has a default depth preference value which may be set in the ChIPS resource file or by calling the set_preference function. The value of the preference may be set to "default" or a positive integer value. If the value is default, then default frame depth is used. The value of the frame default is initialized to the value of the default.depth preference, but may be modified by using the set_default_depth command. The new setting does not affect the depth of existing objects, only new ones created after the call to set_default_depth.

# Python
   add_label(100, 200, "Source A", "depth=75")

% S-Lang
   add_label(100, 200, "Source A", "depth=75");

Changing an Exisiting Object's Depth

# Python
   set_axis([id], values)
   set_contour([id], values)
   set_curve([id], values)
   set_histogram([id], values)
   set_label([id], values)
   set_line([id], values)
   set_plot([id], values)
   set_point([id], values)
   set_region([id], values)

% S-Lang
   set_axis([id], values); 
   set_contour([id], values);
   set_curve([id], values); 
   set_histogram([id], values); 
   set_label([id], values); 
   set_line([id], values); 
   set_plot([id], values); 
   set_point([id], values);
   set_region([id], values);

# Python
   set_label(["depth", 50])

   r=ChipsRegion()
   r.depth=34
   set_region(r)

% S-Lang
   set_label({"depth", 50});

   r=ChipsRegion();
   r.depth=34;
   set_region(r);

Each of the set accessors has a help file; refer to "ahelp set_<object>" for more information and examples.

# Python
   set_axis_depth([ChipsId|id], depth)
   set_contour_depth([ChipsId|id], depth)
   set_curve_depth([ChipsId|id], depth)
   set_default_depth([ChipsId|id], depth)
   set_histogram_depth([ChipsId|id], depth)
   set_label_depth([ChipsId|id], depth)
   set_line_depth([ChipsId|id], depth)
   set_plot_title_depth([ChipsId|id], depth)
   set_point_depth([ChipsId|id], depth)
   set_region_depth([ChipsId|id], depth)

% S-Lang
   set_axis_depth([ChipsId|id], depth);
   set_contour_depth([ChipsId|id], depth);
   set_curve_depth([ChipsId|id], depth);
   set_default_depth([ChipsId|id], depth);
   set_histogram_depth([ChipsId|id], depth);
   set_label_depth([ChipsId|id], depth);
   set_line_depth([ChipsId|id], depth);
   set_plot_title_depth([ChipsId|id], depth);
   set_point_depth([ChipsId|id], depth);
   set_region_depth([ChipsId|id], depth);

# Python
   set_line_depth(15)

   set_line_depth("line2", 11)

   id=ChipsId()
   id.line="line1"
   set_line_depth(id, 55)

% S-Lang
   set_line_depth(15);

   set_line_depth("line2", 11);

   id=ChipsId;
   id.line="line1";
   set_line_depth(id, 55);

Retrieving an Object's Depth

The get_<object> accessors return all the attribute values of the object type, including depth. To retrieve just the depth value, provide the attribute name and the id or ChipsId of the object.

# Python
   get_window([ChipsId|id depth)
   get_frame([ChipsId|id depth)
   get_plot([ChipsId|id depth)
   get_axis([ChipsId|id depth)
   get_curve([ChipsId|id depth)
   get_contour([ChipsId|id depth)
   get_histogram([ChipsId|id depth)
   get_label([[ChipsId|id depth)
   get_line([ChipsId|id depth)
   get_point([ChipsId|id depth)
   get_region([ChipsId|id depth])

% S-Lang
   get_window([ChipsId|id depth);
   get_frame([ChipsId|id depth);
   get_plot([ChipsId|id depth);
   get_axis([ChipsId|id depth);
   get_curve([ChipsId|id depth);
   get_contour([ChipsId|id depth);
   get_histogram([ChipsId|id depth);
   get_label([[ChipsId|id depth);
   get_line([ChipsId|id depth);
   get_point([ChipsId|id depth);
   get_region([ChipsId|id depth]);

# Python
   get_line('line2')
   get_label(None, 'depth')

% S-Lang
   get_line("line2");
   get_label(NULL, "depth");

# Python
   get_axis_depth([ChipsId|id])
   get_contour_depth([ChipsId|id])
   get_curve_depth([ChipsId|id])
   get_default_depth([ChipsId|id])
   get_histogram_depth([ChipsId|id])
   get_label_depth([ChipsId|id])
   get_line_depth([ChipsId|id])
   get_plot_depth([ChipsId|id])
   get_point_depth([ChipsId|id])
   get_region_depth([ChipsId|id])

% S-Lang
   get_axis_depth([ChipsId|id]);
   get_contour_depth([ChipsId|id]);
   get_curve_depth([ChipsId|id]);
   get_default_depth([ChipsId|id]);
   get_histogram_depth([ChipsId|id]);
   get_label_depth([ChipsId|id]);
   get_line_depth([ChipsId|id]);
   get_plot_depth([ChipsId|id]);
   get_point_depth([ChipsId|id]);
   get_region_depth([ChipsId|id]);

# Python
   get_label_depth()
   get_line_depth('line2')

   id = ChipsId
   id.line = "line1"
   get_line_depth(id)

% S-Lang
   get_label_depth;
   get_line_depth("line2");

   id = ChipsId;
   id.line = "line1";
   get_line_depth(id);

Listing Objects at a Depth

The info_depth command (Python or S-Lang) provides a means of seeing what objects are at various depths.

# Python
   info_depth( [ChipsId,] [depth] )

% S-Lang
   info_depth( [ChipsId,] [depth] );

The command returns a string that contains each depth accessed and the objects which are at that depth. A depth has been accessed if an object ever resided at that depth, even if there aren't any objects currently set to that depth.

# Python
   info_depth()

   info_depth(100)

% S-Lang
   info_depth;

   info_depth(100);

The "info.depth" preference can be set to display the object depth as "d <depth>" within the info listing. By default, info (Python or S-Lang help) returns all items in the ChIPS hierarchy.

# Python
   set_preference('info.depth', 'true')
   print(info())

% S-Lang
   set_preference("info.depth", "true");
   info;

Changing Position within a Depth

By default, objects within a depth are ordered chonologically based on when they were added to that depth. The objects are stacked with the oldest item at the back of the list and the newest item at the front of the list.

The shuffle command changes the object's position within the stack. Any given object may be shuffled forward or backward one place in the stack or sent directly to the front or back of the stack.

# Python
   shuffle([ChipsId|id], object, manner)

% S-Lang
   shuffle([ChipsId|id], object, manner);

# Python
   shuffle(chips_curve, chips_forward)

% S-Lang
   shuffle(chips_curve, chips_forward);

# Python
   shuffle_axis([ChipsId|id], manner)
   shuffle_contour([ChipsId|id], manner)
   shuffle_curve([ChipsId|id], manner)
   shuffle_histogram([ChipsId|id], manner)
   shuffle_label([ChipsId|id], manner)
   shuffle_line([ChipsId|id], manner)
   shuffle_point([ChipsId|id], manner)
   shuffle_region([ChipsId|id], manner)

% S-Lang
   shuffle_axis([ChipsId|id], manner);
   shuffle_contour([ChipsId|id], manner);
   shuffle_curve([ChipsId|id], manner);
   shuffle_histogram([ChipsId|id], manner);
   shuffle_label([ChipsId|id], manner);
   shuffle_line([ChipsId|id], manner);
   shuffle_point([ChipsId|id], manner);
   shuffle_region([ChipsId|id], manner);

# Python
   shuffle_curve(chips_front)

   shuffle_line("line2", chips_backward)

% S-Lang
   shuffle_curve(chips_front);

   shuffle_line("line2", chips_backward);

Hiding/Displaying a Depth

Each depth within a frame may be displayed or hidden, regardless of whether the depth contains any objects. When a depth is hidden, any objects which are located at that depth become hidden as well. They still exist and will be listed in an info command, but do not appear in the window.

# Python
   hide_depth([ChipsId], depth)

   hide_depth(50)

   display_depth([ChipsId], depth)

   id=ChipsId()
   id.frame="frm2"
   display_depth(id, 100)

% S-Lang
   hide_depth([ChipsId], depth);

   hide_depth(50);

   display_depth([ChipsId], depth);

   id=ChipsId;
   id.frame="frm2";
   display_depth(id, 100);

Reindexing and Collapsing Depths

A depth (and all objects within that depth) can be changed to a different depth value with reindex_depth.

# Python
   reindex_depth([ChipsId|id,] olddepth, newdepth)

   reindex_depth(100, 50)
   reindex_depth("frm1", 50, 65)

% S-Lang
   reindex_depth([ChipsId|id,] olddepth, newdepth);

   reindex_depth(100, 50); 
   reindex_depth("frm1", 50, 65);

The collapse_depths command merges an array of depths into a single new depth. The order in which the depths are specified dictates the order in which the objects are merged into the new depth.

# Python
   collapse_depths([ChipsId], old_depths_array, new_depth)

   collapse_depths([50, 65, 100], 20)

% S-Lang
   collapse_depths([ChipsId], old_depths_array, new_depth);

   collapse_depths([50, 65, 100], 20);