Skip to content

Commit 1c3fa9f

Browse files
mmi-codingmmi-coding
committed
Initial commit
0 parents  commit 1c3fa9f

9 files changed

+720
-0
lines changed

‎.gitignore

+214
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig
2+
# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,python
3+
# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,linux,python
4+
5+
### Linux ###
6+
*~
7+
backup/
8+
# temporary files which can be created if a process still has a handle open of a deleted file
9+
.fuse_hidden*
10+
11+
# KDE directory preferences
12+
.directory
13+
14+
# Linux trash folder which might appear on any partition or disk
15+
.Trash-*
16+
17+
# .nfs files are created when an open file is removed but is still being accessed
18+
.nfs*
19+
20+
### Python ###
21+
# Byte-compiled / optimized / DLL files
22+
__pycache__/
23+
*.py[cod]
24+
*$py.class
25+
26+
# C extensions
27+
*.so
28+
29+
# Distribution / packaging
30+
.Python
31+
build/
32+
develop-eggs/
33+
dist/
34+
downloads/
35+
eggs/
36+
.eggs/
37+
lib/
38+
lib64/
39+
parts/
40+
sdist/
41+
var/
42+
wheels/
43+
share/python-wheels/
44+
*.egg-info/
45+
.installed.cfg
46+
*.egg
47+
MANIFEST
48+
49+
# PyInstaller
50+
# Usually these files are written by a python script from a template
51+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
52+
*.manifest
53+
*.spec
54+
55+
# Installer logs
56+
pip-log.txt
57+
pip-delete-this-directory.txt
58+
59+
# Unit test / coverage reports
60+
htmlcov/
61+
.tox/
62+
.nox/
63+
.coverage
64+
.coverage.*
65+
.cache
66+
nosetests.xml
67+
coverage.xml
68+
*.cover
69+
*.py,cover
70+
.hypothesis/
71+
.pytest_cache/
72+
cover/
73+
74+
# Translations
75+
*.mo
76+
*.pot
77+
78+
# Django stuff:
79+
*.log
80+
local_settings.py
81+
db.sqlite3
82+
db.sqlite3-journal
83+
84+
# Flask stuff:
85+
instance/
86+
.webassets-cache
87+
88+
# Scrapy stuff:
89+
.scrapy
90+
91+
# Sphinx documentation
92+
docs/_build/
93+
94+
# PyBuilder
95+
.pybuilder/
96+
target/
97+
98+
# Jupyter Notebook
99+
.ipynb_checkpoints
100+
101+
# IPython
102+
profile_default/
103+
ipython_config.py
104+
105+
# pyenv
106+
# For a library or package, you might want to ignore these files since the code is
107+
# intended to run in multiple environments; otherwise, check them in:
108+
# .python-version
109+
110+
# pipenv
111+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
112+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
113+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
114+
# install all needed dependencies.
115+
#Pipfile.lock
116+
117+
# poetry
118+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
119+
# This is especially recommended for binary packages to ensure reproducibility, and is more
120+
# commonly ignored for libraries.
121+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
122+
#poetry.lock
123+
124+
# pdm
125+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
126+
#pdm.lock
127+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
128+
# in version control.
129+
# https://pdm.fming.dev/#use-with-ide
130+
.pdm.toml
131+
132+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
133+
__pypackages__/
134+
135+
# Celery stuff
136+
celerybeat-schedule
137+
celerybeat.pid
138+
139+
# SageMath parsed files
140+
*.sage.py
141+
142+
# Environments
143+
.env
144+
.venv
145+
env/
146+
venv/
147+
ENV/
148+
env.bak/
149+
venv.bak/
150+
151+
# Spyder project settings
152+
.spyderproject
153+
.spyproject
154+
155+
# Rope project settings
156+
.ropeproject
157+
158+
# mkdocs documentation
159+
/site
160+
161+
# mypy
162+
.mypy_cache/
163+
.dmypy.json
164+
dmypy.json
165+
166+
# Pyre type checker
167+
.pyre/
168+
169+
# pytype static type analyzer
170+
.pytype/
171+
172+
# Cython debug symbols
173+
cython_debug/
174+
175+
# PyCharm
176+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
177+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
178+
# and can be added to the global gitignore or merged into this file. For a more nuclear
179+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
180+
#.idea/
181+
182+
### Python Patch ###
183+
# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
184+
poetry.toml
185+
186+
# ruff
187+
.ruff_cache/
188+
189+
# LSP config files
190+
pyrightconfig.json
191+
192+
### VisualStudioCode ###
193+
.vscode/*
194+
!.vscode/settings.json
195+
!.vscode/tasks.json
196+
!.vscode/launch.json
197+
!.vscode/extensions.json
198+
!.vscode/*.code-snippets
199+
200+
# Local History for Visual Studio Code
201+
.history/
202+
203+
# Built Visual Studio Code Extensions
204+
*.vsix
205+
206+
### VisualStudioCode Patch ###
207+
# Ignore all local history of files
208+
.history
209+
.ionide
210+
211+
# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,python
212+
213+
# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
214+

‎README.md

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# SpaceMouse 3D Cube Controller
2+
3+
## Overview
4+
5+
This project is a 3D cube controller that allows users to manipulate a cube using a **3Dconnexion SpaceMouse**, a keyboard, or a regular mouse. The application is built using **PyQt5** for the GUI and **OpenGL** for rendering and the **PySpaceMouse** python library.
6+
7+
The project is modular, separating concerns into different files:
8+
9+
- `main.py`: Entry point of the application.
10+
- `control_panel.py`: Handles the user interface for controlling the cube.
11+
- `cube_widget.py`: Manages OpenGL rendering and cube transformations.
12+
- `keyboard_mouse_input.py`: Handles keyboard and mouse input.
13+
- `spacemouse_input.py`: Manages input from the SpaceMouse device.
14+
- `config.py`: Stores configuration settings such as keyboard layout.
15+
- `requirements.txt`: Lists required dependencies.
16+
17+
18+
---
19+
20+
## Features
21+
22+
✅ **3Dconnexion SpaceMouse Support** – Move and rotate the cube in 3D space.\
23+
✅ **Keyboard and Mouse Fallback** – If no SpaceMouse is connected, use the keyboard and mouse to control the cube.\
24+
✅ **Configurable Sensitivity** – Adjust translation and rotation speeds via UI.\
25+
✅ **Supports AZERTY & QWERTY Layouts** – Users can choose their preferred keyboard layout.\
26+
✅ **Modular Design** – Clean separation of rendering, input handling, and UI logic.
27+
28+
---
29+
30+
## Installation & Setup
31+
32+
### 1️⃣ **Clone the Repository**
33+
34+
```sh
35+
git clone https://github.com/mmi-coding/SpaceMouse-3D-Cube-Python-Controller.git
36+
cd SpaceMouse-3D-Cube
37+
```
38+
39+
### 2️⃣ **Set Up a Virtual Environment** (Recommended)
40+
41+
```sh
42+
python -m venv .venv # Create a virtual environment
43+
source .venv/bin/activate # On macOS/Linux
44+
# OR
45+
.venv\Scripts\activate # On Windows
46+
```
47+
48+
### 3️⃣ **Install Dependencies**
49+
50+
```sh
51+
pip install -r requirements.txt
52+
```
53+
54+
### 4️⃣ **Run the Application**
55+
56+
```sh
57+
python main.py
58+
```
59+
60+
---
61+
62+
## Controls
63+
64+
### **Using a SpaceMouse**
65+
66+
- Move the SpaceMouse to **translate** the cube.
67+
- Rotate the SpaceMouse to **rotate** the cube.
68+
- Press the **first button** on the SpaceMouse to **reset** the cube.
69+
70+
### **Using a Keyboard & Mouse** *(Fallback Mode)*
71+
72+
#### **Keyboard Controls**
73+
74+
| Action | AZERTY | QWERTY |
75+
| ------------- | ------ | ------ |
76+
| Move Forward | Z | W |
77+
| Move Backward | S | S |
78+
| Move Left | Q | A |
79+
| Move Right | D | D |
80+
| Move Up | A | Q |
81+
| Move Down | E | E |
82+
| Rotate Left | ← | ← |
83+
| Rotate Right | → | → |
84+
| Rotate Up | ↑ | ↑ |
85+
| Rotate Down | ↓ | ↓ |
86+
| Reset Cube | R | R |
87+
88+
#### **Mouse Controls**
89+
90+
- **Left-click + Drag** – Rotate the cube.
91+
- **Mouse Wheel** – Zoom in/out.
92+
93+
---
94+
95+
## Project Structure
96+
97+
```
98+
.
99+
├── config.py # Configuration file (keyboard layout, sensitivity)
100+
├── control_panel.py # UI controls and layout
101+
├── cube_widget.py # OpenGL rendering and cube transformations
102+
├── keyboard_mouse_input.py # Keyboard & mouse input handling
103+
├── main.py # Application entry point
104+
├── requirements.txt # Python dependencies
105+
├── spacemouse_input.py # SpaceMouse input handling
106+
```
107+
108+
---
109+
110+
## Troubleshooting
111+
112+
### **Error: No SpaceMouse Found**
113+
114+
If you see:
115+
116+
```sh
117+
⚠ Warning: No found any connected or supported devices.
118+
🔄 Running in fallback mode (keyboard/mouse input).
119+
```
120+
121+
Your SpaceMouse is not detected. Ensure:
122+
123+
- The device is connected properly.
124+
- Drivers are installed.
125+
- Try restarting the application.
126+
127+
### **Keyboard/Mouse Not Responding?**
128+
129+
- Ensure the application window has focus.
130+
- Check your keyboard layout in `config.py`.
131+
132+
---
133+
134+
135+
## License
136+
137+
MIT License © 2025 [mmi-coding](https://github.com/mmi-coding)
138+

‎config.py

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
DEFAULT_CONFIG = {
2+
"sensitivity": {"translation": 0.1, "rotation": 2},
3+
"axis_direction": {"tx": -1, "ty": 1, "tz": 1, "rx": 1, "ry": 1, "rz": -1},
4+
"threshold": 0.01,
5+
"axis_enabled": {"tx": True, "ty": True, "tz": True, "rx": True, "ry": True, "rz": True},
6+
"keyboard_layout": "AZERTY",
7+
}

0 commit comments

Comments
 (0)