Marimapper uses your webcam to map addressable LEDs to 3D space!

Above example data folder can be found under docs/highbeam_example/

Caution

This tool does not support Python 3.12

Caution

Exposure control is not supported on mac

You can however adjust the exposure manually in third party tools or use the software that comes with your webcam

Step 0: Install

pip --version # Ensure that it is //not// python 3.12, see above
pip install pipx
pipx ensurepath
pipx install "git+https://github.com/themariday/marimapper"

If you have Python 3.12 installed, install 3.11 and add --python /path/to/python3.11 to the above pipx install command

PIPx not working? You can also download this repo and run pip install . from inside it!

You can run the scripts anywhere by just typing them into a console

Step 1: Test your camera

Tip

use --help for any MariMapper command to show a full list of additional arguments!

Some not even in this doc...

Run marimapper_check_camera to ensure your camera is compatible with MariMapper, or check the list below:

Working Cameras

• HP 4310 (settings may not revert)
• Logitech C920
• Dell Latitude 5521 built-in
• HP Envy x360 built-in
• If your camera works, please drop me a line, so I can add it to the list!

Test LED identification by turning down the lights and holding a torch or led up to the camera.

This should start with few warnings, no errors and produce a very dark image with a single crosshair on centered on your LED.

Wrong webcam? MariMapper tools use --device 0 by default, use --device 1 to switch to your second webcam.

Tip

If your camera doesn't support exposure adjustment, or the image is still too bright, try dimming the lights and playing around with:

• --exposure - The lower the darker, defaults to -10, my webcam only goes down to -11
• --threshold - The lower the more detections, ranges between 0-255, defaults to 128

Step 2: Choose your backend

For the Marimapper to communicate with your leds, it requires a backend.

The following backends are built-in:

Fadecandy

To use the Fadecandy backend, please ensure that you are running the Fadecandy server A fork of the Fadecandy repo can be found here

Use --backend fadecandy --server 127.0.0.1:7890 to enable this backend, adjusting the server IP and port where needed

WLED

More info can be found here

FCMega

This is a custom driver I've written for the Teensy 4.1 to drive up to 9600 leds. Source code can be found here

PixelBlaze

Using Pixelblaze as a backend requires you to upload the marimapper.epe into the PixelBlaze editor and upload it as a new pattern.

--backend PixelBlaze --server 192.168.4.1 to enable this backend, adjusting the server IP where needed

Once you've completed your 3D map, upload it to pixelblaze using marimapper_upload_to_pixelblaze --help

If your LED backend isn't supported, you need to write your own. Open a new python file called my_backend.py and copy the below stub into it.

class Backend:

    def __init__(self):
        # connect to some device here!

    def get_led_count(self) -> int:
        # return the number of leds your system can control here

    def set_led(self, led_index: int, on: bool) -> None:
        # Write your code for controlling your LEDs here
        # It should turn on or off the LED at the led_index depending on the "on" variable
        # For example:
        # if on:
        #     some_led_library.set_led(led_index, (255, 255, 255))
        # else:
        #     some_led_library.set_led(led_index, (0, 0, 0))

If your backend needs any external libraries for example, requests, add them to marimapper with pipx inject marimapper requests

Fill out the blanks and check it by running marimapper_check_backend --backend my_backend.py

Step 3: It's time to thunderize!

In a new folder, run marimapper --backend fadecandy

and change fadecandy to whatever backend you're using and use --help to show more options

Set up your LEDs so most of them are in view and when you're ready, type y when prompted with Start scan? [y/n]

This will turn each LED on and off in turn, do not move the camera or leds during capture!

If you just want a 2D map, this is where you can stop!

Rotate your leds or move your webcam to a new position

Tip

As long as some of your leds are mostly in view, you can move your webcam to wherever you like! Try and get at least 3 views between 6° - 20° apart

Once you have a few views and the reconstructor succeeds, a new window will appear showing the reconstructed 3D positions of your LEDs.

If the window doesn't appear after 4 scans, then something has gone horribly wrong. Delete the scan .csv files in the current working directory and try again.

If it doesn't look quite right, add some more scans!

Here is an example reconstruction of a test tube of LEDs I have

How to move the model around

• Click and drag to rotate the model around.
• Hold shift to roll the camera
• Use the scroll wheel to zoom in / out
• Use the n key to hide / show normals
• Use the + / - keys to increase / decrease point sizes
• Use 1, 2 & 3 keys to change colour scheme

Not working?

Make sure you've read this readme all the way through and do give those error messages a good read too.

They should be able to tell you at least roughly what area is going wrong.

If you want a lot more reading material, run marimapper with -v to put it into verbose mode. This will tell you pretty much everything marimapper is doing under the hood. Also good if you're just curious as to why x is taking so long!

Feedback

I would really love to hear what you think and if you have any bugs or improvements, please raise them here or drop me a line on Telegram.

You can also raise issues on this repo's issues page

If you implement a backend that you think others might use, please raise a pull request or just drop me a message on Telegram!

Licensing

The licensing on this is GPLv3.

The TLDR is you can do anything you like with this as long as it's open source