From WeoGeo Support

Developer: WeoApp

Third Party Developer Documentation >> Developer: WeoApp

Overview

Note: This documentation is current as of WeoApp version 0.7.0. To see how to determine the version of your WeoApp, click here.

WeoGeo provides a client side application, the WeoApp, for communicating with your Library or the WeoGeo Market. The WeoApp is used to:

1. Preview how a new Listing will appear
2. Communicate with the Library/Market to create new Listings
3. Facilitate downloads

The Listing WeoFile is used to invoke the first and second functions above, and the Download WeoFile is used to invoke the third function.

Installation of the WeoApp

Four versions of the WeoApp are available on the Download WeoApp web page. These are for the following operating systems:

• Windows (XP SP2 and greater)
• Mac OS X (10.4 and greater)
• Linux 32-bit
• Linux 64-bit

The links on the Download WeoApp web page lead to the latest version of the binary installation files. These links are valid for both first-time installation and for upgrading to the latest version of the WeoApp.

Click the link that reflects your operating system, save the installation file to your local file system, and execute it once the download is complete. The installation will provider further instructions for completion.

gWeoApp (Graphical WeoApp)

The WeoApp is typically run via its Graphical User Interface, which allows the user to see a preview their listing before upload. More information on using the gWeoApp can be found on its wiki page.

WeoApp Command Line

Typically, the WeoApp is invoked with a single parameter: either the Listing WeoFile or the Download WeoFile. When invoking the WeoApp with a fully specified Listing WeoFile, no further action is needed. The progress of the Listing and Upload is printed to the screen. Please be aware that when uploading or downloading large files, the progress may seem to freeze. This is because progress calculation is currently based on file number i.e. 3 of 10 files = 30% done rather than progress for each file.

Using WeoApp

WeoApp is, by nature, a modular application. The steps that it carries out during an upload process are discrete enough to be carried out independently of each other, as long as they are done in order. Given this modular nature, WeoApp needs a location where it can keep the state of any of its uploads. This location depends on the operating system that is running WeoApp, and they are:

• Windows XP: c:\Documents and settings\$(logged_in_user)\Application Data\.weoapp\
• Windows Vista: c:\Users\$(logged_in_user)\AppData\Roaming\.weoapp\
• Linux and OSX: $(HOME)/.weoapp/

Usually this directory will always include the following files:

• log -> general weoapp log file.
• gweoapp.cfg -> configuration file for gWeoApp. It is best not to manually change this file.
• template.xml -> template file for gWeoApp. This file gets overwriten by gWeoApp often so it should not be modified directly.

In addition to the files above, WeoFile will create new files for uploads according to the following rules:

• For any given job with a token assigned to it, WeoApp will print everything related to that token in a log file called $(token).log
• For any given upload with a token assigned to it, WeoApp will write everything that it creates regarding that upload in a subdirectory called $(token)/
• For any given upload with a token assigned to it, for operations that change the WeoFile given to WeoApp, it will save the new, modified, WeoFile at location $(token)/weoapp.weo. This file is referred to as the default WeoFile.

The steps that WeoApp takes depend on which mode it is operating under. There are two main modes: upload and download; and several simpler modes that generally do a single operation. The operations that each mode performs are described below:

• Upload: the main WeoApp mode of operation:
  • Creates previews.
  • Creates the tileset.
  • Creates the KML file.
  • Validates the WeoFile against its XSD.
  • Calculates MD5sums for every files to be upload to WeoGeo.
  • Performs the upload.

• Download: WeoApp runs in this mode when provided witha download WeoFile. The steps in this mode are the following:
  • Download every file described in the download WeoFile.
  • Check MD5 sums to check the download.
  • Decompress those files that were compressed.

• Clean up: WeoApp runs in this mode if any of the cleaning options are given to it. The operations performed in this mode depend on the options passed to WeoApp. Every clean up operation may be performed at once by passing all the clean up options.

• Miscellaneous modes: the following options will set WeoApp in their particular mode, WeoApp will perform the action desired and then immediately exit:
  • --add-group
  • --get-groups
  • --get-template
  • --get-token
  • --help
  • --info
  • --library-info
  • --shell
  • --set-cache
  • --size
  • --validate
  • --verify
  • --version

To accomplish all these different tasks, WeoApp makes use of numerous options. Simply typing the weoapp command with no parameters, or the --help option, will list all the available options. The options are described in details in the following section:

Detailed options descriptions

Option: add-group

--add-group=$(new_group_name), -A$(new_group_name)

Adds a new group called $(new_group_name). If a WeoFile with a valid weogeo hostname is not provided then the --website options must be used too to specify which weogeo library to apply the change to. This option requires valid admin credentials.

Sample run:

$ weoapp --add-group test_group --website testserver.weogeo.com
<?xml version="1.0" encoding="UTF-8"?>
<group>
  <created-at type="datetime">2009-10-19T17:58:10-04:00</created-at>
  <id type="integer">1</id>
  <library-id type="integer">1</library-id>
  <name>test_group</name>
  <updated-at type="datetime">2009-10-19T17:58:10-04:00</updated-at>
</group>
Groups successfully obtained

Option: catcher

--catcher=$(catcher), -a$(catcher)

Tells WeoApp to use catcher $(catcher) to process the request. This option should only be used to specify the catcher host in the particular, and rare, case that tag dataset/catcher/host is not set in the WeoFile. This option does not produce any specific output.

Option: catcher-allocate

This option is meant for internal testing by WeoGeo. It is included here only for thoroughness.

Option: catcher-process

This option is meant for internal testing by WeoGeo. It is included here only for thoroughness.

Option: catcher-upload

This option is meant for internal testing by WeoGeo. It is included here only for thoroughness.

Option: clean-cache

--clean-cache, -k

Tells WeoApp to clean the user credentials that have been stored. Nothing happens if not credentials are stored. This function sets WeoApp in clean up mode, all non clean up options will be ignored.

Sample run:

$ weoapp --clean-cache
Cleaning cache
Cleaning complete

Option: clean-gui

--clean-gui, -U

Tells WeoApp to clean up gWeoApp's temporary files if any are present. Nothing happens if there are no gWeoApp's temporal files. This function sets WeoApp in clean up mode, all non clean up options will be ignored.

Sample run:

$ weoapp --clean-gui
Cleaning gui
Cleaning complete

Option: clean-logs

--clean-logs, -K

Tells WeoApp to clean up its log files. Nothing happens if there are no WeoApp log files. This function sets WeoApp in clean up mode, all non clean up options will be ignored.

Sample run:

$ weoapp --clean-logs
Cleaning logs
Cleaning complete

Option: clean-tokens

--clean-tokens, -T

Tells WeoApp to clean up its token subdirectories. Nothing happens if there are no token subdirectories. This function sets WeoApp in clean up mode, all non clean up options will be ignored.

Sample run:

$ weoapp --clean-tokens
weoapp --clean-tokens
Cleaning tokens
Cleaning complete

Option: continue

--continue, -N

Tells WeoApp to use the following options: --no-info, --no-preview, --no-interpolated-previews, --no-tiles, --no-kml, --no-misc, --no-md5. See their individual description for details.

Option: debug

--debug, -B

Tells WeoApp to record more information in its log files.

Option: download-directory

--download-directory=$(path_to_directory), -d$(path_to_directory)

For a download operation, tells WeoApp to download to files to $(path_to_directory). This option should only be used when using a download WeoFile.

Sample output:

$ weoapp --download-directory=/download_here/ download_weofile.weo
Downloading file_one.tif.gz
Downloading file_two.txt.gz
Extracting from file_one.tif.gz
Extracting from file_two.tif.gz
Download completed for download_weofile.weo

Option: get-groups

--get-groups, -p

Gets the groups information for a given WeoGeo library. If a WeoFile with a valid WeoGeo host name is not provided then a valid WeoGeo host must be given to WeoApp with the --website option. The use of this option requires valid admin credentials.

Sample output:

$ weoapp --get-groups --website testserver.weogeo.com
<?xml version="1.0" encoding="UTF-8"?>
<groups type="array">
  <group>
    <created-at type="datetime">2009-09-24T13:56:03-04:00</created-at>
    <id type="integer">1</id>
    <library-id type="integer">1</library-id>
    <name>Sample_Group_Name</name>
    <updated-at type="datetime">2009-09-24T13:56:03-04:00</updated-at>
  </group>
</groups>

Option: get-template

--get-template, -E

Tells WeoApp to retrieve gWeoApp's template file. The location that the template file is stored in may be set with the --output option. gWeoApp's template file is a text document used to control what is shown by gWeoApp's interface. This option is included here for thoroughness.

Option: get-token

--get-token, -g

Tells WeoApp to retrieve a new token ready to be used. If a WeoFile with a valid WeoGeo host name is not provided then a valid WeoGeo host must be given to WeoApp with the --website option. The use of this option requires valid admin credentials.

Sample output:

$ weoapp --get-token --website testserver.weogeo.org
User information obtained from cache
ce53d521-9645-d35b-a142-4d22dd87bb92
Token successfully obtained

Option: GUI

--GUI, -G

Tells WeoApp to encase its output in well know tags to ease the processing of WeoApp's output for derivative applications. This option should probably be use only when the output from WeoApp is meant to be ingested by other applications.

Sample output:

$ weoapp --clean-logs --clean-cache --clean-tokens --clean-logs --GUI
:weoapp-summary:Cleaning logs:end:
:weoapp-summary:Cleaning tokens:end:
:weoapp-summary:Cleaning cache:end:
:weoapp-complete:Cleaning complete:end:

Option: gui-previews

--gui-previews, -F

Tells WeoApp to create special preview images to be ingested by gWeoApp. These preview images are two square 316x316 pixel images named image1_tile.jpg and image1_zoom.jpg. image1_tile.jpg shows the the complete preview image, image1_zoom.jpg should the center of the original preview file in its original resolution.

Option: help

--help, -h

Tells WeoApp to print its help menu. No other processing will be performed.

Option: info

--info, -i

Tells WeoApp to extract all the information it can from the file pointed to by tag dataset/data_files while doing no actual processing. Currently WeoApp can only extract information from the following raster file formats: GeoTiff, JPG, ERDAS img, ESRI hdr, ENVI hdr. The information extracted will be stored in the default WeoFile. The information may be stored in a different file by using the --output option.

Sample output:
Given the following WeoFile:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
  <token>f6e11106-daa6-dd5a-9fd0-fa796ac470e9</token>
  <data_files>/Users/test_user/data/example.tif</data_files>
  <weocatch>
    <host>testserver.weogeo.com</host>
    <port>80</port>
  </weocatch>
</dataset>

The file in tag dataset/data_files is a raster geotif file. Performing the following call to WeoApp:

$ weoapp --info sample_weofile.weo

Yields the following WeoFile:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
  <meta>
    <mask_samples/>
    <mask_lines/>
  </meta>
  <original_projection_values>
    <utm>
      <zone>17</zone>
    </utm>
  </original_projection_values>
  <layers>Layer_1 Layer_2 Layer_3</layers>
  <rgb_bands>
    <blue>3</blue>
    <green>2</green>
    <red>1</red>
  </rgb_bands>
  <projection>UTM</projection>
  <pixel_type>Byte</pixel_type>
  <file_format>GeoTiff</file_format>
  <palette>0</palette>
  <number_of_layers>3</number_of_layers>
  <boundaries>
    <original>
      <datum>NAD27</datum>
      <east>359984.0800970000</east>
      <south>3090456.4005100001</south>
      <west>352546.9600970000</west>
      <north>3094266.4005100001</north>
      <line_pixel_size>-10.1600000000</line_pixel_size>
      <sample_pixel_size>10.1600000000</sample_pixel_size>
      <number_of_lines>375</number_of_lines>
      <number_of_samples>732</number_of_samples>
    </original>
  </boundaries>
  <data_type>raster</data_type>
  <token>f6e11106-daa6-dd5a-9fd0-fa796ac470e9</token>
  <data_files>/Users/test_user/data/example.tif</data_files>
  <weocatch>
    <host>testserver.weogeo.com</host>
    <port>80</port>
  </weocatch>
</dataset>

Option: kamap-resample-algorithm

--kamap-resample-algorithm=$(algorithm), -Y$(algorithm)

Tells WeoApp to use the resampling algorithm $(algorithm) for the interpolated preview creation step. There are only two algorithms available: bilinear, which is the default, and nearest neighbor.

Option: kml-resample-algorithm

--kml-resample-algorithm=$(algorithm), -Z$(algorithm)

Tells WeoApp to use the resampling algorithm $(algorithm) for the kml creation step. There are five different algorithms available: nearest neighbor, bilinear, cubic, cubic spline, and lanczos.

Option: l2m

This option is meant for internal testing by WeoGeo. It is included here only for thoroughness.

Option: library-info

--library-info, -C

Gets general library information for a given WeoGeo library. If a WeoFile with a valid WeoGeo host name is not provided then a valid WeoGeo host must be given to WeoApp with the --website option. The use of this option requires valid admin credentials.

Sample Output:

$ weoapp --library-info --website testserver.weogeo.com
User information obtained from cache
<?xml version="1.0" encoding="UTF-8"?>
<library>
  <admin-user-id type="integer">1</admin-user-id>
  <allow-registration type="boolean">true</allow-registration>
  <created-at type="datetime">2009-01-21T14:47:46-05:00</created-at>
  <default-lat type="decimal" nil="true"></default-lat>
  <default-lng type="decimal" nil="true"></default-lng>
  <default-zoom type="integer">5</default-zoom>
  <enable-access-control type="boolean">true</enable-access-control>
  <id type="integer">1</id>
  <invite-code nil="true"></invite-code>
  <last-invoiced-on type="date" nil="true"></last-invoiced-on>
  <logo-file-name nil="true"></logo-file-name>
  <name>testserver</name>
  <start-invoicing-on type="date" nil="true"></start-invoicing-on>
  <status>active</status>
  <subdomain>testserver</subdomain>
  <tier-name>organization</tier-name>
  <updated-at type="datetime">2009-05-05T16:23:27-04:00</updated-at>
  <user-limit type="integer">15</user-limit>
  <user-count type="integer">10</user-count>
  <storage-limit type="integer">1000000000</storage-limit>
  <total-hosted-data type="integer">50000</total-hosted-data>
</library>
Library information successfully obtained

Option: max-preview-dim

--max-preview-dim, -J

Sets the upper bound for the dimensions of a preview image created by WeoApp. The default is 65500 pixels and the value provided to this option must be equal to the default of smaller. This option may be used to force the generation of smaller preview files, and thus smaller tile sets, if desired.

Option: min-preview-dim

--min-preview-dim, -j

Sets the lower bound for the dimensions of a preview image created by WeoApp. The default is 500 pixels. This option may be used to force the generation of smaller preview files, and thus smaller tile sets, if desired.

Option: no-delete

--no-delete, -x

In its regular processing mode, WeoApp will delete the temporary files it creates when it is done. This option may be used to stop WeoApp from deleting these files.

Option: no-info

--no-info, -n

In its regular processing mode, WeoApp will always attempt to read information from the file pointed to by tag dataset/data_files. Use this option to stop WeoFile from trying to extract any information from those files. This option is most useful when tag dataset/data_files is pointing to files which are not natively supported by WeoApp.

Option: no-initial-token-verification

--no-initial-token-verification, -t

In its regular processing mode, the first thing WeoApp does is verify the validity of the token inside the WeoFile it is operating on. Use this option to stop WeoApp from verifying the token. This option should only be used for testing purposes.

Option: no-interaction

--no-interaction, -I

In its regular processing mode WeoApp will prompt the user for a username and password any time one of its operations require credentials and it is not able to automatically retrieve saved credentials. This options may be used to prevent the credentials prompt from being displayed and force WeoApp to fail on missing credentials error.

Sample output:
WeoApp asking for user credentials:

$ weoapp --get-token --website testserver.weogeo.com
Username and password needed to testserver.weogeo.com
Username: test_server
Password: 
Would you like to save these credentials [y/N]: y
bc526d14-8b0e-db56-a6ce-14bd93f6c9c0
Token successfully obtained

Using the --no-interaction-option:

$ weoapp --get-token --website testserver.weogeo.com --no-interaction
ERROR: Can not obtain token from testserver.weogeo.org: Non-interactive mode prohibits asking
username/password (Weoapp.cpp:766)

Option: no-interpolated-previews

--no-interpolated-previews, -r

In its regular processing mode, WeoApp will create a number of preview images at different zoom levels from the original preview file at dataset/preview_files. These preview images are the base of the tiles and their output location is stored in dataset/tileset/preview_files. This option stops WeoApp from creating this set of preview images. If a set of preview images is intended to be the base for the tiles and is created without WeoApp's involvement then this option must be used.

Option: no-kml

--no-kml, -m

In its regular processing mode, WeoApp will create a kml preview file. This option stops WeoApp from creating this preview file and allows users to provide their own kml preview file in dataset/kml_preview_file. If this option is not used then WeoApp will attempt to create a low resolution KML image from the preview images in dataset/preview_files and apply the mask file to it.

Option: no-misc

--no-misc, -M

In its regular processing mode, WeoApp will take all the miscellaneous files provided in the tag dataset/misc_files and will compress and archive them into a single ZIP file, which is then uploaded. Use this option to stop WeoApp from performing that step.

Option: no-preview

--no-preview, -P

In its regular processing mode, WeoApp will create a preview file from any supported raster files provided in the tag dataset/data_files. Use this option to stop WeoApp from creating a preview file from the original data. This options must be used if the user desires to provide his own preview file with the tag dataset/preview_files or if the data is not one of the five supported file formats.

Option: no-tiles

--no-tiles, -m

In its regular processing mode, WeoApp will create tiles from the preview files pointed to by tag dataset/tileset/preview_files. This options may be used to stop WeoApp from performing this step. This option must be used it the user wants to provide his own tilepack by filling out all the information in the tag dataset/tileset.

Option: no-upload

--no-upload, -u

The last step in WeoApp's regular processing mode is to upload all the necessary files to WeoGeo. This option tells WeoApp to skip that step. This option may be used to preview all the steps WeoApp can do without performing the upload, then, if WeoApp has performed satisfactorily, do the upload by itself later.

Option: no-xml-validation

--no-xml-validation, -X

In its regular processing mode, WeoApp will validate the WeoFile against its XSD and inform the user if something is wrong. This option may be used to stop WeoApp from performing that step. This option is strictly a debugging option and must be used for all jobs that are intended to be uploaded to a WeoGeo library, in other words, if this option is used then option --no-upload should also be used.

Sample output:
Passing a WeoFile to WeoApp that does not validate:

$ weoapp invalid_weofile.weo
Getting token from website
User information obtained from cache
bc57c0e7-2f3d-0a5f-b81b-36cce0e5fb80
Verifying token with website
Creating first preview image
Creating second preview image
Downsizing preview images
Creating thumbnail
Creating small preview
Creating tileset
Creating kml.png
Validating XML
User information obtained from cache
VALIDATOR ERROR: <?xml version="1.0"?>
<errors>
  <error>
    <element>/dataset/name</element>
    <message>The 'name' is required at this point.</message>
  </error>
  <error>
    <element>/dataset/tags</element>
    <message>At this point, the tags field cannot be empty.</message>
  </error>
</errors>
 (Weoapp.cpp:1221)

Option: output

--output=$(path_to_file), -o$(path_to_file)

Normally WeoApp always writes out to its default WeoFile. Use this option to tell WeoApp where to write its output WeoFile. If $(path_to_file) does not exists then it will be created; if $(path_to_file) already exists then it will be overwritten.

Option: shell

--shell=$(token), -s$(token)

Tells WeoApp to retrieve a shell (skeleton) WeoFile for the given token. If a WeoFile with a valid WeoGeo host name is not provided then a valid WeoGeo host must be given to WeoApp with the --website option. By default WeoApp will store the new shell WeoFile with the default WeoFile name, this behavior may be overridden by using the --output option.

Sample output:

$ weoapp --shell=f811a8a7-d657-c15a-b10d-9132e5693dee --website testserver.weogeo.com
Shell WeoFile successfully obtained.

The following is a shell WeoFile, which only contains the most basic information.

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
  <token>f811a8a7-d657-c15a-b10d-9132e5693dee</token>
  <hosted>true</hosted>
  <weogeo_mode>library</weogeo_mode>
  <weogeo_host>testserver.weogeo.com</weogeo_host>
  <weocatch>
    <host>testserver.weogeo.org</host>
    <port>80</port>
  </weocatch>
</dataset>

Option: set-cache

--set-cache=$(username:password), -W$(username:password)

Tells WeoApp to store the credentials $(username:password). If run without an argument then the credentials prompt will be displayed; this is considered safer since credentials passed in the command line will be visible in any list of running processes. If credentials are stored by WeoApp then any of the calls which require admin credentials will automatically read them from the stored location and the credentials prompt will not be displayed. If a WeoFile with a valid weogeo hostname is not provided then the --website options must be used to tell WeoApp which library the credentials apply to.

Sample output:
Without the argument:

$ weoapp --set-cache --website testserver.weogeo.com
Username and password needed to testserver.weogeo.org
Username: test_server
Password: 
Password cache successfully set

Passing the credentials in the command line directly:

$ weoapp --set-cache=test_username:test_password --website testserver.weogeo.org
Password cache successfully set

Option: set-token

This option is meant for internal testing by WeoGeo. It is included here only for thoroughness.

Option: silent

--silent, -S

Suppresses regular output from WeoApp. Will not suppress error output and prompts.

Option: size

--size, -z

Tells WeoApp to print the size of its local data directory in bytes.

Sample output:

$ weoapp --size
6474
Size request completed

Option: use-png

--use-png, -H

Tells weoapp to use files in PNG format as intermediate files instead of JPG files. This is useful if it is desireable to bypass the inherent 64K row/column limit of the JPG format.

Option: validation-stage

--validation-stage=$(validation_stage), -q$(validation_stage)

Tells WeoApp to validate the given WeoFile at validation stage $(validation_stage) when it performs the WeoFile validation. Default stage is 50. This options will usually be used together with option --validate. Please see the validator section for more details on validation levels.

Option: validate

--validate, -V

Tells WeoApp to perform only the WeoFile validation step and print the results. If the --validation-stage option is not provided to explicitly set a validation stage then stage 50 will be used. Please click here for more details on validation levels.

Sample output:

$ weoapp --validate --validation-stage=90 test_weofile.weo
User information obtained from cache
<?xml version="1.0"?>
<errors>
  <error>
    <element>/dataset/data_type</element>
    <message>A data type ('raster' or 'other') is required at this point.</message>
  </error>
  <error>
    <element>/dataset/description</element>
    <message>The description is required at this point.</message>
  </error>
  <error>
    <element>/dataset/name</element>
    <message>The 'name' is required at this point.</message>
  </error>
  <error>
    <element>/dataset/tags</element>
    <message>At this point, the tags field cannot be empty.</message>
  </error>
  <error>
    <element>/dataset/projection</element>
    <message>The projection tag is required at this point.</message>
  </error>
  <error>
    <element>/dataset/file_format</element>
    <message>The file format is required at this point</message>
  </error>
  <error>
    <element>/dataset/data_files</element>
    <message>data files must be provided at this point.</message>
  </error>
  <error>
    <element>/dataset/tilepack_file_size</element>
    <message>the file size for a tilepack is required at this point.</message>
  </error>
  <error>
    <element>/dataset/tilepack_file</element>
    <message>a tilepack is required at this point.</message>
  </error>
</errors>
Weo file has been successfully submitted to validation server for test_weofile.weo

Option: verify

--verify=$(token), -e$(token)

Tells WeoApp to perform only the token validation step and print the result. If a WeoFile with a valid weogeo hostname is not provided then the --website options must be used too to specify which weogeo library to apply the change to.

Sample output:
With a valid token:

$ weoapp --verify=43f1d0a4-7935-7057-ae92-0a7e4b02fa0e --website testserver.weogeo.com
Token is OK
Verification complete

With an invalid token:

$ weoapp --verify=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa --website testserver.weogeo.com
Invalid token:
Verification complete

Option: version

--version, -v

Tells WeoApp to print its version number and quit.

Sample output:

$ weoapp --version
0.6.0

Option: website

--website=$(website_address), -w$(website_address)

Tells WeoApp to use WeoGeo host at $(website_address) for anything that requires a WeoGeo host. This option will override the WeoGeo host in tag dataset/weogeo_host.

Option: zoom-levels

--zoom-levels=$(number_of_zoom_levels), -y$(number_of_zoom_levels)

Tells WeoApp to create $(number_of_zoom_levels) preview images at different zoom levels. The default value is 6. Passing value 0 (zero) will tell WeoApp to create the best number of zoom levels according to the image parameters. If not 0 then $(number_of_zoom_levels) should be greater than or equal to 2, one representing the most zoomed out preview image, and one representing the most zoomed in preview image.