Tiny ARM SLAM

This is an implementation of vSLAM built for the NXP i.MX93 chip
As of right now, this repository would only process a dataset and does not support live camera feed (yet)
A dataset simply contains png images that are named as "image" followed by the order/frame number (e.g. "image380.png") and a "calibration.json" file such as this

Usage

• tiny_arm_slam.hpp is the file to look for if using this as a library/dependency
• The current configuration is using process_folder_cli where the arguments received are "logs", "calibration", "imageroot", "logfile"
  An example is ./build/IMX -logs -calibration=path/to/calibration.json
  putting in the logs argument enables logs, leaving it out disables logs; the other arguments would process the values given with them
• There is another process_folder_manual in which these previously command-line arguments can be passed into this function itself
• The function definition of process_folder_cli is: process_folder_cli(int argc, char **argv)
• The function definition of process_folder_manual is: process_folder_manual(std::string imageroot, std::string calibration, std::string logfile, bool does_log)

Setup

Using Docker (Recommended)

The easiest way to build and run this project is using the pre-built Docker image from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/zhosein/vio-on-arm:latest

# Run the container
docker run -it ghcr.io/zhosein/vio-on-arm:latest

# Or build the image locally
docker build -t vio-on-arm .

Authentication for Private Access

If this repository or its Docker images are private, you'll need to authenticate. We provide multiple authentication methods similar to GitHub deploy keys:

Quick Start for Users

1. Using Personal Access Token (Simplest):

   # Login to GitHub Container Registry
   echo YOUR_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
   
   # Pull the image
   docker pull ghcr.io/zhosein/vio-on-arm:latest

2. Using GitHub App (Recommended for teams):

   • Get credentials from the repository owner (App ID, Installation ID, Private Key)
   • Generate a token using our helper script:

     ./scripts/generate-app-token.sh APP_ID INSTALLATION_ID private-key.pem

   • Use the generated token for authentication

For detailed setup instructions, see GitHub App Setup Guide

Manual Setup

• Firstly, the Operating System used to cross compile was Ubuntu 20 LTS and it is recommended
• Run build.sh on the x86 device that is doing the cross compiling (preferably a vm or a docker dedicated to just this purpose)
• Zip all of /root and all of /usr/local
• Unzip the zipped folders and place them in their respective locations
• run ./build/IMX from the /root dir for the cross compiled program to run

Deployment

Build and Execute on x86

• pass

Build and Execute on ARM (iMX93)

• pass

Tag Generation

genTags.sh generates each individual tag in a separate pdf. For each tag family the pdf's were merged and then the merged pdf's printed using a pdf printer to get the tags centred on letter sized pages. (See comment at top of genTags.sh for futher details).

Access Control Documentation

For detailed information about accessing this repository and its Docker images:

• Quick Start Guide - Step-by-step instructions for users and owners
• GitHub App Setup - Complete guide to setting up GitHub App authentication
• Authentication Flows - Visual diagrams of authentication methods
• Access Grant Template - Template for repository owners to grant access
• Troubleshooting - Common issues and solutions
• Scripts Documentation - Token generation helper scripts