NOAA SOS Public Kiosk

Version History

  • 5.1.1: Aug. 2016
  • 5.1: Jul. 2016
  • 5.0: Nov. 2015

Introduction

The NOAA SOS Public Kiosk (“NOAA Kiosk”) software initially debuted with the SOS 5.0 release. It provides a touch screen controller intended for a general public audience to interact with a Science On a Sphere® (SOS) exhibit when there is no docent present. It has some similarities with other third party kiosks created in the past for SOS, such as the Bishop Museum’s kiosk. The motivation for building the NOAA Kiosk was to provide a flexible and easy-to-administer public controller that can be localized to native languages by using standard SOS playlists. The NOAA Kiosk runs on Microsoft Windows, but was designed to be able to portable to other types of operating systems such as Linux and Mac OSX (should there be sufficient demand for those platforms). The NOAA Kiosk is fully supported by its NOAA software developers and is included as part of the normal SOS customer support provided at sos.gsd@noaa.gov. Suggestions for new features and submissions of bug reports is highly encouraged to keep improving the NOAA Kiosk into the future.

Overview

The NOAA Kiosk has two main user interfaces (UIs), one for public interaction with SOS and another for administration of the kiosk. The public UI is normally the one displayed and is described in this section, while the latter is described in the Administration UI Options section.

Public User Interface

The default public UI is shown in the following annotated screenshot:

These are the Major Components of the public UI outlined by numbered red boxes for reference:

  1. Title Area - at the top. This area includes a logo image at the left, title and subtitle text, an information button (“i” symbol), and a group of language buttons. The language buttons transform the language of the UI to the selected choice. The supported languages are preselected by each venue (see the Localization/Translations to Non-English Languages section for information on how to set up translations).
  2. Groups Column - on the left side. This is a scrollable set of rectangular buttons, each of which defines a related set of datasets. By default, these are largely the same as the Major Categories in the SOS Data Catalog, but can be changed to fit each venue’s needs (see the Group and Dataset Configuration section).

  3. Datasets Row - on the bottom. This is a scrollable set of circular buttons, each of which defines a dataset for the currently selected group. By default, these are NOAA’s selection of the best and most popular datasets for each group, but can be changed to fit each venue’s needs (see the Group and Dataset Configuration section).

  4. Overlays Column - on the right side. This is a scrollable set of circular buttons, each of which defines an overlay dataset that may be shown on top of the current dataset. By default, these are all of NOAA’s set of overlay datasets, but fewer may be shown to can fit with the venue’s needs.

  5. Information Box - left of center. This is a text area that usually displays a brief description of the currently selected dataset. When the information button is selected, this area displays an introduction to SOS and instructions on how to use the NOAA Kiosk.

  6. Sphere Controls - right of center. This is a collection of controls to manipulate the sphere. A spherical trackball controller is used to drag the sphere horizontally and vertically with curved arrow next to it used to tilt the sphere (by tapping or dragging it). Below the sphere are buttons to reset the sphere position, play or pause it, turn globe rotation on/off for animations, step one frame backward/forward, and a frame slider.

  7. Administration UI Button - lower right corner. The "gear" button is used to access the user interface for kiosk administration controls. It includes the ability to lock the kiosk UI when a presenter is using the iPad controller.


Quick Start: How to Use the NOAA Kiosk

(Component numbers refer to the diagram above)

Basic steps for use by the general public:

  1. Select a Group (Component #2) and scroll through its Datasets (Component #3).
  2. Select a Dataset (Component #3) and watch it appear on SOS and on the trackball controller (Component #6).
  3. Read about the currently playing dataset in the Information Box (Component #5)
  4. Use the Sphere Controls (Component #6) to position the sphere and change which frames are displayed on SOS.
  5. Select one or more Overlays (Component #4) to display an overlay on top of the Dataset currently playing on SOS.
  6. Repeat these steps as long as desired.

Other options a public user can use:

  • Select the Information Button (Component #1) to display information about SOS or how to use the kiosk (Component #5)
  • Select a language button (Component #1) to change the language text used in the kiosk

Required Equipment

The NOAA Kiosk software runs on a PC running Microsoft Windows. It is officially supported on Windows 7 and 8, but may also run okay on Windows 10 or XP. The User Interface scales automatically for different screen sizes, including both 4:3 and 16:9 ratios. It requires a touch screen, which can be separate from the computer or in an all-in-one configuration. The touch screen works best when mounted either in a kiosk housing near the sphere or mounted to the railing that surrounds the sphere. The kiosk PC must be on the same network as the SOS machine, either directly connected with Ethernet or by Wi-Fi.

For more specific recommendations pertaining to your particular venue, you can contact NOAA SOS support at sos.gsd@noaa.gov.

Installation and Setup

The NOAA Kiosk software is available to all current SOS customers at no cost upon request by e-mailing NOAA SOS support at sos.gsd@noaa.gov. Instructions will be provided on how to download the software, which is provided as a standard Windows setup.exe program that unpacks and installs the software as well as the default configuration files on the PC. Most of the files reside under c:\shared\sos\kiosk, so the Windows user must have privileges to write to the C: drive. The kiosk software doesn't not use the Windows registry. Approximately 80MB of disk space is required for the software and data- files.

Once installed, the hostname or IP address of the SOS machine must be changed in the kiosk_server property for the Kiosk to operate. See the Administration UI Options section for more information.

The NOAA SOS Kiosk software will occasionally crash, leaving the Windows PC with the desktop showing. To remedy this situation, you can install an application that will automatically detect that the kiosk is no longer running and restart it automatically. One free application that does this is called Restart On Crash and it has been successfully used with the NOAA SOS Kiosk. Instructions on how to download and install this utility are described in Appendix E. There are many other Windows restart applications available that may work with the NOAA SOS Kiosk and NOAA is not specifically endorsing the use of Restart On Crash.


Configuring NOAA Kiosk Settings

The NOAA Kiosk has default settings carefully selected by NOAA that will work well at many SOS sites. However, there are many ways to customize the kiosk to suit the needs of a particular venue:

Each of these of configurations is described in a separate section below. The underlying file structure used by the NOAA kiosk is also fully described for reference in Appendix A.

Basic Settings using the Administration UI

The NOAA Kiosk is highly configurable using the Administration (Admin) UI, which is launched by pressing the gear icon in the lower right corner of the Public UI (Component #7). A numeric keypad appears to enter a 4-digit administration passcode (the default is 1234, which should be changed!). The back-arrow key is used to delete a mistyped digit. Note that if the kiosk was previously locked, a 4-digit lock code must be entered (the default is 4321, which should also be changed).

The Admin UI has five tabs (described below) and a set of common buttons, Apply and Close at the bottom right and X at the top right, that are used for all options. Apply must be pressed for changes to be saved. Pressing either Close or X simply dismisses the Admin UI without saving changes made.

  1. Viewpoint Tab

    The Viewpoint tab controls are used to correctly set the position of the images in the trackball controller relative to the SOS origin.

    • Press the Ready button to begin
    • Rotate the sphere image until it matches what is displayed on SOS directly in front of the kiosk
    • Press the Set button to finish

    Normally this operation is only required once when the NOAA Kiosk is first set up.

  2. Properties Tab

    (screenshot expanded to show all the properties)

    The Properties tab presents a table of kiosk properties and controls to change their settings. Colors are represented with hexadecimal characters for red-green-blue that are set using a popup Color Chooser. Numbers are set using a graphical Numeric Keypad or a dropdown Number Chooser, and text is set using a Graphical Keyboard. Examples of each of these controls are given after the property list. Note that for more extensive editing, a regular keyboard may be attached to the kiosk machine and used instead of the graphical keyboard and numeric keypad.

    • locale_options (default = en_US). A comma separated list of localization strings for the languages supported in the kiosk. It must include the locale_default value in the list. These are used to specify the language buttons shown (on the right side of Component #1). Note that if only one locale is specified, the language buttons are hidden. Set using the Graphical Keyboard.

      For example, to use American English, Mexican Spanish, and Traditional Chinese in Taiwan, the value would be: en_US,es_MX,zh_TW. If new locale_options are added, it is necessary to restart the kiosk for them to take effect.

    • locale_default (default = en_US, English in the United States). The localization string for the language in which the kiosk starts. The localization string uses the ISO 639-1 two letter code for language an underscore (“_”) and then the ISO 3166 for the country or region. Set using the Graphical Keyboard.

    • group_buttons (default = both). Options for showing text and/or an image for Groups. In this version of the kiosk, both is always used.

    • dataset_buttons (default = both). Options for showing text and/or an image for datasets. In this version of the kiosk, both is always used.

    • kiosk_server (default = 127.0.0.1). The name or IP address of the SOS machine (typically something like sos1). The default will not work and must be changed to a valid value. Set using the Graphical Keyboard.

    • ftp_server: (default = 127.0.0.1). The name or IP address of the machine configured for FTP (typically the SOS machine, something like sos1). The default will not work and must be changed to a valid value. Set using the Graphical Keyboard.

    • ftp_username: (default = test). The username being used for FTP transfers on the SOS machine (typically something like sos). The default will not work and must be changed to a valid value. Set using the Graphical Keyboard.

    • ftp_password: (default = test). The password being used for FTP transfers on the SOS machine (typically the password used for the sos user). The default will not work and must be changed to a valid value. Set using the Graphical Keyboard.

    • ftp_save_path: (default = C:\shared\sos\kiosk). The root directory on the Windows kiosk machine where the NOAA Kiosk data files are installed. Normally will not need to be changed. Set using the Graphical Keyboard.

    • autoplay (default = 0). Analogous to the SOS Autorun mode, this property controls the behavior for automatically playing datasets in the kiosk. Set using the Numeric Keypad.
      • 0 - off: manual mode only
      • 1 - on: cycles repeatedly through all the datasets in the Group specified by the value of the autoPlayGroup property.
      • 2 - on: cycles randomly through all the datasets in the kiosk
      • When autoplay is on, each dataset plays for the length of time specified by the duration property. If autoplay is interrupted by a person manually selecting a dataset, the autoplay will restart again after a length of time specified by the timeout property until interrupted.

    • autoPlayGroup: (default = popular). Used when autoplay is set to 1 and specifies the group from which datasets will be automatically displayed. Set using the Graphical Keyboard.

    • timeout (default = 180). Length of time in seconds after autoplay is interrupted before the autoplay resumes (when autoplay's value is 1 or 2).

    • duration (default = 180). Length of time in seconds that a dataset will be displayed when autoplay is turned on (value = 1 or 2) before switching to the next dataset. Datasets that are narrated movies will play to the end even if they are longer than the duration time.

    • background (default = ffffff, black). The color used for the main area of the kiosk background (below Component #1). Set using the Color Chooser.

    • fontcolor (default = 000000, white). The color of the text in the main area of the kiosk (below Component #1). Set using the Color Chooser.

    • banner_background (default = ffffff, black). The color of the Title Area (Component #1) of the kiosk background. Set using the Color Chooser.

    • banner_fontcolor (default = 000000, white). The color of the text in the Title Area (Component #1) of the kiosk. Set using the Color Chooser.

    • circlecolor (default = 55555, gray). The color of the border drawn around the Dataset and Overlay circular buttons (in Component #2 and Component #4). Set using the Color Chooser.

    • nowcolor (default = ffff00, yellow). The color of the border drawn around the currently selected Group, Dataset, and Overlay buttons (in Components #2, #3, and #4). Set using the Color Chooser.

    • content_fontsize (default = 18). The font size of the text in the Information Box (Component #5). Set using the Number Chooser.

    • title_fontsize (default = 48). The font size of the text in the main title (top-left of Component #1). Set using the Number Chooser.

    • subtitle_fontsize (default = 36). The font size of the text in the secondary title (bottom-left of Component #1). Set using the Number Chooser.

    • langbtn_fontcolor (default = ffffff, black). The color of the text used for the language buttons (right side of Component #1). Set using the Color Chooser.

    • langbtn_bordercolor (default = ffffff, black). The color of the border around each language button (in Component #1). Set using the Color Chooser.

    • password (default = 1234). The 4-digit passcode used to open the Administration UI. This should be changed to a different value that is less easily guessed. Set using the Numeric Keypad.

    • lockcode (default = 4321). The 4-digit passcode to lock and unlock the kiosk. This should be changed to a different value that is less easily guessed. Set using the Numeric Keypad.

    • sphere_load_delay (default = 5). The length of time in seconds that the kiosk waits after a dataset has been selected before it will allow another dataset to be selected. This prevents a user from rapidly selecting datasets in succession, which causes SOS to cycle too quickly between datasets. Set using the Numeric Keypad.

    • sync_enable (default = 1). Synchronize rotation of the trackball image with the SOS display. Use 0 to turn this off if the kiosk computer or networking equipment used is unable to handle the increased system load this feature may cause. Set using the Numeric Keypad.

      Color Chooser example:


      The Color Chooser interface is used to set a color, such as for backgrounds, text, and button borders. It provides a variety of options for picking a color, including selecting 1 of 64 basic colors, making your own custom color by clicking in a rectangular color grid, and entering numerical values into boxes for Hue/Saturation/Value (HSV), Red/Green/Blue (RGB), or as a 6-digit hexadecimal HTML number. The best way to learn how these controls work is to experiment with them and try out different ways to create the colors you want. The Color Chooser has the ability to remember particular colors you like with the Add to Custom Colors button. These Custom colors can then be picked and used for other kiosk color properties, but note that they won't be remembered the next time the kiosk is restarted (however, any colors saved as properties are definitely preserved).

      When you are finished, press OK to accept the new color or Cancel to keep the previous color. (note: the Close button at the bottom-right will close the Admin UI).


      Numeric Keypad example:


      The Numeric Keypad interface is used to set a numeric value, such as passcodes. Use the Del button to delete that last typed digit. When you are finished, press OK to accept the new numbers or Cancel to keep the previous numbers. (note: the Close button at the bottom-right will close the Admin UI).


      Number Chooser example:


      The Number Chooser interface is used to set a numeric value from a dropdown list of choices, such as font sizes. Select the desired value and use the Apply button to change the value or the Close button (next to Apply) to discard changes and keep the old value. (note: the Close button at the bottom-right will close the Admin UI).


      Graphical Keyboard example:


    The Graphical Keyboard interface is used to set text values and simulates a physical keyboard. Use Clear to delete all the text, the back arrow key to delete the last typed character, and the up arrow key to shift to type alternative characters. When you are finished, press OK to accept the new text or Cancel to keep the previous text. (note: the Close button at the bottom-right will close the Admin UI).


  3. FTP Tab

  4. The FTP tab controls are used to transfer kiosk-related files between the Windows Kiosk machine and the Ubuntu SOS Server using the industry standard File Transfer Protocol (FTP). This feature is new in version 5.1 and replaces the need to use external file transfer tools. The properties in the upper left of the pane are all defined in the Properties tab and are normally set only once when the kiosk is first set up. The buttons on the right side are used to initiate a transfer in the direction indicated. The progress bar shows the file transfer activity as it occurs.

    • Server to Kiosk: this option copies files from the SOS machine to the kiosk. This needs to be used whenever the media2kiosk command line utility has been run on the SOS machine to update which groups and datasets are shown on the kiosk, along with related text including translations.

    • Kiosk to Server this option copies file from the kiosk to the SOS machine. This generally needs to be done only once after the kiosk is installed and its purpose is to copy the default kiosk configuration to the SOS machine so it can be customized. If there are no files in the /shared/sos/kiosk directory on the SOS machine, this option will copy those files from the kiosk as the initial starting point.

    The purposes of the files transferred are described below in the sections entitled Group and Dataset Configuration and Localization/Translations to Non-English Languages. For even more information, the file structure is documented in Appendix A. Also, an FTP server must be set up on the SOS machine in order for these options to work properly (see Appendix B for instructions).

    Note: the Apply button at the bottom-right applies all previous edits made in any tab of the Admin UI, while the Close button next to it will close the Admin UI.


  5. Language Tab

  6. The Language tab controls are used to set the text for the small amount of text in the Public user interface of the kiosk for each of the languages specified by the locale_options property (described above). Note that this tab is not used to translate groups, dataset names and descriptions, or text in the Administration UI, which are described below.

    To edit the value of any of any text property, just click in the Setting field space next to it and use the Graphical Keyboard to edit the text. If there are characters you need that are not available in the Graphical Keyboard, you will need to attach a physical keyboard and mouse, then copy and paste the text you want from another source, such as a website or text document. If you add a new language to the kiosk with the locale_options property, the Language tab will show its text properties with blank lines for the translations. If there are any blank values in the Language tab, the kiosk will use default American English text.

    Note: the Apply button at the bottom-right applies all previous edits made in any tab of the Admin UI, while the Close button next to it will close the Admin UI.


  7. Function Tab

  8. The Function tab has buttons to close the kiosk application and to lock down its operations.

    • Exit Kiosk: closes the kiosk interface and terminates the program. This is used only when administrative work is needed on the kiosk machine and normally the kiosk will always be up and running.

    • Lock Screen: locks the kiosk user interface so that none of its controls can be operated and autoplay is suspended. This should be done whenever a presenter is using the iOS Remote App to control SOS. A separate 4-digit lockcode is entered to unlock the kiosk as shown in the following screenshot.



    • Note that you can lock the kiosk by either 1) using the Lock Screen button in the Function tab, or 2) clicking by the Gear button in the lower right corner of the main kiosk UI Component #7, then entering the 4-digit lockcode (see the section Basic Settings using the Administration UI) above). These two options are equivalent.

      Note: the Apply button at the bottom-right applies all previous edits made in any tab of the Admin UI, while the Close button next to it will close the Admin UI.


Group and Dataset Configuration

The default groups and datasets provided with the NOAA Kiosk setup may work well for your venue, but are easily changed to better suit your intended SOS viewers. The NOAA Kiosk defines which groups and datasets are displayed by using standard SOS playlists that reside under /shared/sos/kiosk/playlists on the SOS machine. General information about SOS playlists is available in the Playlist Format Reference.

Basic structure of playlists used in the kiosk configuration

  • kiosk.sos: this playlist has include lines for all the playlists that define each group. The order they appear in the kiosk.sos playlist is how they are displayed in the kiosk UI. Below is the default kiosk.sos file.
    # NOAA SOS Kiosk

    # Kiosk logo
    icons = /shared/sos/kiosk/images/noaa_logo.png

    # Kiosk ordered group playlists

    # popular group
    include = /shared/sos/kiosk/playlists/groups/popular.sos

    # air group
    include = /shared/sos/kiosk/playlists/groups/air.sos

    # water group
    include = /shared/sos/kiosk/playlists/groups/water.sos

    # land group
    include = /shared/sos/kiosk/playlists/groups/land.sos

    # snow_and_ice group
    include = /shared/sos/kiosk/playlists/groups/snow_and_ice.sos

    # space group
    include = /shared/sos/kiosk/playlists/groups/space.sos

    # people group
    include = /shared/sos/kiosk/playlists/groups/people.sos

    Note that the icons playlist keyword here specifies the image file for the logo graphic used in the upper left corner of the kiosk. This differs from how this keyword is used in regular SOS dataset playlists. In the 5.0 version this line was commented out and needs to be uncommented when upgrading to version 5.1. If you are using your own logo instead of the NOAA logo, the icons value should specify the full path to your graphic file.

  • groups: the groups directory contains all the group playlists included in kiosk.sos. Each group playlist has include lines for each of the datasets that appear in the kiosk when that group’s button is selected. For example, here is part of the land.sos group playlist:

    # NOAA SOS Kiosk
    # Ordered Datasets for Display on the Sphere

    # Group: land
    icons = /shared/sos/kiosk/images/groups/land-kiosk.jpg

    # ID_82: Blue Marble
    include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos

    # ID_88: ETOPO1: Topography and Bathymetry
    include = /shared/sos/media/land/etopo1/playlist.sos

    # ID_118: Age of the Seafloor (topography)
    include = /shared/sos/media/land/sea_floor_age/topo/playlist.sos

    # ID_127: Earthquakes - Real-time
    include = /shared/sos/rt/noaa/quake/hires/playlist/playlist.sos

    # ID_472: Dams and Reservoirs - 1800 - 2100
    include = /shared/sos/media/land/dams/global/playlist.sos

    Note that the icons playlist keyword here specifies the image used for that group’s button in the kiosk. This differs from how this keyword is used in regular SOS dataset playlists.

How to customize the groups, datasets, and graphics in your kiosk

  1. Decide how you will be editing the kiosk text files. Currently the recommended approach is to use a standard text editor such as vim or gedit. In the future you may be able to use other tools such as the Visual Playlist Editor (PDF) to do your edits.

  2. Edit the kiosk.sos file.
    • You can change the value of the icons property if you'd like to replace the NOAA logo with one of your own. For best results, use a size similar to the NOAA logo's dimensions, which is 260x260 pixels. Copy your logo image file into the /shared/sos/kiosk/images/ directory and change the icons value to match its path.

    • Edit, remove, or add include lines to the dataset groups you plan to use in the kiosk. Each include line refers to a group playlist that will appear in the public UI represented with a rectangular group button. The groups will appear in the kiosk (in Component #2) in the same order (top-to-bottom) as they are listed in the kiosk.sos file.

  3. Create new and/or edit existing groups.
    • To create a new group, start by copying an existing group playlist file to a new name. The filename stem (e.g., air for air.sos) will be used as the group name in the kiosk.

    • For each group playlist, edit the value of the icons property if you wish to change the image for that group's button in the public UI. There are a number of image files you may choose to use located in /shared/sos/kiosk/images/groups/. You may also create your own, but any images you use should have pixel dimensions about 500x417 and have empty space at the bottom for where the group name will be displayed. We also suggest that you copy your image files into the /shared/sos/kiosk/images/groups/ directory.

    • For each group playlist, add, remove, or modify include lines for each dataset you plan to use in the kiosk. Each include line refers to a dataset that will appear in the public UI represented with a circular thumbnail button. The datasets will appear in the kiosk (in Component #3) in the same order (left-to-right) as they are listed in the group files.

    • The sphere frame image that is displayed on the trackball control (in Component #6) for each dataset listed by an include line is usually derived directly from the dataset's image data itself, but there are a number of different ways that this image may be generated for use in the kiosk. Here are the available options in priority order of precedence:
      1. If the icons keyword is set immediately following the dataset's include line in the group playlist, the trackball image will be set to the file path for any existing image file anywhere on the SOS machine. This option overrides any other source for the trackball image. Note that this is not the standard use of the icons keyword in an SOS dataset playlist. For example:
      2. include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
        icons = /home/sos/my_images/my_sphere_frame.jpg
      3. For a movie file or directory of images, if the stopframe keyword is set immediately following the dataset's include line in the group playlist, the trackball image is extracted using the frame index specified. This keyword is ignored for a single frame image dataset. Note that this is not the standard use of the stopframe keyword in an SOS dataset playlist. For example:
      4. include = /shared/sos/media/extras/frozen/playlist.sos
        stopframe = 50
      5. If there is a sphere_frame .jpg or .png or.tiff file located in the dataset's media sub-directory (where the thumbnails are located), that will be used as the trackball image. NOAA supplies these as part of some datasets and any site may specify these files for their own datasets installed under the /shared/sos/media/site-custom directory.

      6. The default option is to use the image itself as the trackball for single frame datasets or by extracting the middle frame number as the index into the dataset's movie file or directory of images. In the latter case, for example, if a dataset has 200 frames, then frame 100 would be used to generate the trackball image.

    • There is one special group playlist named overlays.sos that may also be modified. This group is not listed in kiosk.sos and does not have its own group image. overlays.sos is used to specify the overlay layers that may be displayed on top of the regular datasets in SOS. As with the other groups, the datasets in overlays.sos appear in the kiosk in the same order as they are listed, except that overlays are shown top-to-bottom in the Overlays part of the public UI (in Component #4).

  4. Test your kiosk playlists on SOS with the File > Open Playlist menu item in the SOS Stream GUI, by loading the file /shared/sos/kiosk/playlist/kiosk.sos. Check for any dataset loading errors that indicate invalid include paths to the datasets you selected and correct them in the group playlists.

  5. Verify that the directory /shared/sos/kiosk exists on your SOS system. If it doesn't, you can use the FTP tab of the Administration UI to transfer the default kiosk-related files from the kiosk to the SOS machine. You may also need to install and configure a simple FTP server on the SOS machine to handle the FTP file transfers between the two systems. See Appendix B for instructions on how to set up your FTP server.

  6. Run the media2kiosk command line utility in a terminal window (it is located in the C:\shared\bin directory of your SOS installation). This program automatically generates the file hierarchy used by the kiosk for groups and datasets. The options for media2kiosk are described in Appendix C. It automatically names the groups after the playlist filenames used to define them, such as air for the group playlist /shared/sos/kiosk/playlists/groups/air.sos. It also generates files the kiosk uses to show each dataset in the public UI (Appendix A has a full description of the kiosk file hierarchy). By default, the dataset names and descriptions are obtained from the SOS Data Catalog. The descriptions tend to be longer than desirable for a kiosk user, so there is a way to replace those with your own text. This is done with the same approach as for translating English to other languages, which is covered in the next section.

  7. Transfer the kiosk dataset and group file hierarchy using the controls in the FTP tab of the Administration UI.

  8. Restart the kiosk software (using the desktop or from the Start menu) and verify that you are satisfied with how your changes appear in the public UI, including group names and button images and dataset names, descriptions, and button images. Test the kiosk with SOS to make sure all the datasets load and display properly.

  9. Repeat these steps until the kiosk is configured the way you want it.

Localization/Translations to Non-English Languages

The term localization refers to translating text into another language, with possible variations for a particular country or region. A locale is defined as xx_YY, where xx is the ISO 639-1 language code and YY is the ISO 3166 country or region code. The default locale is en_US, which is English in the United States.

In the NOAA SOS Kiosk, translations are created and edited in several different ways depending on which part of the kiosk is being localized:

  1. Public UI text translations are created and edited using the Language tab in the Admin UI on the Windows kiosk machine.

  2. Administration UI text translations are made using a set of utilities run on the Windows kiosk machine. This is a more advanced localization activity that may require assistance from the SOS team. Steps to perform a translation of the Admin UI are described in Appendix D.

  3. Dataset names and descriptions are translated using the SOS Data Catalog and playlists as described in this section. Translations are made on the SOS machine and then transferred to the kiosk.

  4. Group names are translated using playlists as described in this section. Translations are made on the SOS machine and then transferred to the kiosk.

Translating Dataset Names and Descriptions

The names and descriptions for datasets in the NOAA Kiosk are generated by the media2kiosk utility and are written to directories under /shared/sos/kiosk/datasets, where they are used by the kiosk after being transferred there.

Here is a summary of where the dataset informational text (Component #5) displayed in the kiosk comes from:
  1. The default locale (en_US) names and descriptions are read from the SOS Data Catalog. The descriptions are stripped of any HTML formatting that may have been used.

  2. If there are any translations previously imported into the SOS Data Catalog, those are automatically extracted as well for each of their locales.

  3. Playlists may also be used to define translations for dataset names and descriptions. These are very similar to the localization playlists used more generally in SOS, which are described in the separate SOS Translations Guide. How to use these translation playlists is explained next.

Translation playlists for datasets reside on the SOS machine under the /shared/sos/kiosk/playlists/locale/datasets directory. This directory holds a set of playlists following the naming convention xx_YY.sos, where xx_YY is the locale code, as described earlier. All the dataset translations for a given locale are placed together in the same playlist. You may notice that there is an en_US.sos playlist under the datasets subdirectory. This does not contain translations per se, but the file contains entries for all the datasets in the default kiosk configuration with shortened dataset names and descriptions. This was done to work better for viewing by the general public and can be thought of a way to override the Data Catalog text.

For reference, here is a portion of the en_US.sos playlist for datasets, which includes two datasets:
# ID 3: Hurricane Season - 2005
include = /shared/sos/media/atmosphere/2005_hurricane/grayir/playlist.sos
rename = Hurricane Season - 2005
description = {{The 2005 hurricane season shattered records that have stood for decades - most named storms, most hurricanes and most category five storms. With 28 named storms, 15 hurricanes, seven major hurricanes, and four category 5 hurricanes, the 2005 hurricane season certainly blew the records away. It was also the first season in which four major hurricanes hit the U.S.. Even with all these records, the 2005 hurricane season will arguably be most remembered for Hurricane Katrina, which devastated parts of Mississippi, Louisiana and in particular, New Orleans.

This dataset is a gray-scale infrared satellite image available from June 1, 2005 through January 3, 2006.}}

# ID 82: Blue Marble
include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
rename = Blue Marble
description = {{The Blue Marble is an incredibly detailed, true-color depiction of the Earth. NASA is responsible for this dataset made from a compilation of satellite images throughout 2001. The background image of the land and oceans was created using data from June through September of 2001. This could not be done in a single day or even a week because on any given day clouds are blocking a significant portion of the surface. The cloud image is a composite of three days worth of data. The shading is true color with the oceans shades of blue, the clouds white and the lands varying from green to brown. The brown areas are the sands of the deserts.}}
Each of the two datasets shown uses three playlist keywords that are applicable to translations:
    include = path to the dataset playlist
    rename = kiosk name for the dataset
    description = kiosk description for the dataset. Description is a dataset playlist property first introduced in SOS 5.0. The description may have multiple lines, but must always be enclosed between {{ and }} characters.

Translations to other languages work exactly the same way, except that the values for rename and description will not be in English.

For example, here are the same two datasets in Traditional Chinese from the translation playlist /shared/sos/kiosk/playlists/locale/datasets/zh_TW.sos:
include = /shared/sos/media/atmosphere/2005_hurricane/grayir/playlist.sos
rename = 2005年颶風季節
description = {{2005年的颶風季節打破了多項記錄,例如颶風最高等級5。總共有28個被命名的風暴,15個颶風,7個極大的颶風,和4個5級颶風。其中最強的是是卡催娜颶風,這個颶風摧毀了密西西比州,路易斯安那州,其中新奧爾良地區超過1600人在風暴中喪生,估計全部損失超過750億美元。}}

include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
rename = 地球-藍色星球
description = {{這顆藍色星球非常詳盡而真實地描繪地球的面貌,這個資料集是由美國太空總署編輯2001年一整年的人造衛星影像所建立起來的。 大部分的訊息來自美國太空總署的輻射光譜影像分析器 MODIS(the Moderate Resolution Imaging Spectroradiometer),它架設在地球上方 435 英里的特拉這顆人造衛星上。陸地與海洋的背景影像是採用從 2001年 6 月至 9 月的所有資料所建立起來的,而不是採用某一天或一個禮拜的資料,因為任何一天,都會有雲層擋住地表某些特定的區域。雲的影像是由資料值所合成的,前二天收集的是可見光波的資料,第三天為了得到極地地區雲層的景觀所採用的是紅外線熱能影像。
海洋的藍色是原本真實的顏色,雲是白色,陸地從綠色到棕色有不同顏色的變化。棕色的部分是沙漠的沙地,編輯陸地影像的資料來自美國地球資源調查地質測量報告和科學資料中心。
其它有關藍色星球的數據,則用來強化地球變化的一些特徵。標準的藍色星球是地球全年平均數據所呈現的景觀。也可根據每個月的資料合成全年的數據圖像,而沒有雲層覆蓋。每個月的變化呈現具有季節性的藍色星球。每個月的演變讓觀眾到地貌的季節性變化。最讓人驚豔的是白雪在冬季逐漸漫天蓋地及在夏季消融的景像。藍色星球也因為沒有雲層的遮蔽,才能清楚看到地表的植被。}}

How to edit translations:

Editing a translation (or English override text) is done by simply modifying the values to the right of the equals sign of either rename or description keywords for any datasets in a translation playlist with your favorite text editor. Be sure the description text is enclosed between {{ and }} characters. Should you wish to remove a particular translation entirely, just delete the lines containing include, rename, and description for any datasets you no longer want.

How to create translations for a new language:

The easiest way to add another language for dataset translations is to start by making a copy of the en_US.sos file, then renaming the copied file to use the locale code to your new langauge. For example, if you wanted to add Turkish, you would use a file named tr_TR.sos copied from en_US.sos. In the new file, replace the English text values with your new language translations to the right of equals sign for the rename or description keywords. Be sure the description text is enclosed between {{ and }} characters.

How to add additional datasets to translations:

If you have modified your kiosk configuration by including datasets not found in the NOAA-defined default configuration, the include paths for those datasets will be set in your group playlists (see the section Group and Dataset Configuration). To add these to your translation playlists, just copy the include lines and add rename and description keywords for each one. Be sure the description text is enclosed between {{ and }} characters.

Deploying your translations:

After finishing your translation changes, run media2kiosk, as the sos user, then transfer the resulting files to the kiosk machine using the FTP tab in the Admin UI.

Translating Group Names

The names for groups in the NOAA Kiosk are generated by the media2kiosk utility and are written to directories under /shared/sos/kiosk/groups, where they are used by the kiosk after being transferred there.

Here is a summary of where the group text display in the kiosk comes from:
  1. The default locale (en_US) names are the filename stems extracted from group playlist filenames. For example, the playlist /shared/sos/kiosk/playlists/groups/air.sos would have the group name air.

  2. Playlists may also be used to define translations for group names. How to use these translation playlists is explained next.

Translation playlists for groups reside on the SOS machine under the /shared/sos/kiosk/playlists/locale/groups directory. This directory holds a set of SOS playlists following the naming convention xx_YY.sos, where xx_YY is the locale code, as described earlier. All the group translations for a given locale are placed together in the same playlist. You may notice that there is an en_US.sos playlist under the groups subdirectory. This does not contain translations per se, but the file contains entries for all the groups in the default kiosk configuration with slightly different text. For example, the name for the group defined in air.sos is Air. This was done to make more attractive looking group labels for the general public and can be thought of a way to override the filename stem text.

Groups are translated similarly to datasets, except that there is no description. Here is an example of a Traditional Chinese translation for the kiosk groups in /shared/sos/kiosk/playlists/locale/groups/zh_TW.sos:

# popular group
include = /shared/sos/kiosk/playlists/groups/popular.sos
rename = 最受歡迎

# air group
include = /shared/sos/kiosk/playlists/groups/air.sos
rename = 大氣

# water group
include = /shared/sos/kiosk/playlists/groups/water.sos
rename = 水文

# land group
include = /shared/sos/kiosk/playlists/groups/land.sos
rename = 地表

# snow_and_ice group
include = /shared/sos/kiosk/playlists/groups/snow_and_ice.sos
rename = 冰雪

# space group
include = /shared/sos/kiosk/playlists/groups/space.sos
rename = 太空

# people group
include = /shared/sos/kiosk/playlists/groups/people.sos
rename = 人文

After finishing your translation changes, run media2kiosk, then transfer the resulting files to the kiosk machine using the FTP tab in the Admin UI.


Appendix A: The Kiosk File Structure

This appendix is a reference that describes the underlying file hierarchy used in the NOAA Kiosk and its user interface. The kiosk software’s appearance and operations are driven entirely by a local file structure in combination with SOS automation interface commands made from the kiosk to the SOS machine. All media used in the kiosk software is locally resident and set up in advance.

Most of the kiosk files are autogenerated on the SOS machine using the media2kiosk utility found in the bin directory of the SOS software installation. This utility must be run from the command line. There are also some files that must be configured directly on the kiosk.

The files structure described below is relative to the kiosk root directory, which is /shared/sos/kiosk on the SOS machine and C:\shared\sos\kiosk on the kiosk machine.


Directories and files required only on the kiosk machine

These files are edited on the Kiosk and are not used on the SOS machine:

config\ UI settings directory
    settings.txt UI properties
    logo.png Image in Kiosk title area (upper left corner)
    en_US.txt Title and label text in English / United States
    xx_YY.txt Title and label text in xx language / YY country

    admin\

Admin UI translations directory
        en_US.ts Admin UI interface elements for US English in text (editable)
        en_US.qm Admin UI interface elements for US English in binary (used by kiosk software)
        xx_YY.ts Admin UI interface elements for xx language / YY country in text (editable)
        xx_YY.qm Admin UI interface elements for xx language / YY country in binary (used by kiosk software)
     info\
Info text directory
        en_US.txt SOS info and kiosk instructions in US English
        xx_YY.txt SOS info and kiosk instructions in xx/YY locale

resource\

Control button image directory
    buttonA.png Control button image (png)
    buttonB.jpg Control button image (jpeg)
    ...

Directories and files required only on the SOS machine

These files are used as input to the media2kiosk utility and are not used directly on the kiosk:

images/ Images directory
    groups/ Group images directory
       GroupA.jpg GroupA button image (jpeg)
       GroupB.png GroupB button image (png)
       ...

playlists/

Kiosk playlists directory
    kiosk.sos a playlist defining the groups in the kiosk
    groups/ Group playlists directory
        overlays.sos playlist of the overlays in the Overlays group
        GroupA.sos playlist of the datasets in GroupA
        GroupB.sos playlist of the datasets in GroupB
        ...

    locale/    Media translation playlists directory
        datasets/
    Dataset translation playlists directory
            en_US.sos
    dataset names/descriptions playlist in US English
            xx_YY.sos     dataset names/descriptions playlist in xx language/YY country
        groups/
    Group translation playlists directory
            en_US.sos
    group names playlist in English / United States
            xx_YY.sos
    group names playlist in xx language / YY country

Directories and files generated on the SOS machine by the media2kiosk utility

These files must be transferred to the kiosk machine:

groups/ Derived directory for groups
     groups.txt listing of all the groups in the kiosk
    GroupA/ Derived directory for GroupA
        datasets.txt listing of the datasets in GroupA
        group.png | .jpg image on the group button (png or jpeg)
        en_US.txt group name in English / United States
        xx_YY.txt group name in xx language / YY country
    GroupB/ ...
        datasets.txt
        group.png | .jpg
        en_US.txt
        xx_YY.txt
    …
    overlays/ ...
    datasets.txt
    en_US.txt
    xx_YY.txt

datasets/

Derived directory for datasets
    ID_#####/playlist/ Derived directory for dataset with ID #####
        thumbnail.jpg image on the dataset button
        properties.txt dataset properties used by the kiosk
        sphere.png | .jpg dataset image shown in the trackball sphere (png or jpeg)
        en_US.txt dataset name/description in English / United States
        xx_YY.txt dataset name in xx language / YY country
    ID_#####/playlist_xyz/ Derived directory for dataset variation xyz with ID #####
        thumbnail.jpg ...
        properties.txt
        sphere.png | .jpg
        en_US.txt
        xx_YY.txt


Appendix B: Setting Up File Transfers Between the SOS Machine and NOAA Kiosk

File transfer between the SOS machine and the kiosk is not trivial since these two machines use very different operating systems, Ubuntu Linux and Microsoft Windows, respectively. Beginning with version 5.1, the kiosk software supports a direct transfer between the two systems from the FTP tab in the Administration UI. This functionality uses the industry standard File Transfer Protocol (FTP) software. On the SOS machine, the very secure FTP daemon (vsftpd) server can be installed using the normal Ubuntu apt-get commands and by editing a few configuration files.

To install vsftpd, follow these steps:

  1. Open a terminal window using the Terminal application
  2. Install the FTP server software:
  3. $ sudo apt-get update
    $ sudo apt-get install vsftpd
  4. Edit the FTP configuration file with a Linux text editor, usually one of these options:
  5. If you're comfortable using a command line editor:
    $ sudo vi /etc/vsftpd.conf
    or if you prefer a more visual editor:
    $ sudo gedit /etc/vsftpd.conf
    • Locate the following lines, uncomment them as needed by removing the leading # character, and make sure the values are set exactly as follows:
    • anonymous_enable=NO
      local_enable=YES
      write_enable=YES
      ascii_upload_enable=YES
      ascii_download_enable=YES
      chroot_local_user=YES
      chroot_list_enable=YES
      chroot_list_file=/etc/vsftpd.chroot_list
      ls_recurse_enable=YES
    • Add the following line at the end of the file:
      local_root=/shared/sos/kiosk
    • Save the file and exit the editor.

  6. Create a file the FTP server will use to authorize the sos user to access the /shared/sos/kiosk directory:
  7. $ sudo vi /etc/vsftpd.chroot_list
    • Add the following line:
      sos
    • Save the file and exit the editor.

  8. Start up the FTP server:
  9. $ sudo service vsftpd restart
  10. Verify that the FTP server is running:
  11. $ ftp localhost
    If the FTP server is running, you will see something like this:
    Connect to localhost.
    220 (vsFTPd 3.0.3)
    Name (localhost:sos):
  12. Create the kiosk root directory if it's not already there:
  13. $ mkdir /shared/sos/kiosk
  14. You are now ready to transfer files between the kiosk and the SOS machine.

Appendix C: The media2kiosk Utility

The media2kiosk command-line utility is used in a terminal window on the SOS machine to prepare files for use by the NOAA Kiosk. This utility resides in the bin directory of the standard SOS installation, typically /shared/sos/bin. It is normally used to generate the kiosk file hierarchy as shown in Appendix A. The generated files are then transferred from the SOS machine to the Windows kiosk machine using the FTP tab in the Administration User Interface.

The available options are displayed by running the following at a command prompt:

$ media2kiosk --help
Usage:
--verbose - write timestamps with logged messages (default is no timestamps)
--logging level - set logging level for messages (default is INFO)
Valid level values are: FATAL, ERROR, WARN, INFO, DEBUG, TRACE
--root directory - specify the kiosk root directory (default is /shared/sos/kiosk)
--remove_all - remove all previously generated dataset/group files
--tr_root directory - use a different translations root directory (default is /shared/sos/kiosk/config/admin)
--skip_datasets - skip dataset conversions (use with ts_to_tsv or tsv_to_ts)
--ts_to_tsv - convert Kiosk ts files to tab separated value (tsv) files. Can't combine with tsv_to_ts!
--tsv_to_ts - convert tab separated value (tsv) files to Kiosk ts files. Can't combine with ts_to_tsv!

The most common use of media2kiosk is to generate the kiosk files that are transferred to the kiosk machine after changing the main group file (/shared/sos/kiosk/playlists/kiosk.sos, the group playlists under (/shared/sos/kiosk/playlists/groups), or translation playlists under (/shared/sos/kiosk/playlists/locale. Less commonly, media2kiosk may be run when changes made to the SOS Data Catalog need to be updated in the corresponding kiosk files.

Important Note: It is a good practice to use the --remove_all option when running media2kiosk to ensure that all the files are generated correctly with the latest changes. Any hand editing of files made under /shared/sos/kiosk/datasets or /shared/sos/kiosk/groups will be overwritten. For that reason we don't recommend doing any file edits in those subdirectories. Instead, hand editing should be done in the files under the /shared/sos/kiosk/playlists directory.

The other options available in media2kiosk are not routinely used.

  • --verbose and --logging are helpful when troubleshooting problems running media2kiosk.
  • --root and --tr_root are used for developer testing.
  • --ts_to_tsv, --tsv_to_ts, and --skip_datasets are experimental and will become regular features in a future release.

Appendix D: Localization/Translations of the Administration User Interface

The Administration User Interface (Admin UI) in the NOAA Kiosk may be localized to other languages. Translating the Admin UI is distinctly different than translating the Public UI, group names, and dataset names and descriptions, which is described in the section, Localization/Translations to Non-English Languages. Translating the Admin UI is non-trivial, so please feel free to contact SOS Support for assistance if you need help beyond what is laid out here.

The Admin UI uses a third-party application called Qt Linguist to assist you in translating from English to another language. You can also use Linguist to modify any existing translations. As shown in Appendix A, there are two translation files for each locale under c:\shared\sos\kiosk\config\admin: xx_YY.ts and xx_YY.qm, where xx = language, YY = country or region, .ts = raw (ASCII) translation format, and .qm = compiled (binary) translation format. You do not need to know details about these formats to perform your translations.

Here are the basic steps to create translations of Admin UI text in a new language on the kiosk machine:
  1. If it is running, close the kiosk application on the Windows machine.

  2. Open Windows Explorer from the Start Menu, navigate to C:\shared\bin, and double click on linguist.exe. The Qt Linguist user interface will be displayed.

  3. From the menubar, select File > Open... In the file browser that pops up, navigate to c:\shared\sos\kiosk\config\admin. Double click on en_US.ts. to open the English language raw translations file and display the contents.
  4. From the menubar, select File > Save As... In the file browser that pops up, enter the raw translation filename for locale you want. For example, for French in France, type fr_FR.ts. Click the Save button to create the new file.

  5. From the menubar, select Edit > Translation File Settings... In the popup window, change the Target Language settings to match the language and country for your translation. For fr_FR, the settings will be Language: French, Country/Region: France.
  6. Using the Linguist controls, go through each English text element by selecting first the Context item and then the first Source text item. Replace the English text in the French translation box with your translation. Then click the green Checkmark icon next to the item or in the toolbar to accept the translation. Note that you may also fill in the French translator comments box if you wish, but that text will not appear in the kiosk.

  7. After translating all the Source text elements for the first Context item, select the next Context item and translate all its Source text elements. Continue in this fashion through the last Context item.
  8. From the menubar, select File > Save to save your translations to the raw translations file.

  9. From the menubar, select File > Release to write your translations to the compiled (binary) translations file.

  10. Test your translations in the kiosk. You will need to be sure your new locale is included in the locale_options property list (see Properties Tab section) so you can select its button on the right side of the Title Area (Component #1).

Appendix E: Using a Utility to Automatically Restart the Kiosk

As mentioned in the Administration and Setup section, you may wish to install a separate application that automatically restarts the NOAA SOS Kiosk if it crashes or a clever kiosk user finds a way to close it intentionally. One free application that does this is called Restart On Crash. It has been successfully used with the NOAA SOS Kiosk is described in this appendix. Note that there many other Windows restart applications available that may work with the NOAA SOS Kiosk and NOAA is not specifically endorsing the use of Restart On Crash.

Information about Restart On Crash is at the link Automatically Restart Crashed Or Hanged Applications. Here are the steps to set up Restart On Crash:

  1. In a web browser, click on the link Download Restart on Crash, which puts the file RestartOnCrash-v1.4.1.zip in your Downloads folder (or a different download location, depending on your browser settings).

  2. Double-click on RestartOnCrash-v1.4.1.zip to unzip the utility. It does not have an installer and it's easiest to just put the RestartOnCrash.exe on the Kiosk machine's Windows Desktop.

  3. Select Settings and enter the full path to a log file where crashes will be recorded in the Settings window. There are a few other options for Restart On Crash you can choose, with suggested settings shown in the screenshot.

  4. Select Add and enter the full path to the Kiosk application (C:\shared\bin\Kiosk.exe) in the Add New Application window. There are a few options you can choose on restarting the kiosk when it isn't running, with suggested settings shown in the screenshot. (the example shown is for Edit Applications Settings, which has exactly the same options)
  5. To turn off Restart On Crash, first open it by right-clicking on its icon in the icon tray (the lower right side of the Windows taskbar), then choosing Show/Hide. In the window that opens, just uncheck the box next to the Application name (C:\shared\bin\Kiosk.exe) in the utility's main window. The Status indicated by Disabled means that the kiosk won't be automatically restarted when it's not running. If you check the box again, then Restart On Crash will start monitoring and restarting it when needed.
  6. Note: When the Restart On Crash program is running and you want to close down the kiosk, you will need to bring up the Restart UI and disable the Application (step 5) within the Grace period time which we recommend set to 30 sec. However, even if the kiosk is running, if you have a keyboard you can also use Alt-Tab to bring up the Windows taskbar, then right click the icon in the icon tray (right side) to open the UI.