Oxoria API Reference

7 modules · Complete method reference

Modules

cv_api.py — opencv_convert
std_cv_cmd.py — CvProcessAPI
std_menu_cmd.py — StdMenuCmd
canvas_api.py — CanvasAPI
app_api.py — AppAPI
resources_api.py — ResourcesAPI
search_api.py — SearchAPI

opencv_convert

cv_api.py

A decorator function that bridges PySide6 canvas items and OpenCV-compatible NumPy arrays. It automatically extracts the pixmap from each selected canvas item, converts it to an RGBA NumPy array, passes it to the decorated function as cv_img, and writes the processed result back to the canvas.

decorator @opencv_convert ▼

@opencv_convert def my_func(*args, cv_img: np.ndarray = None) -> np.ndarray: ...

Step	Description
1	Retrieves all selected items via `CanvasAPI().get_selected()`
2	Converts each item's `base_pixmap` to `QImage.Format_RGBA8888`
3	Casts the image data to a `np.ndarray` of shape `(H, W, 4)`
4	Injects it into the decorated function as the `cv_img` keyword argument
5	Converts the returned `np.ndarray` back to `QPixmap`
6	Writes the result back via `CanvasAPI().set_pixmap()`

The decorated function must accept cv_img: np.ndarray = None and must return a np.ndarray of shape (H, W, 4) in RGBA format. The decorator iterates over all selected items independently. No value is returned from the wrapper.

CvProcessAPI

std_cv_cmd.py

Provides a collection of OpenCV-based image processing operations applied to currently selected canvas items. All methods are decorated with @opencv_convert and @classmethod.

classmethod to_blackwhite ▼

cls.to_blackwhite(cv_img: np.ndarray = None) -> np.ndarray

Converts the selected image(s) to grayscale (black & white).

Argument	Description
cv_img	Injected automatically by `@opencv_convert`; do not pass manually

Returns
np.ndarray	RGBA image converted from grayscale

Uses cv2.COLOR_BGRA2GRAY then cv2.COLOR_GRAY2RGBA for round-trip conversion.

classmethod recover_color ▼

cls.recover_color(cv_img: np.ndarray = None) -> np.ndarray

Returns the image unchanged. Intended to restore a previously processed image to its original state.

Returns
np.ndarray	Original RGBA image as-is

This method is a pass-through; actual restoration depends on base_pixmap holding the original data.

classmethod denoise_img ▼

cls.denoise_img(cv_img: np.ndarray = None) -> np.ndarray

Applies colored non-local means denoising to the selected image(s).

Returns
np.ndarray	Denoised RGBA image

Uses cv2.fastNlMeansDenoisingColored with fixed parameters (h=10, hColor=10, templateWindowSize=7, searchWindowSize=21). These are not currently configurable.

classmethod custom_operation ▼

cls.custom_operation(cv2_cmd: str, cv_img: np.ndarray = None) -> np.ndarray

Executes an arbitrary OpenCV expression string and applies the result to the selected image(s).

Argument	Description
cv2_cmd	A Python expression string; has access to `cv2`, `np`, and `cv_img` in its execution context
cv_img	Injected automatically by `@opencv_convert`

Returns
np.ndarray	Result of the evaluated expression

⚠️ Security Warning: This method uses eval() to execute the expression. Only pass trusted, validated strings. Never expose this to untrusted user input, as it can execute arbitrary code.

StdMenuCmd

std_menu_cmd.py

Implements standard menu-bar commands (File menu operations, window management, etc.) for the Oxoria application. Relies on CanvasAPI, ResourcesAPI, and AppAPI internally.

__init__ ▼

__init__(self)

Initializes the command class and instantiates internal API objects.

save_as ▼

save_as(self) -> None

Opens a Save dialog and saves the current canvas to a new .oxoria file chosen by the user.

Requires UI_Var.MAIN_WINDOW to be set. The .oxoria suffix is enforced regardless of the user's input. Updates GBVar.OPENED_FILE.

save_file ▼

save_file(self) -> None

Saves the current canvas to the already-opened file. Falls back to save_as() if no file is currently open.

open_resource ▼

open_resource(self) -> None

Opens a file picker dialog and loads the chosen file onto the canvas as a resource.

Accepts all file types. Requires UI_Var.MAIN_WINDOW to be set.

new_canvas ▼

new_canvas(self) -> None

Saves the current file and then clears the canvas.

Calls save_file() before clearing, so unsaved work is preserved.

open_oxoria_file ▼

open_oxoria_file(self) -> None

Opens a .oxoria project file selected by the user. If a file is already open, new_canvas() is called first.

Requires UI_Var.MAIN_WINDOW to be set.

export_canvas ▼

export_canvas(self) -> None

Exports the current canvas as an .oxoarchive file (zip-based bundle) to a user-selected path.

Requires UI_Var.MAIN_WINDOW to be set. The .oxoarchive suffix is enforced.

new_window ▼

new_window(self) -> None

Opens a new application window.

quit_app ▼

quit_app(self) -> None

Saves the current file and then quits the application.

force_quit_app ▼

force_quit_app(self) -> None

Quits the application immediately without saving.

⚠️ Any unsaved changes will be lost.

test ▼

test(self) -> None

Prints a test message to stdout. Used for development/debugging.

CanvasAPI

canvas_api.py

Provides the primary interface for canvas state management, including saving/loading project files, managing items on the scene, and exporting/importing canvas archives.

make_oxoria_file ▼

make_oxoria_file(self) -> dict

Serializes the current canvas scene into a dictionary suitable for JSON export.

Returns
dict	Keys are item pointers; values contain `size_h`, `size_w`, `pos_x`, `pos_y`

Only ImageItem instances are included. Returns early if UI_Var.MAIN_CANVAS is None.

save_oxoria_file ▼

save_oxoria_file(self, saving_path: str) -> None

Serializes and saves the current canvas to a .oxoria JSON file.

Argument	Description
saving_path	Absolute or relative path to write the file

Updates GBVar.OPENED_FILE upon completion.

open_oxoria_file ▼

open_oxoria_file(self, opening_path: str | Path) -> None

Loads a .oxoria project file and restores all image items to the canvas.

Argument	Description
opening_path	Path to the `.oxoria` file

Silently returns if the path does not exist, is not .oxoria, or cannot be parsed. Only items whose pointers exist in the current resource profile are restored. Updates GBVar.OPENED_FILE.

open_resource_on_canvas ▼

open_resource_on_canvas(self, img_path: str | Path) -> None

Opens an image file and places it onto the canvas.

Argument	Description
img_path	Path to the image file

clear_canvas ▼

clear_canvas(self) -> None

Removes all items from the canvas scene and resets GBVar.OPENED_FILE.

⚠️ Destructive operation. Call save_file() before invoking if preservation is needed.

wrap_canvas ▼

wrap_canvas(self, archive_path: str | Path) -> None

Packages the current canvas and its associated image resources into an .oxoarchive file.

Argument	Description
archive_path	Destination path for the archive

Creates a temporary directory temp_export/ under GBVar.DATA_DIR, builds a zip archive, then renames it to .oxoarchive. The temp directory is removed after archiving. Only resources referenced by the current canvas are included.

delete_item ▼

delete_item(self, items_to_delete: list[ImageItem]) -> None

Removes a list of ImageItem instances from the canvas scene.

Argument	Description
items_to_delete	List of items to remove

get_selected ▼

get_selected(self) -> list[ImageItem]

Returns a list of currently selected items on the canvas.

Returns
list[ImageItem]	Currently selected scene items

group_selected ▼

group_selected(self) -> None

Groups all currently selected items into a single QGraphicsItemGroup.

is_anything_selected ▼

is_anything_selected(self) -> bool

Returns whether any item is currently selected on the canvas.

Returns
bool	`True` if at least one item is selected

set_to_origin ▼

set_to_origin(self) -> None

Resets the canvas view transform, centers on the origin, and applies a default zoom scale of 0.15.

set_pixmap ▼

set_pixmap(self, pixmap: QPixmap, image_item: ImageItem) -> None

Replaces the pixmap of an ImageItem on the canvas, updating both base_pixmap and the displayed scaled version.

Argument	Description
pixmap	New `QPixmap` to assign
image_item	The target canvas item

AppAPI

app_api.py

Handles application-level operations such as launching subprocesses and managing the application lifecycle.

run_capture_monitor ▼

run_capture_monitor(self) -> None

Launches the screen capture monitor as a background process, if not already running.

Checks running processes via psutil before launching to prevent duplicate instances. The monitor script path is resolved relative to the module's location.

open_new_window ▼

open_new_window(self) -> None

Opens a new Oxoria application window as an independent subprocess.

Resolves and launches __main__.py in the application root directory. Prints an error to stdout if the entry script is not found.

quit_app ▼

quit_app(self) -> None

Quits the main Qt application.

Calls GBVar.MAIN_APP.quit(). Does nothing if MAIN_APP is None.

get_command_stack ▼

get_command_stack(self, output_length: int = -1) -> list[str]

Retrieves a slice of the global command execution history stack.

Argument	Description
output_length	Number of commands to return from the end of the stack. Pass `-1` (default) to return the entire stack; pass a positive integer to return only the last N commands

Returns
list[str]	List of command strings; empty list if the command stack is empty or output_length is invalid

If output_length exceeds the actual stack size, the entire stack is returned. The stack is accessed via GBVar.COMMAND_STACK.

mycommand ▼

mycommand(self, cmd: str, shortcut_alphabet: str) -> None

Registers a custom shortcut by storing a command string mapped to a shortcut alphabet key.

Argument	Description
cmd	The command string to execute when the shortcut is triggered
shortcut_alphabet	A single character or key name to use as the shortcut trigger

Reads config/app_config.json, updates the "mycommand" section with the new shortcut mapping, and writes the updated config back to disk. Creates the "mycommand" dictionary if it does not exist.

get_mycommand ▼

get_mycommand(self, shortcut_alphabet: str) -> str

Retrieves the command string associated with a registered custom shortcut.

Argument	Description
shortcut_alphabet	The shortcut key to look up

Returns
str	The command string for the given shortcut; empty string `""` if the shortcut does not exist or the `"mycommand"` section is not found

Reads from config/app_config.json. Returns an empty string rather than raising an error if the shortcut is not found.

get_data_dir ▼

get_data_dir(self) -> str

Returns the absolute path to the application data directory.

Returns
str	Path to the data directory, typically containing `resources_lib/`, `profiles/`, and other application data

Reads from GBVar.DATA_DIR. This is a convenience accessor for the global data directory.

get_app_folder_dir ▼

get_app_folder_dir(self) -> str

Returns the absolute path to the parent directory of the data directory (the root application folder).

Returns
str	Path to the application root folder, one level above the data directory

Resolves the data directory, then returns its parent using Path.resolve().parent. Useful for locating configuration files and other app-level resources.

get_gbvar ▼

get_gbvar(self) -> GBVar

Returns a reference to the global GBVar class object.

Returns
GBVar	The `GBVar` class itself, providing access to all global application variables

This is a convenience accessor for obtaining the global variables class. Use this to access module-level config like MAIN_APP, COMMAND_STACK, DATA_DIR, etc.

ResourcesAPI

resources_api.py

Manages the local image resource library: importing, profiling, tagging, and searching image assets identified by perceptual hash pointers.

__init__ ▼

__init__(self, data_path: str | None = None)

Argument	Description
data_path	Override for the data directory; defaults to `GBVar.DATA_DIR`

On macOS (Darwin), sets OMP_NUM_THREADS=1 to avoid OpenMP conflicts.

clone_resource_to_repo ▼

clone_resource_to_repo(self, original_path: str, new_path: str) -> None

Copies an image file into the local resource library directory.

Argument	Description
original_path	Source file path
new_path	Destination filename (relative to `resources_lib/`)

Skips the copy if the destination already exists.

check_exists ▼

check_exists(self, img_hash: str | None, img_path: str | None, tolerance: float = 0) -> tuple[str | None, bool | None]

Checks whether an image (by hash or path) already exists in the resource library.

Argument	Description
img_hash	Precomputed hash; if `None`, computed from `img_path`
img_path	Image file path; used to compute hash if `img_hash` is `None`
tolerance	Similarity tolerance for fuzzy matching; `0` = exact match (default: `0`)

Returns
tuple	`(hash_value, exists_flag)`; both `None` if neither argument is provided

get_resources_profile ▼

get_resources_profile(self) -> dict

Returns the full resource profile dictionary from resources_profile.json.

Returns
dict	All resource entries; empty dict if the profile file does not exist

make_resource_profile ▼

make_resource_profile(self, img_path: str, name: str = None, memo: str = None, tags: list[str] = None, make_clone_path: bool = True) -> dict

Constructs a profile dictionary for a new resource (does not write to disk).

Argument	Description
img_path	Path to the image
name	Display name; defaults to the filename stem
memo	Free-text memo; defaults to `""`
tags	List of tag strings; defaults to `[]`
make_clone_path	If `True`, stores only the filename (not the full path) in the profile (default: `True`)

Returns
dict	Profile with keys `path`, `name`, `memo`, `tags`

write_resource_profile ▼

write_resource_profile(self, pointer: str, profile: dict, merge: bool = False) -> bool

Writes or updates a single resource entry in resources_profile.json.

Argument	Description
pointer	Unique hash identifier for the resource
profile	Profile data; must contain a `"path"` key
merge	If `True`, merges with the existing profile instead of replacing (default: `False`)

Returns
bool	`True` on success; `False` if `"path"` is missing from `profile`

import_resource ▼

import_resource(self, img_hash: str | None, img_path: str | None, profile: dict, skip_existencce_check: bool = True, tolerance: float = 0, make_clone: bool = True) -> bool

Imports an image into the resource library: adds its hash, writes its profile, and optionally copies the file.

Argument	Description
img_hash	Precomputed hash; computed from `img_path` if `None`
img_path	Source image path
profile	Resource profile dictionary
skip_existencce_check	If `True`, skips duplicate detection (default: `True`)
tolerance	Hash similarity tolerance for duplicate check (default: `0`)
make_clone	If `True`, copies the file into the repository (default: `True`)

Returns
bool	`True` on success; `False` if the resource already exists (when check is enabled) or if both hash and path are `None`

Note: The parameter name skip_existencce_check contains a typo (existencce). Use it as-is in your code.

pointer_to_path ▼

pointer_to_path(self, pointer: str) -> str | None

Resolves a resource pointer (hash) to its absolute file path.

Returns
str \| None	Absolute path string, or `None` if not found

path_to_pointer ▼

path_to_pointer(self, path: str) -> str | None

Finds the resource pointer associated with a stored relative path.

Returns
str \| None	Pointer string, or `None` if not found

name_to_path ▼

name_to_path(self, name: str) -> str | None

Looks up the relative path for a resource by its display name.

Returns
str \| None	Relative path string, or `None` if not found

filter_pointer_with_tag ▼

filter_pointer_with_tag(self, tag: str) -> list[str]

Returns all resource pointers that have the specified tag.

Returns
list[str]	List of matching pointer strings

filter_pointer_with_category ▼

filter_pointer_with_category(self, category: str) -> list[str]

Returns all resource pointers matching the specified category.

Returns
list[str]	List of matching pointer strings

filter_pointer_with_memo ▼

filter_pointer_with_memo(self, kw: str)

⚠️ Not implemented: Method body is pass. Not yet available.

edit_memo ▼

edit_memo(self, pointer: str, memo_text: str) -> None

Updates the memo field of a resource profile in place.

Argument	Description
pointer	Resource hash
memo_text	New memo content

edit_tags ▼

edit_tags(self, pointer: str, tags: list[str], mode: str = "append") -> None

Appends or removes tags from a resource's profile.

Argument	Description
pointer	Resource hash
tags	Tags to add or remove
mode	`"append"` adds new tags (deduplicates); `"remove"` removes specified tags (default: `"append"`)

Silently returns if pointer is not in the current profile or if mode is unrecognized.

SearchAPI

search_api.py

Provides both semantic (vector-based) and fuzzy string-based search over the resource library's keywords and names.

__init__ ▼

__init__(self)

Initializes UseVector, SearchBase, and FaissIndexBase internally.

append_search_base ▼

append_search_base(self, kw: str) -> None

Adds a keyword to the FAISS vector index and the in-memory search base.

Argument	Description
kw	Keyword string to index

semantic_search_kw ▼

semantic_search_kw(self, kw: str, return_num: int = 3) -> list[str]

Searches for the most semantically similar keywords to the query using the FAISS index.

Argument	Description
kw	Query keyword
return_num	Maximum number of results to return (default: `3`)

Returns
list[str]	List of matching keyword strings; may be shorter than `return_num` if the search base is small

Uses a distance cutoff of 0.65; results below this threshold are excluded.

semantic_search_kw_to_pointer ▼

semantic_search_kw_to_pointer(self, kw: str, return_num: int = 3) -> list[str]

Performs semantic search and maps the results back to resource pointers.

Argument	Description
kw	Query keyword
return_num	Number of results to return (default: `3`)

Returns
list[str \| None]	List of length `return_num`; positions without a matching pointer contain `None`

Matches are made by comparing search results against the "memo" field of each resource profile.

distance_search_kw ▼

distance_search_kw(self, kw: str, return_num: int = 3, cutoff: float = 0.5) -> list[str]

Searches for resources by fuzzy string matching on display names using difflib.

Argument	Description
kw	Query string
return_num	Maximum number of results (default: `3`)
cutoff	Minimum similarity score `[0.0, 1.0]`; results below this are discarded (default: `0.5`)

Returns
list[str]	List of resource pointer strings matching the name query

Note: The cutoff parameter is accepted in the signature, but the internal difflib.get_close_matches call hardcodes cutoff=0.5, so the passed value is ignored.