Mahalle Boyamaca User Guide

MinibüslerMahalle Boyamaca is a single page, html/js application that lets the user to generate thematic maps. The final output is a bunch of image files colored thematically.

Generating Shapes


The canvas of the top left corner of the screen is where the user can draw the shapes (geometries). Drawing a shape consists of specifying the points on the border of the shape. It is possible to drag and drop a base image from the file system (any image file format, i.e.; jpg, png, bmp etc) to this canvas. What is being displayed on this canvas can be panned and zoomed in/out with mouse. Left clicking and dragging the mouse  on the canvas is how a user can pan. For zooming, mouse wheel can be used.

Left clicks with the mouse on the canvas without dragging is the way to put new points for a shape. No shape is being displayed unless the initial two points of the shape is specified. In order to finalize the drawing of a shape the user need to press the ‘C’ key on the keyboard. This action pops up the dialog for naming the shape.

A named shape is listed on the right side of the panel that contains the canvas. With this list, the user can edit or delete a shape. Pressing the delete button on an item in the list pops up the confirmation dialog for the deletion. Pressing the edit button on an item in the list does two things:

  1. The item is removed from the list.
  2. The shape is turned back into edit mode. The user can add more points to the shape, can remove present points and has the chance to change the name of it.

Whenever there is a need to delete the last point specified for a shape when in edit mode, the user can press the ‘Esc’ key on the keyboard. This action removes the last point added for the shape being drawn. Currently, this  is the only way to edit a geometry. There is no keyboard interaction other than ‘C’ and ‘Esc’ keys.

When making thematic maps, there usually is a need to draw shapes next to each other, sharing edge(s). Mahalle Boyamaca displays the shapes drawn with little circles on the points clicked to define the border of a shape. When drawing a second shape that is needed to be drawn adjacent to the first one, simply clicking close to the circles that defines the border to be shared is required. Mahalle Boyamaca automatically snaps these clicks to the circles if they are close enough. By zooming in to the location of the circles that defines the edges to be shared, the user can make sure if the click was snapped to the circle.

Providing Thematic Values For Shapes

Determining the shape of an item is one aspect of generating thematic maps. In order for a map to be thematic, there is a need to attribute each such shape with a value. Mahalle Boyamaca expects an excel file (an xls file to be more specific, there is no xlsx support currently) for such values.

The second box next to where the drawing is made is a droppable place, where the user is expected to drag and drop an excel file containing the thematic values of the shapes.

The format of the excel file is;excelFormat

With a single excel file, values for more than one image can be given. Each line (row) of the excel file corresponds to an output image.

There are a couple of things to notice for this format;

  1. Only one and the first worksheet is used.
  2. The content of the sheet MUST begin at the first row (1) and at the first column (A). Only the first cell (A1) must be empty.
  3. The names given to shapes must be at the first row starting with column B. It is CASE SENSITIVE. So the exact name given to the shape must be used in the excel file.

With shapes drawn and an excel file containing the thematic values for the shapes is provided, it is possible to generate images. But most of the time the desired result can not be achieved without some settings.


All the settings about Mahalle Boyamaca is under the collapsable panel named ‘Settings’. It is physically divided into two parts:

Thematic Settings


This part of the settings is where the user determines

  • the colors to be used,
  • the label for the color boxes that are going to be displayed below each image produced
  • and the thematic interval for each such thematic color.

colorChangingThe first two settings are trivial. By clicking on the colored boxes, the user accesses a color palette where he/she can choose another color. The associated text can be changed directly.

The third part is, determining the thematic intervals. The values to be used here changes from business to business. A user can enter intervals such as, 0-20.00, 20.01 – 40.00, 40.01 – 60.00, 60.01 – 80.00, 80.01 – 100.00. The thematic values given in the excel file should lie in one of the given interval otherwise the associated shape would not be drawn. By default the step of the controls for these values is set to 0.1 . But values with more significant digits can be entered as well. The important thing to take into account is that the intervals should not overlap, even by a single value. For example, 0-20, 20-40. For this instance, for a thematic value of 20, either of the colors can be used.

Image Settings

relativeSizeThe first part of image settings is where the user sets the relative extra width and height of the image.

To study these variables in an example, lets say that the total width and height of the shapes drawn be 327 px and 225 px respectively. With the first part of the image setting have values %20, %50, %95 and %80 as given in the image above, the total width and height of the images would be 801 px and 450 px. There would be  0.50 * 327 = 163 empty pixels on the left, 0.95 * 327 = 311 empty pixels on the right, 0.20 * 225 = 45 empty pixels on the top and 0.80 * 225 = 180 empty pixels on the bottom of the image. The shapes would be drawn between these regions. A sample output image is displayed below with the values studied above.



Another part of the image settings is the table where the user can enter values for parameters for label alignment. The labels considered here are the numbers displayed on the shapes. Especially for shapes that are concave, the labels sometimes are placed out of the boundaries of the shape.


With parameters for label alignment, the user is able to change the location of the labels. There are three number boxes for each item added to the table of parameters for label alignment. The first one is the identifying number of the shape. The other two are the displacement amounts of the location of the label. The X parameter is used to displace the label to the right or to the left and the Y parameter is used to displace the label to the top or to the bottom.

For example, with values [1, -85, 800] entered for the [No, X, Y] fields, the output image changes into the one below:concaveShapesDisplaced

For each such shape where its label need to be relocated, an entry to the parameters for label alignment table should be added and set.

Legend Settings

By default Mahalle Boyamaca enumerates the shapes drawn and displays them with labels enumerated starting with 1. It also displays a legend on the top right side of the image listed vertically that contains the name and the themaic numeric value of the shapes. The first three parameters of the Legend Settings is for this part of the image. The first two is to relocate the list. The values denotes the pixel values of the top left corner of the list. The default values are (-100,100). The origin of these parameters is the top right corner of the image. So, in order to display this list, the X parameter must always be lower than zero (since both Turkish and English are written from left to right). If a user would like not to display this legend, giving positivie value for the X parameter suffices. The third parameter is used to determine the font size of this list.

Similar to the previous list, the color legend is displayed at the bottom of the image. It is displayed as small color boxes and labels attributing them. Setting the colors to be used and the associated texts are discussed in Thematic Settings section. The first three parameters for color legend are exacly same as the three parameters of the previous list. The only difference being the origin of the displacement is the lower left corner of the image this time. Thus the Y value must be lower than zero in order the color legend to be drawn. If a user would like not to display the color legend, giving positive value for the Y parameter suffices. The third one is used to determine the font size of the associated text’s font.

The forth Color Box Size parameter is used to determine the size of the color boxes to be drawn. Each box is a square so providing a single numeric value suffices.

The fifth Extra Space Around Boxes parameter is used to put extra spaces around the color boxes and their associated texts. It enables to display them more discreetly.

Although listed under the Legend Settings, the last two parameters are irrevelant of the legends.

The Label Font Size parameter is used to determine the font size of the labels displayed on the shapes.

Scale Factor Parameter

The last parameter, Scale Factor is a different kind of parameter.

Without this parameters, the shapes are always drawn as big as they are generated. When the base image used has a high resolution, the output images becomes big as well. Similary, having very small shapes yields images with irelevantly large legends.

With Scale Factor parameter, the user can enlarge or diminish the size of the shapes to be drawn. With the default value of 1, the shapes would be drawn as big as they were generated. With a Scale Factor of 2, they would be drawn twice as big as they are. With a Scale Factor of 0.25, they would be drawn quarter the size they are.


Notice: Any changes to either thematic or image settings can be effective if and only if Save Settings button is pressed after doing the necessary changes.

Previewing and Downlading the Results

The Preview button is below the area where the excel file is dropped. When clicked, if the necessary data is provided (the excel file and at least one shape) a pop-up window appears where the first resulting image to be downloaded is displayed. This is the only way to see the effects of the changes made in the settings area. There is a Save button at the footer of the Preview Popup  Dialog. When the final form of the images to be generated is reached, clicking this button initiates the downloads of all the resulting images.

Save / Load

Mahalle Boyamaca is an html/js application that has no server-side at all. All code runs on the client browser and any data produced is again in client side. If the application page is refreshed or closed, the data produced and the setting determined are lost. It may be the case that a project in Mahalle Boyamaca would not be finished in one go. The Save / Load panel exists to overcome such problems.

The Save / Load panel at the bottom of the secreen has nothing to do with downloading the final image files. It contains two button Save and Load. When Save button is clicked, the download of a file (setting.json) is initiated. This file contains all the information necessary to come to the state when the Save button is clicked. Clicking Load button, on the other hand, opens a dialog to select a file in the file system. Selecting a file downloaded by clicking the Save button is the way to get back to the state when the Save button is clicked.

Save / Load can be used to save the state of the project in order to continue later.It can also be used to share the project among different users. Sending the downloaded setting file and the excel file that contains thematic values to another party suffices. This information sharing can be carried out with e-mails or by other means. Mahalle Boyamaca has no feature to do that.

Leave a Reply

Your email address will not be published. Required fields are marked *