StarPlot - 3. Menu Items

# StarPlot Documentation

## Contents | Previous | Next

## 3. Menu Items

### 3.1. The File Menu

The File menu contains options for opening star catalogs, loading and saving StarPlot parameter files, saving a screenshot of the currently shown chart, and exiting the program.

#### 3.1.1. Open Star Database...

Related button:

This option opens a standard GTK+ file dialog window, shown below, from which you can select the star catalog (.stars file) to view. By default StarPlot will look in its data directory for .stars files (most likely either `/usr/local/share/starplot` if you installed the program from source, or `/usr/share/starplot` if you installed it from a package shipped by a Linux distribution). You can use the file dialog window to search in other directories, of course.

Once you click "OK", any star catalog that is currently being viewed will be abandoned in favor of the newly selected catalog. (Be warned that no sanity check is made to see whether the selected file really is a StarPlot data file.) Note also that other parameters of the chart (for instance, the location of the chart center, the chart radius, etc.) will not be changed by this operation.

Selecting this menu option is exactly equivalent to clicking the button on the button bar.

#### 3.1.2. Merge Star Database...

This option also allows you to open a star catalog, but unlike "Open Star Database..." it will not cause the previous catalog to be abandoned. Stars in both catalogs will be shown at once. (If you already used this option, all accumulated catalogs will be shown at once.)

Beware that StarPlot does not currently make any attempt to check for duplicate entries in simultaneously open catalogs. Doing so would be non-trivial, as the same physical star may be known by different designations and have different listed positions (particularly for its distance from Earth) in different catalogs.

There is no "Unmerge" option; instead, you can use the "Open Star Database..." option and select the specific catalog which you want to keep viewing.

#### 3.1.3. Open Parameter File...

As seen in section 0.3, this option lets you open a StarPlot parameter file. Parameter files contain all the information necessary to reproduce the exact appearance of a StarPlot display viewed at an earlier time, assuming that you have kept the same star catalogs on your computer in the same places. They do not include contents of star catalog(s).

Parameter files are not intended to be portable across machines since the location of the star catalog(s) is given as an absolute path. However, judicious hand-editing of a parameter file should be fairly trivial.

The default search path for the parameter file is your current working directory. If you started StarPlot from the command line, this is the directory from which you typed "starplot"; otherwise it is most likely your home directory.

#### 3.1.4. Save Chart Parameters...

This option lets you save the current chart parameters to a text file which can be re-opened with the "Open Parameter File..." option. In addition to the portability warnings above, also note that you probably want the location of the currently open star catalog(s) to be saved as an absolute rather than a relative path. The only case where this might be a problem is if you opened the star catalog(s) on the command line rather than from the Open or Merge Star Database menu options.

The default directory to which the parameter file will be saved is your current working directory.

#### 3.1.5. Save Chart as PNG...

Use this to save an image (in PNG format) of the StarPlot display. Only the chart display (and the legend and status, if they are visible) will be saved, not any of the graphical widgets such as the menu bar or button bar. Thus your image will look something like the one below.

The default directory to which the image will be saved is your current working directory. In choosing the filename of the image, if you omit the trailing "`.png`", it will be added for you (only in StarPlot version 0.95.5 or later).

#### 3.1.6. Quit

This option, naturally, quits the program. Upon quitting, StarPlot automatically saves the current chart parameters to a file named `.starplotrc` in your home directory. This file is automatically reloaded to set the initial parameters the next time StarPlot is started. It has exactly the same format as any other StarPlot parameter file.

### 3.2. The Chart Menu

The Chart menu includes three menu options that open dialog windows, which provide precise manual control of the fundamental parameters of the StarPlot display.

#### 3.2.1. Define Chart...

Related buttons: [also, star symbols in chart display]

The StarPlot Define Chart dialog window, shown at right, lets you select the volume of space covered by the chart. Notice that when you first open the dialog, the coordinates and size of the chart are already filled in for you with the current values, using your preferred coordinate system and standard distance unit.

Three of the four parameters required to define a chart volume are the coordinates of the center of the volume. You have the option of entering this information in two ways. The simpler is to type the name of a star into the uppermost text entry field, and then click the "Search" button. (You can also just hit Enter on the keyboard.) The field is case-insensitive. If the star can be found in the currently open star database file(s), its coordinates will automatically be entered into the central part of the dialog for you. If the search string is not matched by any star, a pop-up error message tells you so. (If you have a large file such as the SKY2000 catalog open, it may take several seconds for the matching star or the error message to come up.)

Alternatively to the star search function, you can enter the coordinates of the star manually. This is also useful in case you want to center the chart on a position where there is no star. The two angular coordinates must each be entered in three separate fields, in the formats HH MM SS and ±DD MM SS, respectively for right ascension and declination. (In Galactic coordinate mode, the Galactic longitude is entered in the DDD MM SS format.) However, if you prefer to use a decimal format such as ±DD.dddd for the declination, for instance, you can enter this decimal number in the first entry box (for degrees) and enter 0 in the corresponding minute- and second-of-arc entry boxes.

The fourth parameter needed, the radius of the chart volume, can be entered at the bottom of the window. The number entered in that text field is interpreted to be in either light-years or parsecs, depending upon what set of units you have selected to use from the Options->Distance Units submenu. (Prior to StarPlot 0.95.5, only light-years were supported.)

When finished entering the desired chart location and size, click the "OK" button to confirm, or the "Cancel" button to abort the operation. The "Revert" button can be used to restore the chart location and size to the default starting values of the program: a chart of radius 10 light-years, centered on the Sun.

#### Aside regarding the star search

It may be useful to understand the details of how the search for a star name is performed. First, any constellation genitive names in the search string are converted to the corresponding constellation abbreviation. The presumption is that constellations are always abbreviated in the star database files in order to use less disk space. For instance, the search string `Alpha Coronae Borealis` is internally converted to `Alpha CrB`. Any lowercase Greek letters, supposing that you are able to type them in easily, are converted to their spelled-out English names, such as `α` to `Alpha`. Asterisks * are converted to degree symbols ° for your convenience (most people do not have a degree sign on their keyboard). After these transformations, StarPlot looks for a star record having a name field of which the search string is a case-insensitive exact match.

If there is no exactly-matching record, a tokenizing substring search is then attempted on the original (non-transformed) search string using the same algorithm as in the star search dialog, with a case-sensitive search. If there is still no match, StarPlot re-tries the same algorithm with a case-insensitive search. If at any stage more than one match is found, only the first match is used, but no warning of this fact is given. You can skip these attempts to search for inexact matches by tokenizing if you wrap the search string in double-quote marks `"`.

Usually this procedure does what you want; for instance, the search string `alpha centauri` will match the star having a name field Alpha(1) Cen. However, surprises can occur. For instance, if you enter `HD 12` in the search field, but that star is not in the currently open database(s), you may end up with the star HD 123 being found instead. Searching for `HD [12]` or `"HD 12"` instead will do what you want, producing an error message if there is no such star. In any case, once a match is found, it is wise to double-check the contents of the search string field for the matching star name, to be sure it is what you expect.

#### 3.2.2. Orientation...

Related buttons:

This subsection is not yet written.

#### 3.2.3. Star Filter...

Related buttons: [also, spectral class icons in chart legend]

This subsection is not yet written.

### 3.3. The Options Menu

This section is not yet written.

### 3.4. The Stars Menu

This section is not yet written.

### 3.5. The Help Menu

This section is not yet written.

## Continue to Chapter 4...