JTexSynth
Documentation
Quick quide
In order to synthesize textures you should follow these simple steps:
- Select source image
- Specify target image size (width and height)
- Select synthesis plugin
- Set plugin specific settings
- Press the 'Go' button
- If satisfied with the result save the synthesized image. If not go back to step 2 or possibly 4.
Complete quide
Introduction
JTexSynth is a program that generates large texture images from small samples. The results vary with the sample image, the algorithm used for the synthesis, the settings and maybe even luck. The program is simple to use. You just load a sample image, adjust a couple of settings, hit the 'Go' button and wait for the results to appear.
In the picture below you can see part of the main window of JTexSynth. As you can see there aren't many settings to be bothered with. The bottom part of the window (not visible in the picture) is reserved for algorithm specific settings. This picture and the numbers in it will be used as a reference throughout this guide.
Installation
JTexSynth is written in Java so it should be easy to run it on every environment. You need a Java run time environment which can be get from Sun. After you have set up the Java run time environment download the binary package (the package ending with .jar) of JTexSynth from the download page. You can start the application by double clicking the icon of the package. If that doesn't work then try typing to command line:
java -jar JTexSynth-[version].jar
where version is the version of the program you have. When you succesfully start the program you will see a window which should look something like the following image.
Selecting a source image
The very first step in using JTexSynth is selecting the source image. There are two ways of doing this. Select File→Load source image... from the menu bar or press the button with three dots in it next to the source image text field (number 1 in the picture above). Either way you get a file selection dialog from which you can select your sample image.
Once you select a source image a new window will appear showing the source image. You can toggle the visibility of this image from the meny bar by selecting View→View source image. The check mark next to the menu selection corresponds to the present state of the window. You can also hide the source image window by pressing the closing button of the window (if your window manager/operating system provides one).
Specifying target image size
Next you specify how big an image you want to synthesize. You do this by entering the dimensions (width and height) in to the text fields (number 2 in the picture above). The values represent the dimensions in pixels. The values entered must be positive integers naturally. If you enter invalid values or fail to enter anything and try to start the synthesis an error message is produced.
Selecting the synthesis plugin (algorithm)
JTexSynth includes a selection of algorithms to be used in the texture synthesis. If you don't know the specific features of a particular algorithm you can always use it with trial and error. If you know the very nature of an algorithm it might be easier for you to understand and adjust the algorithm specific settings. Texture synthesis algorithms might not be very simple to understand. They make use of advanced mathematics and image manipulation theory. You have been warned;-)
You select the algorithm you want to use by selecting it from the algorithm selection drop down box (number 3 in the above picture). The algorithm specific settings (number 4 in the picture above) change accordingly immediately. You should consult to the Plugin specific help for information about the algorithm specific settings.
Setting the plugin specific settings
When you choose a particular plugin the plugin specific settings (number 4 in the picture above) change accordingly. These settings determine how the texture synthesis outcome will be. Check the Plugin specific help for more information.
Starting the synthetisation
Once you have set all the settings you start the texture synthesis by pressing the 'Go' button (number 5 in the picture above). The time needed for the synthesis depends on many things including the algorithm used, the source image and settings you have chosen. Once the synthesis is finished the synthesized image will appear to a new window. This window is similar to the source image window explained earlier. You can toggle the visibility of this window from the menu bar by selecting View→View synthesized image.
If the outcome is not to your satisfaction you can adjust the settings and press the 'Go' button again. The old synthesized image is lost at this point and the new synthesized image will appear to the synthesized image window once it's ready.
Saving the synthesized image
Once you have achieved an image that satisfies your needs you should save it to further use. You save your image by selecting File→Save synthesized image... from the menu bar. A file selection dialog will appear where you can select the location and file name to your image. Currently the images will be saved as JPEG so you should probably set the file name extension to .jpg or .jpeg.
Exiting JTexSynth
You can exit JTexSynth by selecting File→Quit from the menu bar. You can also press the closing button of the main window or use any other means to close an application that your operating system offers. Note that you won't be prompted when you exit. Remember to save your images before you exit! (This might change in the future versions of JTexSynth).
Plugin specific help
Wang Tile plugin
Introduction
The Wang Tile algorithm was introduced in 2003 on a paper by Michael F. Cohen, Jonathan Shade, Stefan Hiller and Oliver Deussen. The paper – called Wang Tiles for Image and Texture Generation – is available from the web. A short explanation to Wang Tiles in general (Wang Tiles can be used for other purposes than texture synthesis also) can be found for example from Wikipedia.
It isn't required to understand every detail about the algorithm in order to use it. This isn't however the most complicated algorithm out there so you don't have to be a rocket scientist to be able to read the paper. The settings for the Wang Tile plugin will be explained here in a way that assumes you have no knowledge at all about the algorithm.
There is one thing you should keep in mind when using Wang Tile plugin and thinking about the time it takes to complete. The time required for this algorithm is (almost) not dependent at all on the synthesized image size. This means you can synthesize an image of size 5000x5000 pixels in about the same time as you would synthesize a 100x100 pixel image.
Tile size
The Wang Tile algorithm constructs the images it synthesizes from small (or not so small, depends on this setting) tiles. These are square tiles that are laid one next to each other enough to fill a plane so big that it will cover the area you wanted (by setting the image width and height in the general settings). This setting sets the tile size in pixels. A good start for this setting might be half the size of the source image. So if your source image is 128x128 pixels set this to 64. You must never set this value larger than your source image. This value should also be even. It stays even if you only use the spinner buttons. (You are able to input odd values from the keyboard but please don't.)
Horizontal and vertical colors
Colors when talking about Wang Tiles are just an abstract concept in order to make the idea easier to understand. Your tiles have colored edges and the tiles are arranged in a way that adjacent tiles have edges of the same color. Since the tiles are square they have horizontal (east and west) and vertical (north and south) edges. These settings set the possible number of colors in each direction. The more colors you choose more complex your tiles and your synthesized image will be. This however comes with a price: the more colors you choose the more time it takes to complete the algorithm.
There isn't generally any reason for you to choose different values for horizontal and vertical coloring. You can try this however.
A good starting point for these settings is two which is the default. You shouldn't set these to one since that produces only one kind of tile and your texture will repeat itself badly. There is no upper bound for these settings but try not to go above about six or seven. The complexity of the calculation and the amount of memory consumption will rise quickly if you set too large values.
Tile quality
Note: the tile quality setting was removed from the Wang Tile plugin with the 0.3.0 release of JTexSynth. It was not considered a very useful feature.
You set the tile quality with a five level slider. This setting sets the amount of effort that is taken in order to produce good tiles.
Structural texture settings
Structural textures are images from brick walls, parquet floors and others that have a repeating pattern of some kind. An image of a grass mat is usually not a structural texture. When you have a structural source image you might want to enable the structural texture check box. This changes the tile generation procedure. Normally the tiles are chosen randomly anywhere from the source image. With the structural texture toggle enabled the size of the structure is considered when choosing the tiles from the source image.
You can set the size of the structure in your source image with inputting values to the structure horizontal and vertical size text fields.
Example: lets consider a sample image of a brick wall. There are five whole bricks visible in the uppermost row of bricks. There are a total of ten rows of bricks in the source image. The size of the source image is 100x100 pixels. One brick is about 20 pixels wide and about 10 pixels high. The width of the structure in this case is 20 (input this to the structure horizontal size text field) but the height is not 10 but 20 (input this to the structure vertical size text field) since bricks are usually laid on top of each other in a way that the seam between two bricks is in the middle of the one on top of them. We need to include two rows of bricks to the structure size. You should also pay attention to the tile size setting. It should be set to a multiple of the structure size. In this case good choices might include 40, 60 and 80. You should also start with a low tile quality setting since using the structural texture setting restricts the tile choosing algorithm considerably. (TODO: add sample images)