Polygon Series file

Multics “polygon files” are used to store data about a set of polygons whose vertices may change position over time.

Definitions

File Format

A polygon file stores the \(x\)- and \(y\)-coordinates of one or more polygons, at one or more instants in time. The purpose of the file is to store whether a point is “inside” the polygon(s) at a specific point in time. In the event there are multiple polygons, there are several options for specifying how to define “inside,” as will be discussed below.

Warning

As explained below, the term “time” is used loosely with polygon files. The measure of time does not necessarily need to be “physical time” (i.e., measured in seconds). Rather, it could be “time” measured as, for example, the rotation angle of a pump shaft (in which case [TIME_UNIT] might be degrees).

General Format

There are two primary parts of a polygon file: (1) the header and (2) the polygon coordinates. The header lines in the files below are highlighted to distinguish the two parts of the file.

The standard format of a full polygon file is shown below. It can seem confusing at first, so if you aren’t sure about the format, skip to the later sections in which the format is broken down in more detail. The format is slightly different if storing one instant in time or multiple instants, and each is described under the tabs below.

Single Time Step

1 [Np] [POLYGON_MERGE_METHOD]
[NUM_COORD_1] [IS_INSIDE_1]  # <-- polygon 1
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_1}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_1}]
[NUM_COORD_2] [IS_INSIDE_2]  # <-- polygon 2
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_2}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_2}]
...
[NUM_COORD_j] [IS_INSIDE_j]  # <-- polygon j
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_j}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_j}]
...
[NUM_COORD_Np] [IS_INSIDE_Np]  # <-- polygon NUM_POLYGONS
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_Np}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_Np}]

Multiple Time Steps

[Nt] [Np] [POLYGON_MERGE_METHOD]
[TIME_UNIT]: [TIME_BEGIN] [TIME_STEP] [TIME_EXTRAP_METHOD]
[NUM_COORD_1_1] [IS_INSIDE_1_1]  # <-- time step 1, polygon 1
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_1_1}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_1_1}]
[NUM_COORD_1_2] [IS_INSIDE_1_2]  # <-- time step 1, polygon 2
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_1_2}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_1_2}]
...
[NUM_COORD_1_Np] [IS_INSIDE_1_Np]  # <-- time step 1, polygon NUM_POLYGONS
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_1_Np}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_1_Np}]
[NUM_COORD_2_1] [IS_INSIDE_2_1]  # <-- time step 2, polygon 1
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_2_1}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_2_1}]
...
[NUM_COORD_i_j] [IS_INSIDE_i_j]  # <-- time step i, polygon j
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_i_j}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_i_j}]
...
[NUM_COORD_Nt_Np] [IS_INSIDE_Nt_Np]  # <-- time step NUM_TIME_STEPS, polygon NUM_POLYGONS
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD_Nt_Np}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD_Nt_Np}]

Note that the numbers on the left-hand side are line numbers, and they are not part of the file.

Section 1: Header

The header contains metadata about the polygon file, formatted as follows:

Single Time Step

1 [Np] [POLYGON_MERGE_METHOD]

Multiple Time Steps

[Nt] [Np] [POLYGON_MERGE_METHOD]
[TIME_UNIT]: [TIME_BEGIN] [TIME_STEP] [TIME_EXTRAP_METHOD]

All parameters must be whitespace-separated.

Header Parameters for All Polygon Files

These parameters should be included in all polygon files.

[POLYGON_MERGE_METHOD]: Method for Combining Disjoint Polygons

In the event that there are multiple polygons per time step (i.e., Np > 1), there are a variety of ways they could be combined. We might want to know whether a point is inside of all of the specified polygons, or any of them, as a few examples.

There are three supported options for combining multiple disjoint polygons:

`[POLYGON_MERGE_METHOD]`	Description
`0`	If a point is considered “inside” of the union of polygons in the file if it is inside of any of the `Np` polygons.
`1`	If a point is considered “inside” of the union of polygons in the file if it is inside of all of the `Np` polygons.
`2`	If a point is considered “inside” of the union of polygons in the file if it is inside of exactly one of the `Np` polygons.

Note that whether a point is inside of each of the Np polygons will be defined by the IS_INSIDE parameter, discussed in the Section 2: Polygon Coordinates section.

This parameters is only relevant for polygon files in which Np > 1 but a value should be included in all polygon files (if Np = 1, this parameter is simply ignored).

Header Parameters for Files with Multiple Time Steps

These parameters should be included only for polygon files multiple time steps (Nt > 1).

[TIME_EXTRAP_METHOD]: Extrapolation for Time Values

The parameters [NUM_TIME_STEPS], [TIME_BEGIN], and [TIME_STEP] specify a range of times over which polygons will be provided; let us denote this range \(t \in [t_{min}, t_{max}]\). This poses an issue: what should be done if the time \(t\) falls outside this range?

It is not straightforward to “interpolate” or “extrapolate” polygons, since they can have an arbitrary number of coordinates that change in arbitrary ways each time step. Therefore, if \(t\) falls outside \([t_{min}, t_{max}]\), it must be “rescaled” to fall in this range.

Two options are provided for this “rescaling,” described below:

`[TIME_EXTRAP_METHOD]`	Description
0 or 2 (saturation)	When reading data from the polygon file, if \(t \lt t_{min}\), it is rescaled by \(t = t_{min}\), and if \(t \gt t_{max}\), it is rescaled by \(t = t_{max}\).
3 (periodic)	Assumes that the polygon data are periodic with period \(t_{min} - t_{max} + \Delta t\), where \(\Delta t\) represents `TIME_STEP`. If \(t\) falls outside the defined range, it is rescaled by \(t = ((t - t_{min}) \% (t_{max} - t_{min} + \Delta t)) + t_{min}\), where \(\%\) denotes the modulo operator.

Warning

If using the periodic approximation method (3), notice that you should not include both endpoints in the lookup table (otherwise, the period would be \(t_{max} - t_{min}\), not \(t_{max} - t_{min} + \Delta t\)).

For example, suppose your time variable is a cycle that repeats every rotation (\(360^\circ\)) and you are defining polygons in your polygon file every \(1^\circ\). In this case, your polygon file should include data for the following angles: \(0^\circ, 1^\circ, 2^\circ, ..., 358^\circ, 359^\circ\).

Section 2: Polygon Coordinates

This section contains the \(x\)- and \(y\)-coordinates for all polygons in the file, for every time step. The general structure for specifying these points (for a single polygon) is shown below:

[NUM_COORD] [IS_INSIDE]
[X_COORDINATE_UNIT]: [X_1] [X_2] ... [X_{NUM_COORD}]
[Y_COORDINATE_UNIT]: [Y_1] [Y_2] ... [Y_{NUM_COORD}]

Note that Section 2 of a polygon file typically contains a number of code blocks similar to above. However, each has the same format, so only a single such block will be discussed here. To see how to use multiple such blocks, refer to the Examples section.

The following parameters must be included in this section:

Comments, Whitespace, and Line Endings

Comments should not be used in polygon files.

Items denoted “whitespace-separated” may be separated by either spaces or tab (\t) characters.

Blank lines may be included but are not recommended.

On Linux and MacOS, LF line endings (\n) must be used. On Windows, either LF (\n) or CRLF (\r\n) line endings may be used.

Examples

Single, Stationary Polygon

Consider perhaps the simplest possible polygon file: a single polygon, at a single time step. Suppose that we want to describe a rectangle with vertices \((1, 0)\), \((5, 0)\), \((5, 2.5)\), \((1, 2.5)\).

In this case, there is one time step (Nt = 1) and a single polygon (Np = 1). Since there is only one polygon, POLYGON_MERGE_METHOD is not relevant (we’ll set it to 0 for this example). We’ll assume that all coordinates are in units of m and that the area enclosed by the rectangle is “inside” the polygon (IS_INSIDE = 1).

Taken together, these parameters result in the following polygon file:

polygon_file_single_stationary.txt

1 1 0
4 1
m: 1  5  5    1
m: 0  0  2.5  2.5

Multiple, Stationary Polygons

Let’s extend the previous example to describe the area inside of a union of two polygons:

A rectangle with vertices \((1, 0)\), \((5, 0)\), \((5, 2.5)\), \((1, 2.5)\)
A triangle with vertices \((5, 0)\), \((5, 2.5)\), \((7.5, 0)\)

Visually, this union is the following pentagon:

In this example, there is one time step (Nt = 1) and two polygons (Np = 2). Since we want to consider the area enclosed by either of the two polygons as “inside” their union, POLYGON_MERGE_METHOD should be 0. We’ll assume that all coordinates are in units of cm and that the area enclosed by both the rectangle and triangle is “inside” the polygon union (IS_INSIDE = 1).

Taken together, these parameters result in the following polygon file:

polygon_file_multiple_stationary.txt

1 2 0
4 1
cm: 1  5  5    1
cm: 0  0  2.5  2.5
3 1
cm: 5  5    7.5
cm: 0  2.5  0

Single, Moving Polygon

Finally, consider a case in which a polygon is moving. This is particularly applicable to fluid power applications, as this may reflect the moving boundary conditions in lubricating films.

As a simple example, consider a rectangular polygon that moves between \(t = 0\ ms\) and \(t = 2\ ms\) as shown below.

Thus, the rectangle has the following vertices at each time step:

\(t\)	Vertices
\(0\ ms\)	\((1, 1)\), \((3, 1)\), \((3, 2)\), \((1, 2)\)
\(1\ ms\)	\((2, 1)\), \((4, 1)\), \((4, 2)\), \((2, 2)\)
\(2\ ms\)	\((3, 1)\), \((5, 1)\), \((5, 2)\), \((3, 2)\)

In this case, there are three time steps (Nt = 3) and one polygon (Np = 1). Since there is only one polygon, POLYGON_MERGE_METHOD is not relevant (we’ll set it to 0 for this example). The units of time are ms ([TIME_UNITS] = ms), and since the time begins at zero and advances in \(1\ ms\) increments, [TIME_BEGIN] = 0 and [TIME_STEP] = 1. Assuming that we want to use “saturation” for time extrapolation, [TIME_EXTRAP_METHOD] = 0.

Based on the parameters described above and assuming that the coordinates are in units of ft, these parameters result in the following polygon file:

polygon_file_single_moving.txt

3 1 0
ms: 0 1 0
4 1
cm: 1  3  3  1
cm: 1  1  2  2
4 1
cm: 2  4  4  2
cm: 1  1  2  2
4 1
cm: 3  5  5  3
cm: 1  1  2  2