README.md

UrsaMirror

A Python package and GUI for analyzing the Mirror Tracing Task in polar coordinates.

Table of Contents

• Highlights
• Usage
• Installation
• License
• How to cite

Highlights

• Analyze the residuals and density of the drawing for every angle.
• Save this values in a .csv file or work with them as a pandas DataFrame.
• Transform the digitized paper drawing into and easy-to-work format.
• Transform the results from this online version of the drawing task into and easy-to-work format.
• Reconstruct the drawn path when it crosses the borders of the star.

Usage

UrsaMirror performs all of its analysis using a standardized image format where the red, green and blue channels contain, respectively, the drawn path, the inner part of the star, and the borders of the star. You can simply transform any digitized image into this format using either paper2std() or online2std() functions. With the transformed image, the basic analysis in polar coordinates can be done in few lines of code.

There are several provided examples that you can use to test the package. They are located in the raw_data folder, and are divided into app, paper and online source. The app drawings come from an application developed in our group, whichs uses the standardize format as output. The paper folder contains digitized drawings. The online folder contains images from this online version of the task.

Paper to standard version

Using one of the provided digitized paper examples, we can transform it into the standardized version:

import ursamirror as um

path_to_image = "/raw_data/paper/blue.png"

transformed_image = um.paper2std(path_to_image)

You can now access and visualize each of the channels:

import matplotlib.pylab as plt

fig, ax = plt.subplots(1,4, sharex=True,sharey=True)

ax[0].imshow(transformed_image[:,:,0], cmap="Reds")
ax[0].set_title("Path", fontsize=15)
ax[0].axis('off')

ax[1].imshow(transformed_image[:,:,1], cmap="Greens")
ax[1].set_title("Inner star", fontsize=15)
ax[1].axis('off')

ax[2].imshow(transformed_image[:,:,2], cmap="Blues")
ax[2].set_title("Borders", fontsize=15)
ax[2].axis('off')

ax[3].imshow(transformed_image)
ax[3].set_title("Transformed image", fontsize=15)
ax[3].axis('off')

plt.show()

Or you can just save it in the new format to be analyzed.

import ursamirror as um

path_to_image = "/raw_data/paper/blue.png"
new_path = "/processed_data/transformed_blue.png"

transformed_image = um.paper2std(path_to_image, new_path, save=True)

If you want to process a group of images, it can be done in a for loop. Check this simple example

import ursamirror as um
import os 

path_to_folder = "/raw_data/paper/"
path_to_new_folder = "/processed_data/"

for file in os.listdir(path_to_folder):
    if ".png" in file:
        image_name = file
        #In Windows, change "/" by "\"
        path_to_image = path_to_folder + "/" + image_name

        new_name = "transformed_" + image_name
        new_path = "/processed_data/" + "/" + new_name

        transformed_image = um.paper2std(path_to_image, new_path, save=True)

Online to standard version

The procedure is the same as the above. The only change here is the function to be used:

import ursamirror as um

path_to_image = "/raw_data/online/00_online.png"

transformed_image = um.online2std(path_to_image)

#or saving the image
new_path = "/processed_data/transformed_00_online.png"
transformed_image = um.online2std(path_to_image, new_path, save=True)

Star analysis

Once you have a star in the standardized format, the basic analysis and export can be done as:

import ursamirror as um

path_to_image = "/processed_data/transformed_blue.png"

star = um.STAR(path_to_image)
export_data = star.export()
export_data.to_csv("/processed_data/transformed_blue.csv", index=False)

"transformed_blue.csv" will now contain 5 columns: The angles (in radians), the angles (in degrees), the density, the residuals, and the squared residuals.

You can also pre-visualize the results

star = um.STAR(path_to_image)
star.plot()

There are some other methods and attributes connected to the STAR object. The basic usage of the package are summarized above, but you can also get:

• Access to the path, inner star, and border, as from the standardized format.
• The skeleton of the path
• The inner/outer borders and their fitted coefficients.
• The center coordinates of the star in the image
• The estimated path thickness of the star.
• The drawn path and its skeleton in polar coordinates
• The residuals
• The density

Installation

pip install ursamirror

pip install ursamirror@git+https://github.com/PabloFGarrido/ursamirror

If you are not comfortable working with Python or programming, try the GUI that you can find in the exec folder.

Windows: Download ursamiror_windows and run it.

MacOS and Linux: Download ursamiror_linux and run it from the terminal. From the same directory where the file is located,

./ursamiror_linux

License

ursamirror is distributed under the terms of the MIT license.

How to cite