TAMV

Overview

a full real-time run of TAMV for 4 tools on a Jubilee

TAMV GUI has finally arrived. Check out it over on GitHub!

In order to achieve the highest possible precision when using multiple tools, Danal Estes graciously created the Tool Alignment with Machine Vision (TAMV) and Z Tool Align with Touch Plate (ZTATP) programs that allow us to correctly determine both XY and Z offsets for multiple independent tools on a toolchanger platform. For the Jubilee community, an updated version is maintained with slight enhancements as the current version referenced in this wiki, and you can always access the original release by Danal here.

• TAMV = Tool Alignment with Machine Vision
  

TAMV is a fully automated process that uses a camera to calculate XY tool offsets set with G10 L1 tool offsets that go in config.g to correctly set the XY alignment for correct tool-to-tool behavior when printing.

• ZTATP = Z Tool Align with Touch Plate
  

ZTATP is a partially automated process that uses a touch plate to calculate Z tool offsets also set with G10 L1 tool offsets that go in config.g to correctly set the Z alignment for tool-to-tool correct behavior when printing. It also sets the bed-to-tool-zero spacing!

For information on ZTATP, check out the Jubilee ZTATP Wiki Page.

• Download the latest Jubilee TAMV files on GitHub.

Special note to AVOID MACHINE DAMAGE

TAMV will move your tools around in ways that may be different than day-to-day printing.

In particular, if your camera is anywhere beyond the Y coordinate of the parking stalls for other tools, collisions could occur. To ensure this does not happen, two things must be true:

• TAMV expects a tool change, as initiated by a T0 or T1 or so forth, will not cause a collision, no matter where the tool is when the tool change initiates.

It is entirely possible that your tool change macros do not ensure this today, particularly when a ‘current tool’ is beyond the Y line of the parking stalls at the moment a tool change is initiated.

• TAMV itself will always “manhattan move”, that is move in square blocks, and will move X (only!) first, then Y (only!) as required to get FROM wherever the tool is after a Tx, TO the camera.

If (big IF) your tool change macros end with the tool at a ‘safe Y’, then ‘Manhattan moves’ will always prevent collisions. In fact, this form of move is best practice within your tool change macros.

Please read this section for more information.

Requirements

• Raspberry Pi 3B or 4B, with USB attached camera (no Picam at this time).
• Almost any webcam with auto-exposure and the ability to focus within a few centimeters of the lens will work. Logitech C270 is one that is known to have a threaded lens and a case that can be removed and replaced with a printed case.
• A Duet printer, reachable from the Pi by network, running V2 or V3 firmware
• May run on Duet3+Pi; does NOT require that configuration, run on any Pi.

Useful Links for TAMV

1. Set up headless Raspberry Pi VNC
2. VNC Viewer for Windows (freeware)
3. PuTTY SSH client for Windows (freeware)

Installing TAMV

Windows installation steps

The installation steps and Windows scripts needed to run TAMV can be found on this GitHub repository The basic steps to install TAMV under Windows are:

1. Install Git for Windows
2. Install Miniforge
3. Open a Miniforge command shell (not your regular Windows command shell)
4. Switch to the folder/directory where you want TAMV installed
5. Copy the installation scripts from the Windows folder in the GitHub source into this folder.
6. Run the installation script installTAMV.bat (this will create a folder called "logs" with each step's log files stored to review, if needed)
7. Run TAMV using the script startTAMV.bat
8. (OPTIONAL) to delete the TAMV python environment and files, run the deleteTAMV.bat script file

Docker-based installation steps

You can now run TAMV from a docker image directly, and skip the complex and time-consuming process of installing openCV on your hardware. This is available for Raspbian, MacOS, and Linux hardware. Unfortunately, Windows does not support USB device pass-through to docker, which is needed to talk to the camera for TAMV's operation.

Docker on Windows

This environment combination is unfortunately not supported at this point in time, since Docker under Windows does not allow for USB pass-through of the USB camera required to run TAMV.

You may alternatively run TAMV natively under windows, see installation steps above.

Docker on Linux (DOCS IN PROGRESS)

THIS SECTION IS CURRENTLY UNDER REVIEW. USE AT YOUR OWN RISK.

1. Connect using a VNC session to your machine - you MUST use a graphical interface for running TAMV.
2. Save the following script as your install file (installTAMV.sh) in your user's directory

#!/bin/bash
sudo apt update
sudo apt install apt-transport-https curl gnupg-agent ca-certificates software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
sudo apt install docker-ce docker-ce-cli containerd.io -y
sudo usermod -aG docker $USER
newgrp docker
cd
git clone https://github.com/HaythamB/TAMV
docker pull haythamb/tamv

1. Open a terminal window, and make sure you're in your home folder by typing cd then ENTER.
2. Run the command chmod a+x ./installTAMV.sh to change the install script into an executable file.
3. Type

   ./installTAMV.sh

   and press ENTER. This should install docker and pull the TAMV image from DockerHub

Legacy (old) Installation steps for TAMV

In case you're looking for the older installation instructions for TAMV on a Raspberry Pi, please head to this page to view them.

Troubleshooting a TAMV installation

Failed to connect to printer

1. Make sure you're using an IP address (preferred connection method) or a valid local network name.
2. Make sure your machine's axes have all been homed. TAMV will disconnect from the machine if this isn't valid.
3. In TAMV/config/settings.json, make sure the printer key entry contains a "default":1 key pair. If not, then please add it using standard JSON notation.
4. In TAMV/config/settings.json, make sure the printer key entry contains a "nickname": "printer nickname" key pair. If not, then please add it using standard JSON notation.

Failed to detect nozzle

1. If you are having issues getting the program to find the nozzle, you may need to adjust the lighting or focus of the camera.
2. Additionally, you need to make sure that the nozzle is clear of any filament. You can heat up the extruder before you start the TAMV script and do a slight retraction (~E-5) or brush material away if needed too.
3. If you're using nozzles with an opening of 0.6mm or larger, TAMV may have difficulty detecting them. There's a feature coming soon that will you to tell TAMV which tools have large nozzles and will adjust detection automatically as needed.
4. If TAMV consistently fails to detect your tools, try starting your calibration runs with the microscope slightly further away from the tool, which will blur the nozzle slightly. This sometimes helps in detection.

USB microscope common problems

1. If you're facing intermittent disconnects of the microscope while running TAMV, try running the microscope by connecting it through a powered USB hub. The current draw for the LED ring on the microscope sometimes overwhelms Raspberry Pi USB bus drivers, and causes it to error out. In this scenario, you cannot access the USB microscope again until you reboot the Pi.
2. In your settings.json file, located in the TAMV/config folder, see if the value for the key "video_src" is set to 0 or 1. Default for first connected USB camera should be 0 under Windows and Linux.
3. Also in settings.json, make sure the camera key entry contains a "default":1 key pair. If not, then please add it using standard JSON notation.

Python exceptions while running TAMV

Segmentation faults

Generally these are caused by the Python multiprocessing libraries, and are extremely difficult to troubleshoot. This is a known issue on macOS (especially M1 chips), and are difficult to troubleshoot.

You are strongly recommended to try another install environment to run TAMV, such as an Ubuntu or Windows desktop environment.

CRITICAL : 'tuple' object does not support item assignment

Generally speaking, all of these critical errors are caused by using an incompatible version of OpenCV under Python.

Make sure you have Python 3.8.6+ installed, along with OpenCV 4.2.0 (not any newer version, these are causing crashes).