Page Frame Bounds

This section describes the coordinate systems used by Tioga for page layout.

The "output page" is defined in "output coordinates" having units equal to 1/720 of an inch. This unit is 1/10 of a "big point" that is the basic size used in PostScript and PDF. By making the unit this size, we can write output coordinates to the PDF file as integers, getting a significant size reduction in the file without giving up noticable accuracy. The (0, 0) point of the output coordinate system is at the lower-left hand corner of the output page. The x axis increases horizontally, and the y axis increases vertically. The dimensions of the page are given by the attributes page_width and page_height. The attributes page_right and page_top are aliases for these. The attributes page_left and page_bottom are always zero. The default page size is 5 inches square, but you can set the size to anything you like using the set_device_pagesize routine.

While the output coordinates have a fixed physical size, all the other coordinate systems are relative rather than absolute. At the next level comes "page coordinates" that are defined relative to the output page with (0, 0) in page coordinates at the lower left corner of the output page and (1, 1) at the upper right. Page coordinates are used to define the location of the current "frame". The current frame location is held in the attributes frame_left, frame_right, frame_top, and frame_bottom, all in page coordinates. In addition, the attribute frame_width is defined to be frame_right - frame_left, and frame_height is frame_top - frame_bottom. The defaults are (0.2, 0.2) for the lower left corner of the frame and (0.8, 0.8) for the upper right. You can change these by calling the routine set_frame_sides.

The "frame coordinates" are defined with (0, 0) at the lower left corner of the frame and (1, 1) at the upper right. Subframes are sized and located using frame coordinates. The routine set_subframe does this job. In addition, subframes are used to give a desired aspect ratio. The routine set_aspect_ratio_relative_to_frame does this in terms of frame coordinates — in other words, it creates a subframe having the requested ratio of width to height relative to the frame. In some cases that will be what you want, but it is more common to want to specify the width to height ratio relative to the output page, i.e., in absolute rather than relative terms. This is provided by the routine set_physical_aspect_ratio (with set_aspect_ratio as an alias).

When doing a plot, you want yet another coordinate system, one that matches the data. This is called the "figure coordinate system" and is set by the "bounds" attributes that give the locations in figure coordinates of the edges of the frame. These attributes are called bounds_right, bounds_left, bounds_top, and bounds_bottom. Note that you can "reverse" the x axis, for example, by making bounds_right smaller than bounds_left. To help with the bookkeeping for this, the attribute bounds_xmin holds the minimum of bounds_left and bounds_right, while bounds_ymin has the minimum of bounds_top and bounds_bottom. Finally, bounds_width holds the absolute value of bounds_right - bounds_left and bounds_height has abs(bounds_top - bounds_bottom). The default bounds are 0 for left and bottom and 1 for right and top, making figure coordinates identical to frame coordinates. The bounds can be changed by calling the set_bounds routine.

FigureMaker methods

set_device_pagesize(width, height) [ doc ]

Set device page size

INPUTS

  width, height -- measured in output page coordinates (1/720
                   inch)

The page coordinates go from 0.0 to 1.0 with (0, 0) at the
lower left and (1, 1) at the upper right.  This method sets
the physical size of this rectangle in the output coordinate.

set_frame_sides(left, right, top, bottom) [ doc ]

This command sets `self.frame_left`, `self.frame_right`,
`self.frame_top`, and `self.frame_bottom` to the given
values, in page coords (0 ... 1).

set_subframe(left=0.0, right=0.0, top=0.0, bottom=0.0) [ doc ]

Adjusts frame margins according to the entries in the
dictionary argument.  Note that this does not automatically
adjust the clipping rectangle to the new frame.  If you want
the clipping changed, call `clip_to_frame()` after calling
`set_subframe()`.

column_margins(left_margin=0.0, right_margin=0.0, column_margin=0.0, column=None, first_column=1, last_column=None, num_columns=None) [ doc | example ]

Compute left and right margins for `set_subframe()`

INPUTS

  left_margin
          -- default is 0
  right_margin
          -- default is 0
  column_margin
          -- default is 0
  column  -- an int
  first_column
          -- default is 1
  last_column
          -- default is `first_column`
  num_columns
          -- default is `last_column`

Returns a dict with entries for 'left' and 'right' suitable
for use with `set_subframe()`.  The margins are determined by
the column specifications given in the input argument.  The
leftmost column is number 1 and the number of columns equals
the column number for the rightmost column.  The entries
`left_margin` and `right_margin` determine the space outside
the columns, and `column_margin` is the space between columns,
all given as fractions of the frame width.  The space between
the outer margins is divided to make room for `num_columns` of
equally wide columns.  The returned margins bracket the
requested `column`, or the requested range of columns from
`first_column` to `last_column`, inclusive.  See also
`row_margins()`.

Example

def columns(t):
    read_data(t)
    t.set_aspect_ratio(2)
    t.rescale(0.8)
    t.do_box_labels('Position', 'Values for Colors', 'Blues, Reds, Greens')
    num_plots = 3
    def pblues(t):
        t.right_edge_type = AxisHidden
        blues(t)
    t.subplot(pblues, **t.column_margins(num_columns=3, column=1))
    def preds(t):
        t.yaxis_type = AxisWithTicksOnly
        t.right_edge_type = AxisHidden
        reds(t)
    t.subplot(preds, **t.column_margins(num_columns=3, column=2))
    def pgreens(t):
        t.yaxis_type = AxisWithTicksOnly
        t.right_edge_type = AxisWithTicksOnly
        greens(t)
    t.subplot(pgreens, **t.column_margins(num_columns=3, column=3))

row_margins(top_margin=0.0, bottom_margin=0.0, row_margin=0.0, row=None, first_row=1, last_row=None, num_rows=None) [ doc ]

Compute top and bottom margins for `set_subframe()`

INPUTS

  top_margin
          -- default is 0
  bottom_margin
          -- default is 0
  row_margin
          -- default is 0
  row     -- an int
  first_row
          -- default is 1
  last_row
          -- default is `first_row`
  num_rows
          -- default is `last_row`

Returns a dict with entries for `top` and `bottom` suitable
for use with `set_subframe()`.  The margins are determined by
the row specifications given in the input argument.  The
uppermost row is number 1 and the number of rows equals the
row number for the bottom-most row.  The entries `top_margin`
and `bottom_margin` determine the space above and below the
rows, and `row_margin` is the space between rows, all given as
fractions of the frame height.  The space between the outer
margins is divided to make room for `num_rows` of equally tall
rows.  The returned margins bracket the requested `row`, or
the requested range of rows from `first_row` to `last_row`,
inclusive.  See also `column_margins()`.

set_bounds(left, right, top, bottom) [ doc ]

Set the bounds according to the given figure coordinates

The values of the entries are the figure coordinates for the
edges of the frame.  The following attributes are changed:
`self.bounds_left`, `self.bounds_right`, `self.bounds_bottom`,
`self.bounds_top`, `self.xaxis_reversed`, `self.bounds_xmin`,
`self.bounds_xmax`, `self.bounds_width`,
`self.yaxis_reversed`, `self.bounds_ymin`, `self.bounds_ymax`,
`self.bounds_height`, `self.default_text_height_dx`, and
`self.default_text_height_dy`.

convert_output_to_mm(d) [ doc ]

Convert the distance `d` measured in output coordinates to
millimeters.

convert_mm_to_output(d) [ doc ]

Convert the distance `d` measured in millimeters to output
coordinates.

convert_output_to_inches(d) [ doc ]

Convert the distance `d` measured in output coordinates to
inches.

convert_inches_to_output(d) [ doc ]

Convert the distance `d` measured in inches to output
coordinates.

convert_page_to_output_x(x) [ doc ]

Convert the position `x` measured in page x coordinates to the
position in output x coordinates.

convert_page_to_output_y(y) [ doc ]

Convert the position `y` measured in page y coordinates to the
position in output y coordinates.

convert_page_to_output_dx(dx) [ doc ]

Convert the distance `dx` measured in page x coordinates to
the distance in output x coordinates.

convert_page_to_output_dy(dy) [ doc ]

Convert the distance `dy` measured in page y coordinates to
the distance in output y coordinates.

convert_output_to_page_x(x) [ doc ]

Convert the position `x` measured in output x coordinates to
the position in page x coordinates.

convert_output_to_page_y(y) [ doc ]

Convert the position `y` measured in output y coordinates to
the position in page y coordinates.

convert_output_to_page_dx(dx) [ doc ]

Convert the distance `dx` measured in output x coordinates to
the distance in page x coordinates.

convert_output_to_page_dy(dy) [ doc ]

Convert the distance `dy` measured in output y coordinates to
the same distance in page y coordinates.

convert_page_to_frame_x(x) [ doc ]

Convert the position `x` measured in page x coordinates to the
position in frame x coordinates.

convert_page_to_frame_y(y) [ doc ]

Convert the position `y` measured in page y coordinates to the
position in frame y coordinates.

convert_page_to_frame_dx(dx) [ doc ]

Convert the distance `dx` measured in page x coordinates to
the distance in frame x coordinates.

convert_page_to_frame_dy(dy) [ doc ]

Convert the distance `dy` measured in page y coordinates to
the distance in frame y coordinates.

convert_frame_to_page_x(x) [ doc ]

Convert the position `x` measured in frame x coordinates to
the position in page x coordinates.

convert_frame_to_page_y(y) [ doc ]

Convert the position `y` measured in frame y coordinates to
the position in page y coordinates.

convert_frame_to_page_dx(dx) [ doc ]

Convert the distance `dx` measured in frame x coordinates to
the distance in page x coordinates.

convert_frame_to_page_dy(dy) [ doc ]

Convert the distance `dy` measured in frame y coordinates to
the distance in page y coordinates.

convert_figure_to_frame_x(x) [ doc ]

Convert the position `x` measured in figure x coordinates to
the position in frame x coordinates.

convert_figure_to_frame_y(y) [ doc ]

Convert the position `y` measured in figure y coordinates to
the position in frame y coordinates.

convert_figure_to_frame_dx(dx) [ doc ]

Convert the distance `dx` measured in figure x coordinates to
the distance in frame x coordinates.

convert_figure_to_frame_dy(dy) [ doc ]

Convert the distance `dy` measured in figure y coordinates to
the distance in frame y coordinates.

convert_frame_to_figure_x(x) [ doc ]

Convert the position `x` measured in frame x coordinates to
the position in figure x coordinates.

convert_frame_to_figure_y(y) [ doc ]

Convert the position `y` measured in frame y coordinates to
the position in figure y coordinates.

convert_frame_to_figure_dx(dx) [ doc ]

Convert the distance `dx` measured in frame x coordinates to
the distance in figure x coordinates.

convert_frame_to_figure_dy(dy) [ doc ]

Convert the distance `dy` measured in frame y coordinates to
the distance in figure y coordinates.

convert_figure_to_output_x(x) [ doc ]

Convert the position `x` measured in figure x coordinates to
the position in output x coordinates.

convert_figure_to_output_dx(dx) [ doc ]

Convert the distance `dx` measured in figure x coordinates to
the distance in output x coordinates.

convert_figure_to_output_dy(dy) [ doc ]

Convert the distance `dy` measured in figure y coordinates to
the distance in output y coordinates.

convert_output_to_figure_x(x) [ doc ]

Convert the position `x` measured in output x coordinates to
the position in figure x coordinates.

convert_output_to_figure_y(y) [ doc ]

Convert the position `y` measured in output y coordinates to
the position in figure y coordinates.

convert_output_to_figure_dx(dx) [ doc ]

Convert the distance `dx` measured in output x coordinates to
the distance in figure x coordinates.

convert_output_to_figure_dy(dy) [ doc ]

Convert the distance `dy` measured in output y coordinates to
the distance in figure y coordinates.

convert_to_degrees(dx, dy) [ doc ]

Returns the angle measured in degrees clockwise from the
horizontal for the slope specified by `dx` and `dy` given in
figure coordinates.

FigureMaker attributes

page_left [ doc ]

The position of the left of the page in the device coordinate
system -- measured in output page coordinates (1/720 inch).

page_right [ doc ]

The position of the right of the page in the device coordinate
system -- measured in output page coordinates (1/720 inch).

page_bottom [ doc ]

The position of the bottom of the page in the device
coordinate system -- measured in output page coordinates
(1/720 inch).

page_top [ doc ]

The position of the top of the page in the device coordinate
system -- measured in output page coordinates (1/720 inch).

page_width [ doc ]

The width of the page in the device coordinate system --
measured in output page coordinates (1/720 inch).

page_height [ doc ]

The height of the page in the device coordinate system --
measured in output page coordinates (1/720 inch).

frame_left [ doc ]

The position of the left of the frame in the page x coordinate
system which runs from 0 at the left to 1 at the right.
Initialized to 0.2 and changed by `set_subframe()`.

frame_right [ doc ]

The position of the right of the frame in the page x
coordinate system which runs from 0 at the left to 1 at the
right.  Initialized to 0.8 and changed by `set_subframe()`.

frame_bottom [ doc ]

The position of the bottom of the frame in the page y
coordinate system which runs from 0 at the bottom to 1 at the
top.  Initialized to 0.2 and changed by `set_subframe()`.

frame_top [ doc ]

The position of the top of the frame in the page y coordinate
system which runs from 0 at the bottom to 1 at the top.
Initialized to 0.8 and changed by `set_subframe()`.

frame_width [ doc ]

The width of the frame in page coordinates.  Initialized to
0.6 and changed by `set_subframe()`.

frame_height [ doc ]

The height of the frame in page coordinates.  Initialized to
0.6 and changed by `set_subframe()`.

bounds_left [ doc ]

The position of the left of the frame in the figure coordinate
system.  Initialized to 0.0 and changed by `set_bounds()`.

bounds_right [ doc ]

The position of the right of the frame in the figure
coordinate system.  Initialized to 1.0 and changed by
`set_bounds()`.

bounds_bottom [ doc ]

The position of the bottom of the frame in the figure
coordinate system.  Initialized to 0.0 and changed by
`set_bounds()`.

bounds_top [ doc ]

The position of the top of the frame in the figure coordinate
system.  Initialized to 1.0 and changed by `set_bounds()`.

bounds_width [ doc ]

The width of the frame in figure coordinates.  Initialized to
1.0 and changed by `set_bounds()`.

bounds_height [ doc ]

The height of the frame in figure coordinates.  Initialized to
1.0 and changed by `set_bounds()`.

bounds_xmin [ doc ]

The minimum x figure coordinate that is inside the frame.
Initialized to 0.0 and changed by `set_bounds()`.

bounds_xmax [ doc ]

The maximum x figure coordinate that is inside the frame.
Initialized to 1.0 and changed by `set_bounds()`.

bounds_ymin [ doc ]

The minimum y figure coordinate that is inside the frame.
Initialized to 0.0 and changed by `set_bounds()`.

bounds_ymax [ doc ]

The maximum y figure coordinate that is inside the frame.
Initialized to 1.0 and changed by `set_bounds()`.

tex_preamble [ doc ]

This string will be used as the preamble for the TeX file.
The default does \usepackage commands for color and geometry.
You may want to use some other packages as well.

Here is an example of how to do it which adds the 'marvosym'
package by inserting the following line into the 'initialize'
routine.

t.tex_preamble = t.tex_preamble + "\n\t\\usepackage{marvosym}\n"

PyTioga version: alpha (20071021)