TreeMap Server

Setup

Installing TreeMap Server

Installation of TreeMap Server is pretty straight forward and can usually be performed by simply running the appropriate installer and accepting the default settings. For detailed instructions, including customization notes, please follow the platform-specific instructions for Windows, macOS, Unix/Linux below.

Connecting to TreeMap Server

A web server is built into TreeMap Server. Simply launch TreeMap Server and use a web browser to connect to its interface. The default port for the web-based interface is 9090. If you are on the same machine as TreeMap Server, the following URL will usually work: http://127.0.0.1:9090. The default port number can be changed by editing the treemap‑server.vmoptions file in your installation directory.

Setting up TreeMap Server on Windows

  1. Download the Setup Executable from http://www.treemap.com/server/download/

  2. Run the treemap-server_windows_2020_x_x.exe installer

  3. If desired, change the default settings:

    1. Accept or customize the destination directory (default is C:\Program Files\Macrofocus\TreeMapServer\)

    2. Customize the port number if necessary (default is 9090). Choose another port if the default is already used by another service. Port 80 is the standard HTTP port and can be used if no web server is running on the computer.

    3. Customize the datasets location if desired (default is C:\Program Files\Macrofocus\TreeMapServer\data\). You can either make this point to the installation directory of the desktop version of TreeMap (C:\Program Files\Macrofocus\TreeMap\ by default) or any other location where TreeMap data files (with the .mtm extension) are stored. The use of network drive is allowed if multiple people want to share their data files.

    4. If desired, customize the maximum memory that TreeMap Server is allowed to use. 512 MB (the default) should be adequate for small to medium datasets with a low number of concurrent users. If your computer has a lot of RAM, then increasing this value may for sure not hurt.

  4. Enter the user name and the license key as provided in your license certificate. Make sure to enter both exactly as indicated, as they should match.

  5. Once the installation is completed, TreeMap Server is operational. Click Finish and your default Internet browser will start (if you are on the same machine as TreeMap Server) and open the main landing page of TreeMap Server (by default http://localhost:9090/). From there, any dataset available at the datasets location will be listed and is also accessible by appending the file name to the URL, e.g. http://localhost:9090/Forbes%20Global%202000%20-%202022.mtm. Note that potential space characters in the file name have to be replaced by %20.

    1. If there is no firewall or NAT router preventing connection to it, it can also be reached from other computer on the network (and potentially the Internet) by using the IP address of the computer instead of localhost. Finding your computer’s IP address can be done by following the instructions at http://windows.microsoft.com/en-us/windows7/find-your-computers-ip-address. If you have a firewall enabled on the computer, you may have to add an exception to allow connections to the port number TreeMap Server is running on (follow the instructions at http://windows.microsoft.com/en-gb/windows7/open-a-port-in-windows-firewall if you are using Windows Firewall).

    2. TreeMap Server will be started automatically every time the computer starts. It runs as a standard Windows service and a treemap‑server.exe file is in the installation directory. You can use this executable to install and control the TreeMap Server service. You can also use the Services tool in the Windows Control Panel to start and stop the service, or from a console window run the following commands:
      treemap‑server /install — installs the service.
      treemap‑server /uninstall — uninstalls the service.
      treemap‑server /start — starts the service.
      treemap‑server /stop — stops the service.

    3. Advanced users may wish customize paramaters to the runtime environment of TreeMap Server. You can do this by editing the treemap‑server.vmoptions file in the installation directory. Each parameter to the VM should be on a new line of the file. For example, to set the max VM heap size to 1024 MB, you’d use:
      -Xmx1024m

Setting up TreeMap Server on macOS

  1. Download the DMG Archive from http://www.treemap.com/server/download/

  2. Open the archive and run the TreeMap Server Installer application

  3. If desired, change the default settings:

    1. Accept or customize the destination directory (default is /Applications/TreeMapServer)

    2. Customize the port number if necessary (default is 9090). Choose another port if the default is already used by another service. Port 80 is the standard HTTP port and can be used if no web server is running on the computer.

    3. Customize the datasets location if desired (default is /Applications/TreeMapServer/data/). You can either make this point to the installation directory of the desktop version of TreeMap (/Applications/TreeMap/ by default) or any other location where TreeMap data files (with the .mtm extension) are stored. The use of network drive is allowed if multiple people want to share their data files.

    4. If desired, customize the maximum memory that TreeMap Server is allowed to use. 512 MB (the default) should be adequate for small to medium datasets with a low number of concurrent users. If your computer has a lot of RAM, then increasing this value may for sure not hurt.

  4. Enter the user name and the license key as provided in your license certificate. Make sure to enter both exactly as indicated, as they should match.

  5. Once the installation is completed, TreeMap Server is operational. Click Finish and your default Internet browser will start (if you are on the same machine as TreeMap Server) and open the main landing page of TreeMap Server (by default http://localhost:9090/). From there, any dataset available at the datasets location will be listed and is also accessible by appending the file name to the URL, e.g. http://localhost:9090/Forbes%20Global%202000%20-%202022.mtm. Note that potential space characters in the file name have to be replaced by %20.

    1. If there is no firewall or NAT router preventing connection to it, it can also be reached from other computer on the network (and potentially the Internet) by using the IP address of the computer instead of localhost. Finding your computer’s IP address can be done by following the instructions at http://support.apple.com/kb/PH10658. If you have a firewall enabled on the computer, you may have to add an exception to allow connections to the port number TreeMap Server is running on (follow the instructions at http://support.apple.com/kb/PH4358 if you are using macOS Firewall).

    2. TreeMap Server will be started automatically every time the computer starts. It runs as a standard daemon and a treemap‑server executable file is in the installation directory. You can use this executable to control the TreeMap Server daemon from a Terminal window by running the following commands:
      treemap‑server start — starts the daemon.
      treemap‑server stop — stops the daemon.
      treemap‑server status — displays status information about the daemon.
      treemap‑server restart — restarts the daemon.

    3. Advanced users may wish customize paramaters to the runtime environment of TreeMap Server. You can do this by editing the treemap‑server.vmoptions file in the installation directory. Each parameter to the VM should be on a new line of the file. For example, to set the max VM heap size to 1024 MB, you’d use:
      -Xmx1024m

Setting up TreeMap Server on Linux/Unix

If you are running on a Red Hat or Red Hat like system (CentOS, Fedora, etc), we recommend using the RPM as it contains some custom handling of the standard Red Hat like environment. Assuming that you have used the RPM, you can start and stop TreeMap Server using the /etc/init.d/treemap-server script.

    # /etc/init.d/treemap-server
    Usage /etc/init.d/treemap-server {start|stop|restart|status|condrestart|reload}
    # /etc/init.d/treemap-server start
    Starting treemap-server:

If you are running on a different Linux/Unix varient, and/or you have used the .tar.gz 'installer', you can start and stop TreeMap Server using the treemap-server script in your installation directory:

    # ./treemap-server
    Usage: ./treemap-server {start|stop}
    # ./treemap-server start
    Starting treemap-server

Usage

Selecting Views

TreeMap Server allows passing the views that should be displayed as part of the URL by appending a comma-separated list with the possible values TreeMap, TreePlot, TreeTable,Table, Configuration, Filters, Details, MenuBar, StatusBar to the ?views= parameter. Just remove the one you don’t want the users to be exposed to. Here is an example:

https://public.treemap.com/Forbes%20Global%202000%20-%202021.mtm?views=TreeMap,TreePlot,Details,StatusBar

Client-side vs server-side rendering

By default, TreeMap Server sends to the web browser a full implementation of the TreeMap software so that all computations take place within the browser. It is also possible to have the treemap computed and rendered on the server side by prepending ssr to the path, for example:

https://public.treemap.com/ssr/Forbes%20Global%202000%20-%202021.mtm

Note
Server-side rendering puts additional load on the server and therefore require more carefull planning in term of resources should a lot of viewers be expected.

Embedding treemaps

An interactive treemap can be embedded in a web page by overriding the treeMapInit() method and attaching one or more treemaps to specified div identifiers:

<html>
    <head>
        <script type="application/javascript">
            function treeMapInit(app) {
                app.attach("treemap", "https://public.treemap.com/rest/json/Forbes%20Global%202000%20-%202022.mtm");
            }
        </script>
    </head>
    <body>
        <div id="treemap" style="width: 75%; height:738px; border-width: thin; border-style: groove;">
        </div>
    </body>
</html>

Dynamic data

TreeMap Server can be used to fetch data from dynamic sources, such as databases. Constructing the appropriate DataSource object can be achieved by loading the data using the desktop version of TreeMap and exporting the settings. This settings can be placed as .mtm file on the server and as in the example below used to place arbitrary SQL queries:

<?xml version="1.0" encoding="UTF-8"?>
<TreeMap>
    <DataSource type="JDBC" url="jdbc:mysql://localhost/jira" username="root" password="secret" query="SELECT * FROM jiraissue;" driver="MySQL"/>
    <Variables>
        <Default algorithm="Squarified+"/>
        <Variable index="0" name="ID" showPopup="true" colorMin="10000.0" colorMax="10905.0" showLabel="true"/>
        <Variable index="1" name="pkey" showPopup="true"/>
        <Variable index="2" name="PROJECT" showPopup="true" colorMin="10000.0" colorMax="10001.0" showLabel="true" colormap="predefined">
            <Colormap type="predefined" palette="Blues" minimum="10000.0" maximum="10001.0" numberOfSteps="0" inverted="false" brightness="0" saturation="0" overflowColor="#08306b" underflowColor="#f7fbff" missingValuesColor="#7f7f7f"/>
            <Colormap type="custom" mode="Ramps" brightness="0" saturation="0" overflowColor="#008000" underflowColor="#ff0000" missingValuesColor="#7f7f7f">
                <Entry fraction="0.0" absolute="10000.0" color="#ff0000"/>
                <Entry fraction="0.5" absolute="10000.5" color="#ffffff"/>
                <Entry fraction="1.0" absolute="10001.0" color="#008000"/>
            </Colormap>
        </Variable>
        <Variable index="3" name="REPORTER" showPopup="true"/>
        <Variable index="4" name="ASSIGNEE" showPopup="true"/>
    </Variables>
    <Configuration>
        <GroupBy>
            <Variable name="REPORTER" index="3"/>
        </GroupBy>
        <Size variableName="ID" variableIndex="0"/>
        <Color variableName="PROJECT" variableIndex="2"/>
        <Height/>
        <Label>
            <Variable name="pkey" index="1"/>
        </Label>
        <Tooltip>
            <Variable name="ID" index="0"/>
            <Variable name="pkey" index="1"/>
            <Variable name="PROJECT" index="2"/>
            <Variable name="REPORTER" index="3"/>
            <Variable name="ASSIGNEE" index="4"/>
        </Tooltip>
        <Background/>
    </Configuration>
    <TreePlot/>
</TreeMap>

FAQ

How do I upload data files created by the desktop version of TreeMap, to the TreeMap Server?

You can upload files from within the web interface, as long as the upload mechanism has been enabled during the installation process (disabled by default). You can also manually place the .mtm files created by the desktop version of TreeMap in the dataset location folder set during the installation (by default C:\Program Files\Macrofocus\TreeMapServer\data\ on Windows and /Applications/TreeMapServer/data on macOS). The location of this folder can be adjusted either by editing the treemap-server.vmoptions file or by running the installer again (e.g. to make it point to the same location that is used by the desktop version of TreeMap).
We are going to provide an upload mechanism from within the desktop version of TreeMap in a forthcoming version.

Is it possible to hide the task bar at the bottom of the interface?

Yes, this can be achieved by adding the "!/taskBar=false" option at the end of the URL, for example http://public.treemap.com/!/taskBar=false to hide the task bar at for the directory listing and https://public.treemap.com/Forbes%20Global%202000%20-%202022.mtm!/taskBar=false for a specific data file.

Can I organize the files in subfolders?

Yes, but currently we are now showing the subfolders in the directory listing. As an example, it is possible to access http://public.treemap.com/secret/ even though it is not listed in http://public.treemap.com/. Using this method, it is also possible to make specific subfolders only available to closed user groups by only communicating its location with these users.