Speed up converter terrain merging with Cython

[heinezen]

Required skills: Cython, Python

Difficulty: Easy

The terrain textures in AoC and SWGB are stored as isometric* tiles (see #141 for an example). In the converter, we merge all these tiles together to get the cartesian projection of the texture (also used in the HD Edition: see #141 (comment)). The cartesian projection has many advantages, the main one being that the image size is halved and the generated texture file smaller.

An algorithm for terrain merging has already been implemented here using Cython. You main goal is to improve the speed of the conversion by reducing the Python overhead of the function and adjusting the algorithm. Cython will generates a file that shows the overhead of the source file in bin/openage/convert/processor/export/texture_merge.html when you build the project. We want the Python overhead of the merge function to be as small as possible.

For your conveniance,we have made a list of things that could be improved. You should probably have a look at the code first though.

• The image rotation in line 142 uses a numpy function that could be implemented directly in our code.
• Currently, the algorithm is split into two steps: First all terrain tiles are merged into one big tile, then this tile is projected to cartesian. The initial merging step requires an alpha blend. We can skip the initial merging step by projecting each tile to cartesian directly and directly placing it in the correct position in the final image. This would halve the number of required pixel copy operations.
• texture.frames in the Texture currently stores the terrain tiles as TextureImage objects. The tiles could be instead be stored as numpy arrays which can be accessed faster with Cython's memoryviews.

You can test your changes with the singlefile media converter.

Further reading:

• Terrain merging code
• Converter architecture
• Converter workflow

---

* Technically, the projection is a dimetric (or game isometric) projection. Keep that in mind, when you search the internet for it.

[zehuilu]

Hello, can I take this?

[TheJJ]

Sure, you can just submit an early pull request and get help in the chatroom :)

[ranbir7]

can i help with this?

[heinezen]

@ranbir7 Sure :)

Do you need some directions on where to start?

[ranbir7]

Yes please ..

[heinezen]

@ranbir7 Alright.

Old AoC versions store every terrain tile individually and already projected to how they look ingame (i.e. they have a diamond shape). What our converter does is

1. merging all these tiles together
2. "rotating" the diamond shape so that we get a flat rectangular texture

This is just for context. You don't really need to understand how it works since it's already implemented. What we interested in for this task is speed. For this purpose, it's important that the tiles merge code (written in Cython) gets
fast access to the individual tiles that it operates on.

The terrain tiles for the whole terrain are fetched from the files starts here:

openage/openage/convert/entity_object/export/texture.py

Lines 106 to 121 in 3506478

	if isinstance(input_data, (SLP, SMP, SMX)):
	input_frames = input_data.get_frames(layer)
	for frame in input_frames:
	# Palette can be different for every frame
	palette_number = frame.get_palette_number()
	if palette_number is None:
	main_palette = None
	else:
	main_palette = palettes[palette_number].array
	for subtex in self._to_subtextures(frame,
	main_palette,
	custom_cutter):
	self.frames.append(subtex)

_to_subtextures() is a method that creates a TextureImage object that references the pixel data for single tile in a numpy array and also some metadata like the hotspot (the latter is unimportant for terrains). All TextureObjects are put into a list; the self.frames member of the texture.

The frames are accessed by the tiles merge code starting here:

openage/openage/convert/processor/export/terrain_merge.pyx

Line 44 in 3506478

frames = texture.frames

Since we are accessing Python objects here, Cython cannot use it's full potential for speeding up some of the following calculations. Here, a more Cython-friendly solution would be nice. For example, instead of creating TextureImage objects for each tile, we could directly store the numpy arrays.

[ranbir7]

Okay this is something that's gonna take time for me to understand
But I'll let you know if I'll be able to do it
Just give some few good days
Alright?

[heinezen]

@ranbir7 Okay!

Feel free to ask more questions in our chatroom.

[ranbir7]

im getting stuck up alot in https://github.com/SFTtech/openage/tree/master/openage/convert/processor/export/terrain_merge.pyx
what shall I do here though? like I'll use numpy to do what?