Installation
Compiled binaries
Pre-compiled binaries are not up-to-date during alpha/beta-testing
When software is recently released, it is expected that users report bugs and that these get mended over time. This is
called (early) alpha-testing and (later) beta-testing. OccuPy is in alpha.
Compiled binaries will not be updated as new bugfixes get implemented. Once alpha/beta testing is over, new binaries
will be provided.
Using pip install, you can get bugfixes at any time, and update according to the latest changes. If you don't want
to wait for a new release of bug-fixes, install with pip from source, as described below).
The GUI will be distributed as precompiled binaries that you can download and use. Depending on your operating
system, you might need to "enable" it by adding permissions and assuring that it isn't a virus.
Detailed instructions for this can be found in
the troubleshooting section.
Occupy GUI version 0.1.9 (alpha).
Brief instructions to get going
- Download the binary installer.
- Double-click the installer, which should guide you thorugh the simple process of installing OccuPy on your system.
- In the start-menu, search for "occupy_gui". You should see the OccuPy Guppy.
- Download the executable program file.
- Open a terminal and navigate to the downloads directory.
- In the terminal, type
chmod a+x occupy_gui
. - In a file browser, go to the downloads directory and right-click the
occupy_gui
binary and select 'Open'. In the dialog that pops up, select 'Open again'. You can also type./occupy_gui
in the terminal
- Download the .deb file.
- Open a terminal and navigate to the downloads directory.
- In the terminal, type
sudo dpkg -i occupy_0.1.8.deb
- Update the list of installed software by typing
sudo update-desktop-database
in the terminal. - Open the launcher menu and type "occupy". You should see the OccuPy Guppy.
If you have issues using the pre-compiled binaries, please check the
troubleshooting section.
Previous versions of OccuPy are not available as binaries, but only though PIP and
github. The same goes for the command-line tool. Installation through PIP is
described below.
Using PIP
Regardless if you are using conda or not, OccuPy can be installed from the Python Package Index (PyPI) using pip
.
Stop. Get help.
If you run into issues, check the troubleshooting section.
Verify/install python and/or pip
The following contains elements of this guide to installing python on windows, and this guide to install pip using python.
- In the start-menu, type "Powershell". Open a powershell, which is a text-based interface to run system commands.
- Check if python is installed by running the command
python --version
in the powershell. If you see a version number, python is installed. If not, download and click the python3.10 installer for windows, which you can get thorugh this link. Follow the instructions on screen to install. - Close the powershell and reopen it once python is installed.
- Check if pip is installed by calling
py -m pip --version
in the powershell. If you see a version number, pip is installed, you can go to the next section to install OccuPy. If not, continue with step 5. - Download the file
get-pip.py
from pypa.io by saving it in the "Downloads" folder. - In the powershell, run the command "cd ~/Downloads". If you now run
ls *.py
you should see the file "get-pip.py" you just downloaded. - In the same powershell, run the downloaded file by running the command
py get-pip.py
and hit enter. This will install pip. - You may need to add pip to your environment variables, as described in the later section of this guide.
To install pip (a python package manager that can then install occupy), you can e.g. follow this guide, which also explains and verifies that pip is installed along with python.
Install OccuPy
- If you do not have one open, start a powershell as in step 1 of the previous section.
- In the powershell, run
py -m pip install occupy
. - Verify the install, run
py -m pip show occupy
.
You will either seeWARNING: Package(s) not found: occupy
or a description of the installation. If successfully installed, continue. - In the powershell, call
occupy_gui
. The occupy GUI should start.
If instead you get an error starting withoccupy_gui : The term 'occupy_gui' is not recognized...
then you need to add the pip package path to your environment variables.
To do so, runGet-ChildItem -Recurse -ErrorAction SilentlyContinue -Filter occupy_gui.exe -Force
in the powershell. This will find the Directory where occupy was installed. Copy it.
Add the location you copied to the "Path" as described in the section "Adding PIP To Windows Environment Variables" of this guide. - Note also that calling
occupy
in the powershell will invoke the non-GUI tool.
Calloccupy --help
for a list of input options.
It is recommended that you install occupy using a clean conda or other virtual environment, as this will avoid potential conflict with pre-existing packages and specifically their conflicint dependencies on pyqt.
- Open a terminal.
- In the terminal, call
pip install occupy[pyqt5]
. - Verify the install by calling
pip show occupy
. You will either seeWARNING: Package(s) not found: occupy
or a description of the installation. If successfully installed, continue. - In the terminal, call
occupy_gui
. If you get the errorcommand not found: occupy_gui
then you need to add the pip path to your environment variables, or restart the terminal. Otherwise, the occupy GUI should start. - Note also that calling
occupy
in the terminal will invoke the non-GUI tool. Calloccupy --help
for a list of input options.
- Open a terminal.
- In the terminal, call
pip install occupy
if your mac has an M1 chip. Otherwise you will likely need to instead need to callpip install occupy[pyqt5]
- Verify the install by calling
pip show occupy
. You will either seeWARNING: Package(s) not found: occupy
or a description of the installation. If successfully installed, continue. - In the terminal, call
occupy_gui
. If you get the errorcommand not found: occupy_gui
then you need to add the pip path to your environment variables, or restart the terminal. Otherwise, the occupy GUI should start. - Note also that calling
occupy
in the terminal will invoke the non-GUI tool. Calloccupy --help
for a list of input options.
Update, or downgrade easily
You can also easily install previous versions using pip:
pip install occupy==0.1.6
Make it easy to run without a terminal
In the start menu, type occupy_gui
. You should find occupy_gui as the type "Run command" suggested.
If this is not convenient enough:
- Right-click the occupy_gui run command and choose "open location".
- Right-click
occupy_gui.exe
and click "create shortcut". Move the shortcut to e.g. the desktop.
To create a launcher that makes it easy to start occupy, do the following. This is derived from this guide
- Open a new text file and give it the following content:
[Desktop Entry] Type=Application Terminal=false Exec=/path/to/executable Name=OccuPy
- Replace the
Exec
value with the path to occupy. To find it, open a terminal and callwhich occupy_gui
. - Save the file as
occupy.desktop
in/usr/share/applications/
. This may require root access.
Install from source
If you are a developer or prefer to download the source code for some other reason, you can also install from the cloned repo
git clone https://github.com/bforsbe/OccuPy.git
cd occupy
pip install -e .
Usage
The GUI
Occupy has a GUI that is recommended to use, because it makes the processing steps more intuitive, presents the options plainly, and offer easy ways to check your input and processing results for consistency.
To start the GUI from the command-line (terminal) and it is in your path (e.g. if you used pip install), simply call
$ occupy_gui
If it is not in your path, simply specify its location, or add it to your path.
If you downloaded a binary, simply double-click it.
The command-line tool
OccuPy is also a command-line tool, so that you can easily script its use if needed for bulk processing. This is only available by installing using PIP, or from source code.
We recommend getting acquainted with OccuPy through the GUI, which also has an option to print the command it will run, which can then be called on the command-line.
$ occupy --version
OccuPy: 0.1.5rc4.dev1+gfa0f2e9.d20220905
Developer use
Dev tools
These are instructions to install the developer tools used to build documentation, build binaries, etc. This is not needed to use occupy.
- clone the repo
git clone https://github.com/bforsbe/OccuPy.git
- make a clean virtual environment
mkdir occupy/occupy_venv python3 -m venv ocucpy/occupy_venv source ocucpy/occupy_venv/bin/activate
-
pip install occupy, deps and dev-deps in the virtual environment
pip install -e occupy/".[dev]"
-
build binary
cd occupy pyinstaller --onefile --windowed occupy_lib/occupy_gui.py ls dist
-
build docs and start a local serve to view them (interactive with changes)
mkdocs serve
The python module
For development use, you can also import it as a python module, but this currently and unsupported feature that we will not prioritize as main functionality.
In [1]: import occupy_lib
In [2]: from occupy_lib.map_tools import create_radial_mask
In [3]: create_radial_mask?
Signature:
create_radial_mask(
size: int,
dim: int,
center: int = None,
radius: float = None,
)
Docstring:
Create a circular or spherical dimensional mask or kernel
:param size: Output array length
:param dim: Output array dimension
:param center: Center of the radial region
:param radius: Radius of the radial region
:return: Boolean array
File: ~/Documents/Occ/occupy/occupy_lib/map_tools.py
Type: function