TileCutter Online Documentation

Version 0.5.7

Contents

  1. Introduction
  2. Interface
  3. Basic Usage
  4. Command Line Usage
  5. Default File Locations
  6. Any Other Questions
  7. TileCutter Licence

IntroductionMenu

TileCutter is a tool designed to allow easy creation of multi-tile or multi-view building graphics for use with Simutrans. Its primary purpose is to take an image (or set of images) of a building and cut them into the individual paksize tiles used by the game to display the building. It can output source files (.dat and .png), a .pak file (by integrating with the Simutrans Makeobj utility) or both.

InterfaceMenu

TileCutter has two interfaces, a cross-platform graphical user interface (GUI) provided by wxWidgets and a command line interface (CLI). The GUI is used to configure all of the attributes of a cutting operation. The configuration can then be saved to a TileCutter Project (.tcp) file. The CLI can then be used to "compile" the .tcp file and source images into either Simutrans object source files, or a compiled .pak file.

GUIInterface

The GUI is laid out around the image display viewport. This displays the currently selected image. You can tell which image is currently selected by observing the settings in the left-hand image selection pane. Simutrans objects can have a number of different "views", for Front and Back Image, Facing Direction and Seasons. See the Basic Usage section for more info.

Above the image display viewport are controls to select an image file for this view, there is also a button to allow you to reload the source image (this is done automatically at export, TileCutter does not store the source images so you are free to edit them in another application). Below the image display viewport there are controls for the various paths associated with a project. The Project Save Location is the current location of the project's save file; all other paths are relative to this one. This allows you to move the project save file and still keep the same relative paths for exporting files, and reading source files. Below this there are three output locations, for .dat, .png and .pak files. If the .pak output is left blank, or is set to a directory (with a trailing slash) then the default .pak file naming scheme is used by Makeobj.

TileCutter also has a menu bar with the standard functions for saving/loading etc. project files. Under the Tools menu you can set up the .dat file parameters for the project, change the language of the GUI and configure preferences. There is also a function to load the currently selected image for all views in the project - this is useful if you have one source image with multiple views of the building, and want to quickly load it.

CLIInterface

TileCutter's CLI is designed only to allow the scripted processing of .tcp files into .dat/.png and/or .pak files. It permits you to set up many projects, and then rebuild them all at once (e.g. for pakset maintainers). It also allows for platform-specific build scripts to be produced, e.g. as part of an automated process for outputting rendered building images. See the Command Line Usage section for more

If TileCutter is run with the "-c" command line argument the GUI is suppressed and the files specified on the command line will be processed automatically. If the "-c" option is not specified then the files specified on the command line will be opened in GUI mode. The available options can be found by running the command:

tilecutter -h

For example:

Usage: tilecutter.py [options] filename1 [filename2 ... ]

Options:
  -h, --help    show this help message and exit
  -c            run program in CLI mode (must be specified or program will run
                in GUI mode and load the first file specified on the command
                line)
  -i DIRECTORY  override .png file output location to DIRECTORY
  -I FILENAME   override .png file output name to FILENAME
  -n            disable .dat file output (if -m specified, dat info will be
                output to tempfile)
  -d DIRECTORY  override .dat file output location to DIRECTORY
  -D FILENAME   override .dat file output name to FILENAME
  -m            enable .pak file output (requires Makeobj)
  -p DIRECTORY  override .pak file output location to DIRECTORY
  -P FILENAME   override .pak file output name to FILENAME
  -v            enable verbose output
  -q            suppress stdout

You can override the per-project settings for output directories if needed, this is useful when working with other people's project files.

Basic UsageMenu

This step-by-step guide will take you over the basics of project creation with TileCutter

  1. After opening TileCutter the first thing we need to do is add our source images. You do this either by typing the location of the image in the top bar, or by clicking the Browse button next to it. This will open a standard platform-specific file picker dialog. Select the source image (this must be in .png format) and select Open.
  2. You should see your source image loaded into the viewport window. The path to the specific image is displayed in the top bar.
  3. For most projects you will want to specify multiple image views, these could be for a simple purpose like having a different image for the building in the Winter season (or the Snow climate), or more complex needs like Front/BackImages which can be used when creating buildings which vehicles interact with. You can also configure multiple direction views (which is mandatory for odd-shaped buildings, more on this later) so the building looks right when rotated. All of these views are cumulative, so you can have both Summer and Winter images for each rotation, for example.
  4. To use these additional views, check the "Enable Winter" or "Enable FrontImage" buttons. To enable multiple direction views, select the number of views from the dropdown menu. This will enable the radio buttons which can be used to switch views. Notice that switching views causes the image to vanish from the viewport display. This is normal, and if you move back to the original view the image will come back.
  5. If you have one source image with multiple views of an object you may wish to load this one source image for all views. Rather than doing this manually for each view there is a menu item provided under the Tools menu which can do this for you. Simply load one view with your source image and then select "Same File For All Images" from the menu. The image will be loaded for all views, active or not.
  6. For multi-tile buildings it is of course necessary to configure the size and offset. On the main window displayport you may have noticed the red line. This is the cutting mask. Everything inside the red shape will appear in the object when it is compiled and inserted into the game. By default the cutting mask is set to 1 tile by 1 tile. You can change this using the Dimensions control. Key controls here are:
  7. You can also use the Mask Offset to move the mask around the image. This is useful to correct minor alignment errors in the output image, or to select one of multiple views in a source image. The Fine checkbox switches between paksize adjustments and pixel adjustments.
  8. Once you have your views configured you may wish to alter the .dat file properties for your project. This can be done using the .dat File Options menu item (or by pressing shortcut Ctrl+D). At present this is just a text entry box where you can specify any object properties you need to. In future a proper editor will be provided. You can find out about the various options at the Simutrans Wiki. The .dat file properties are saved in the project file, so no separate .dat file is required.
  9. You should be ready to export your project now. Please check the output locations at the bottom of the screen. All three output locations are relative paths from the Project Save Location. You may wish to change these depending on your environment. On Windows, path sections highlighted in Yellow are ones which do not exist. Please ensure that all directories exist since TileCutter will not create them and will give an error. If you leave the .pak Output Location blank, or specify a directory (with a trailing slash) then the default pakfile naming system of Makeobj will be used. You can override this with your own name if you wish.
  10. Once you've configured the output paths you can click on "Cut Image" to export the .dat and .png files to the locations selected. If you don't want to export the .dat file you can deselect the "Write out .dat file" option.
  11. If you wish to have TileCutter compile a .pak file for you as part of the export process you can click on the "Compile .pak" button. Please note that you need to have Makeobj available since TileCutter uses this to make .pak files. By default TileCutter will look for a copy of Makeobj in its installation directory, but you can specify an alternative location using the Preferences dialog accessed from the Tools menu.

Command Line UsageMenu

The CLI interface to TileCutter is designed to allow scripted processing of pre-produced .tcp project files. It does not support direct project creation (use the GUI for that). After creating your project file you can feed it into TileCutter at the command line by running a command such as:

tilecutter -c my_project.tcp

This will then process the project file, producing .dat and .png output as defined by the paths specified in the project.

If you wish to run the output through Makeobj, suppress .dat creation, override the creation directories etc. you can do so by running the command with flags. For example, the following command switches on .pak file creation and redirects pak file creation to "/home/timothy/tilecutter/" for processing the two projects "my_project.tcp" and "my_second_project.tcp":

tilecutter -c -m -p /home/timothy/tilecutter/ my_project.tcp my_second_project.tcp

This interface can be used as part of scripted pakset generation, as part of a workflow for automatically creating rendered objects (e.g. render, post-processing, cutting, Makeobj export) or just to allow one-click object creation as part of an OS-specific script (e.g. Windows Batch file, or Unix Shell Script). If you have a suggestion for an extension to the script interface please let me know.

Default File LocationsMenu

Since version 0.5.7 TileCutter attempts to store its configuration and log files in the standard location for the platform it is running on. The configuration file is called "tilecutter.config" and can be found under one of these locations:

TileCutter will also read configuration from a tilecutter.config file placed in the installation directory. For backwards compatibility only it will similarly read from a tc.config file from an earlier version located in the installation directory.

The log file is called tilecutter.log and can be found under the following locations.

The Windows version can also create a log file called TileCutter.exe.log which will always be found in the directory where the main TileCutter.exe executable is located. This log file will only appear in the case of program errors). The location of the log file can be controlled by specifying the "logfile" parameter in the configuration file. This is set to "system_default" by default which indicates that the above logic will be used to determine the log file location.

Any Other QuestionsMenu

If you have any questions about using TileCutter please feel free to ask on the Simutrans Forum, or PM me (username: Timothy). I can also be contacted by email: tb@entropy.me.uk.

TileCutter LicenceMenu

A reproduction of the TileCutter Licence, for your convenience. This document is covered by the same licence.

Copyright © 2008-2011 Timothy Baldock. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission from the author.

4. Products derived from this software may not be called "TileCutter" nor may "TileCutter" appear in their names without specific prior written permission from the author.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.