New python API for units handling.

Exposes all supported unit systems & types, and to_value()/to_string() functions.

Reviewed and enhanced by CampbellBarton, many thanks!

Differential Revision: https://developer.blender.org/D416

8 files changed, 445 insertions, 59 deletions

diff --git a/release/scripts/modules/bpy/utils.py b/release/scripts/modules/bpy/utils.py
index ce1efa43b3e..5621af29bc3 100644
--- a/release/scripts/modules/bpy/utils.py
+++ b/release/scripts/modules/bpy/utils.py
@@ -44,6 +44,7 @@ __all__ = (
     "script_paths",
     "smpte_from_frame",
     "smpte_from_seconds",
+    "units",
     "unregister_class",
     "unregister_module",
     "user_resource",
@@ -58,6 +59,7 @@ from _bpy import (
     )
 from _bpy import script_paths as _bpy_script_paths
 from _bpy import user_resource as _user_resource
+from _bpy import _utils_units as units
 
 import bpy as _bpy
 import os as _os
diff --git a/source/blender/python/generic/py_capi_utils.c b/source/blender/python/generic/py_capi_utils.c
index 54e27a30791..8454f5b5887 100644
--- a/source/blender/python/generic/py_capi_utils.c
+++ b/source/blender/python/generic/py_capi_utils.c
@@ -904,3 +904,73 @@ PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag)
 
 	return ret;
 }
+
+
+/**
+ * \return -1 on error, else 0
+ *
+ * \note it is caller's responsibility to acquire & release GIL!
+ */
+int PyC_RunString_AsNumber(const char *expr, double *value, const char *filename)
+{
+	PyObject *py_dict, *mod, *retval;
+	int error_ret = 0;
+	PyObject *main_mod = NULL;
+
+	PyC_MainModule_Backup(&main_mod);
+
+	py_dict = PyC_DefaultNameSpace(filename);
+
+	mod = PyImport_ImportModule("math");
+	if (mod) {
+		PyDict_Merge(py_dict, PyModule_GetDict(mod), 0); /* 0 - don't overwrite existing values */
+		Py_DECREF(mod);
+	}
+	else { /* highly unlikely but possibly */
+		PyErr_Print();
+		PyErr_Clear();
+	}
+
+	retval = PyRun_String(expr, Py_eval_input, py_dict, py_dict);
+
+	if (retval == NULL) {
+		error_ret = -1;
+	}
+	else {
+		double val;
+
+		if (PyTuple_Check(retval)) {
+			/* Users my have typed in 10km, 2m
+			 * add up all values */
+			int i;
+			val = 0.0;
+
+			for (i = 0; i < PyTuple_GET_SIZE(retval); i++) {
+				const double val_item = PyFloat_AsDouble(PyTuple_GET_ITEM(retval, i));
+				if (val_item == -1 && PyErr_Occurred()) {
+					val = -1;
+					break;
+				}
+				val += val_item;
+			}
+		}
+		else {
+			val = PyFloat_AsDouble(retval);
+		}
+		Py_DECREF(retval);
+
+		if (val == -1 && PyErr_Occurred()) {
+			error_ret = -1;
+		}
+		else if (!finite(val)) {
+			*value = 0.0;
+		}
+		else {
+			*value = val;
+		}
+	}
+
+	PyC_MainModule_Restore(main_mod);
+
+	return error_ret;
+}
diff --git a/source/blender/python/generic/py_capi_utils.h b/source/blender/python/generic/py_capi_utils.h
index 0afc4dd98d9..559a8e15678 100644
--- a/source/blender/python/generic/py_capi_utils.h
+++ b/source/blender/python/generic/py_capi_utils.h
@@ -73,4 +73,6 @@ int       PyC_FlagSet_ValueFromID(PyC_FlagSet *item, const char *identifier, int
 int       PyC_FlagSet_ToBitfield(PyC_FlagSet *items, PyObject *value, int *r_value, const char *error_prefix);
 PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag);
 
+int PyC_RunString_AsNumber(const char *expr, double *value, const char *filename);
+
 #endif  /* __PY_CAPI_UTILS_H__ */
diff --git a/source/blender/python/intern/CMakeLists.txt b/source/blender/python/intern/CMakeLists.txt
index 0605f408348..70b4df7d6fe 100644
--- a/source/blender/python/intern/CMakeLists.txt
+++ b/source/blender/python/intern/CMakeLists.txt
@@ -68,6 +68,7 @@ set(SRC
 	bpy_rna_callback.c
 	bpy_traceback.c
 	bpy_util.c
+	bpy_utils_units.c
 	stubs.c
 
 	gpu.h
@@ -91,6 +92,7 @@ set(SRC
 	bpy_rna_callback.h
 	bpy_traceback.h
 	bpy_util.h
+	bpy_utils_units.h
 	../BPY_extern.h
 )
 
diff --git a/source/blender/python/intern/bpy.c b/source/blender/python/intern/bpy.c
index 89104821cb0..5fd19d3ed88 100644
--- a/source/blender/python/intern/bpy.c
+++ b/source/blender/python/intern/bpy.c
@@ -49,6 +49,7 @@
 #include "bpy_props.h"
 #include "bpy_library.h"
 #include "bpy_operator.h"
+#include "bpy_utils_units.h"
 
 #include "MEM_guardedalloc.h"
 
@@ -334,6 +335,7 @@ void BPy_init_modules(void)
 	/* ops is now a python module that does the conversion from SOME_OT_foo -> some.foo */
 	PyModule_AddObject(mod, "ops", BPY_operator_module());
 	PyModule_AddObject(mod, "app", BPY_app_struct());
+	PyModule_AddObject(mod, "_utils_units", BPY_utils_units());
 
 	/* bpy context */
 	RNA_pointer_create(NULL, &RNA_Context, (void *)BPy_GetContext(), &ctx_ptr);
diff --git a/source/blender/python/intern/bpy_interface.c b/source/blender/python/intern/bpy_interface.c
index bf2de02625f..b7752b39900 100644
--- a/source/blender/python/intern/bpy_interface.c
+++ b/source/blender/python/intern/bpy_interface.c
@@ -566,15 +566,12 @@ void BPY_DECREF_RNA_INVALIDATE(void *pyob_ptr)
 	PyGILState_Release(gilstate);
 }
 
-
 /* return -1 on error, else 0 */
 int BPY_button_exec(bContext *C, const char *expr, double *value, const bool verbose)
 {
 	PyGILState_STATE gilstate;
-	PyObject *py_dict, *mod, *retval;
 	int error_ret = 0;
-	PyObject *main_mod = NULL;
-	
+
 	if (!value || !expr) return -1;
 
 	if (expr[0] == '\0') {
@@ -584,59 +581,8 @@ int BPY_button_exec(bContext *C, const char *expr, double *value, const bool ver
 
 	bpy_context_set(C, &gilstate);
 
-	PyC_MainModule_Backup(&main_mod);
-
-	py_dict = PyC_DefaultNameSpace("<blender button>");
-
-	mod = PyImport_ImportModule("math");
-	if (mod) {
-		PyDict_Merge(py_dict, PyModule_GetDict(mod), 0); /* 0 - don't overwrite existing values */
-		Py_DECREF(mod);
-	}
-	else { /* highly unlikely but possibly */
-		PyErr_Print();
-		PyErr_Clear();
-	}
-	
-	retval = PyRun_String(expr, Py_eval_input, py_dict, py_dict);
-	
-	if (retval == NULL) {
-		error_ret = -1;
-	}
-	else {
-		double val;
-
-		if (PyTuple_Check(retval)) {
-			/* Users my have typed in 10km, 2m
-			 * add up all values */
-			int i;
-			val = 0.0;
+	error_ret = PyC_RunString_AsNumber(expr, value, "<blender button>");
 
-			for (i = 0; i < PyTuple_GET_SIZE(retval); i++) {
-				const double val_item = PyFloat_AsDouble(PyTuple_GET_ITEM(retval, i));
-				if (val_item == -1 && PyErr_Occurred()) {
-					val = -1;
-					break;
-				}
-				val += val_item;
-			}
-		}
-		else {
-			val = PyFloat_AsDouble(retval);
-		}
-		Py_DECREF(retval);
-		
-		if (val == -1 && PyErr_Occurred()) {
-			error_ret = -1;
-		}
-		else if (!finite(val)) {
-			*value = 0.0;
-		}
-		else {
-			*value = val;
-		}
-	}
-	
 	if (error_ret) {
 		if (verbose) {
 			BPy_errors_to_report(CTX_wm_reports(C));
@@ -646,10 +592,8 @@ int BPY_button_exec(bContext *C, const char *expr, double *value, const bool ver
 		}
 	}
 
-	PyC_MainModule_Restore(main_mod);
-	
 	bpy_context_clear(C, &gilstate);
-	
+
 	return error_ret;
 }
 
diff --git a/source/blender/python/intern/bpy_utils_units.c b/source/blender/python/intern/bpy_utils_units.c
new file mode 100644
index 00000000000..cdbd57bcebe
--- /dev/null
+++ b/source/blender/python/intern/bpy_utils_units.c
@@ -0,0 +1,332 @@
+/*
+ * ***** BEGIN GPL LICENSE BLOCK *****
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Contributor(s): Bastien Montagne
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/python/intern/bpy_utils_units.c
+ *  \ingroup pythonintern
+ *
+ * This file defines a singleton py object accessed via 'bpy.utils.units',
+ * which exposes various data and functions useful in units handling.
+ */
+
+/* Future-proof, See https://docs.python.org/3/c-api/arg.html#strings-and-buffers */
+#define PY_SSIZE_T_CLEAN
+
+#include <Python.h>
+#include <structmember.h>
+
+#include "BLI_utildefines.h"
+#include "BLI_string.h"
+#include "BLI_ghash.h"
+
+#include "BPY_extern.h"
+#include "bpy_utils_units.h"
+
+#include "../generic/py_capi_utils.h"
+
+#include "BKE_unit.h"
+
+/***** C-defined systems and types *****/
+
+static PyTypeObject BPyUnitsSystemsType;
+static PyTypeObject BPyUnitsCategoriesType;
+
+/* XXX Maybe better as externs of BKE_unit.h ? */
+static const char *bpyunits_usystem_items[] = {
+	"NONE",
+	"METRIC",
+	"IMPERIAL",
+	NULL,
+};
+
+static const char *bpyunits_ucategorie_items[] = {
+	"NONE",
+	"LENGTH",
+	"AREA",
+	"VOLUME",
+	"MASS",
+	"ROTATION",
+	"TIME",
+	"VELOCITY",
+	"ACCELERATION",
+	"CAMERA",
+	NULL,
+};
+
+/**
+ * These fields are just empty placeholders, actual values get set in initializations functions.
+ * This allows us to avoid many handwriting, and above all, to keep all systems/categories definition stuff in
+ * ``BKE_unit.h``.
+ */
+static PyStructSequence_Field bpyunits_systems_fields[ARRAY_SIZE(bpyunits_usystem_items)];
+static PyStructSequence_Field bpyunits_categories_fields[ARRAY_SIZE(bpyunits_ucategorie_items)];
+
+static PyStructSequence_Desc bpyunits_systems_desc = {
+	(char *)"bpy.utils.units.systems",     /* name */
+	(char *)"This named tuple contains all pre-defined unit systems",    /* doc */
+	bpyunits_systems_fields,    /* fields */
+	ARRAY_SIZE(bpyunits_systems_fields) - 1
+};
+static PyStructSequence_Desc bpyunits_categories_desc = {
+	(char *)"bpy.utils.units.categories",     /* name */
+	(char *)"This named tuple contains all pre-defined unit names",    /* doc */
+	bpyunits_categories_fields,    /* fields */
+	ARRAY_SIZE(bpyunits_categories_fields) - 1
+};
+
+/**
+ * Simple utility function to initialize #PyStructSequence_Desc
+ */
+static PyObject *py_structseq_from_strings(
+        PyTypeObject *py_type,
+        PyStructSequence_Desc *py_sseq_desc,
+        const char **str_items)
+{
+	PyObject *py_struct_seq;
+	int pos = 0;
+
+	const char **str_iter;
+	PyStructSequence_Field *desc;
+
+	/* initialize array */
+	/* We really populate the contexts' fields here! */
+	for (str_iter = str_items, desc = py_sseq_desc->fields; *str_iter; str_iter++, desc++) {
+		desc->name = (char *)*str_iter;
+		desc->doc = NULL;
+	}
+	/* end sentinel */
+	desc->name = desc->doc = NULL;
+
+	PyStructSequence_InitType(py_type, py_sseq_desc);
+
+	/* initialize pytype */
+	py_struct_seq = PyStructSequence_New(py_type);
+	BLI_assert(py_struct_seq != NULL);
+
+	for (str_iter = str_items; *str_iter; str_iter++) {
+		PyStructSequence_SET_ITEM(py_struct_seq, pos++, PyUnicode_FromString((*str_iter)));
+	}
+
+	return py_struct_seq;
+}
+
+static bool bpyunits_validate(const char *usys_str, const char *ucat_str, int *r_usys, int *r_ucat)
+{
+	*r_usys = BLI_str_index_in_array(usys_str, bpyunits_usystem_items);
+	if (*r_usys < 0) {
+		PyErr_Format(PyExc_ValueError,
+		             "Unknown unit system specified: %.200s.",
+		             usys_str);
+		return false;
+	}
+
+	*r_ucat = BLI_str_index_in_array(ucat_str, bpyunits_ucategorie_items);
+	if (*r_ucat < 0) {
+		PyErr_Format(PyExc_ValueError,
+		             "Unknown unit category specified: %.200s.",
+		             ucat_str);
+		return false;
+	}
+
+	if (!bUnit_IsValid(*r_usys, *r_ucat)) {
+		PyErr_Format(PyExc_ValueError,
+		             "%.200s / %.200s unit system/category combination is not valid.",
+		             usys_str, ucat_str);
+		return false;
+	}
+
+	return true;
+}
+
+PyDoc_STRVAR(bpyunits_to_value_doc,
+".. method:: to_value(unit_system, unit_category, str_input, [str_ref_unit=None])\n"
+"\n"
+"   Convert a given input string into a float value.\n"
+"\n"
+"   :arg unit_system: The unit system, from :attr:`bpy.utils.units.systems`.\n"
+"   :type unit_system: string\n"
+"   :arg unit_category: The category of data we are converting (length, area, rotation, etc.), "
+"      from :attr:`bpy.utils.units.categories`.\n"
+"   :type unit_category: string\n"
+"   :arg str_input: The string to convert to a float value.\n"
+"   :type str_input: string\n"
+"   :arg str_ref_unit: A reference string from which to extract a default unit, if none is found in :arg:`str_input`.\n"
+"   :type str_ref_unit: string or None\n"
+"   :return: The converted/interpreted value.\n"
+"   :rtype: float\n"
+"   :raises ValueError: if conversion fails to generate a valid python float value.\n"
+);
+static PyObject *bpyunits_to_value(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
+{
+	static const char *kwlist[] = {"unit_system", "unit_category", "str_input", "str_ref_unit", NULL};
+
+	char *usys_str = NULL, *ucat_str = NULL, *inpt = NULL, *uref = NULL;
+	const float scale = 1.0f;
+
+	char *str;
+	Py_ssize_t str_len;
+	double result;
+	int usys, ucat;
+	PyObject *ret;
+
+	if (!PyArg_ParseTupleAndKeywords(args, kw, "sss#|z:bpy.utils.units.to_value", (char **)kwlist,
+	                                 &usys_str, &ucat_str, &inpt, &str_len, &uref))
+	{
+		return NULL;
+	}
+
+	if (!bpyunits_validate(usys_str, ucat_str, &usys, &ucat)) {
+		return NULL;
+	}
+
+	str_len = str_len * 2 + 64;
+	str = PyMem_MALLOC(sizeof(*str) * (size_t)str_len);
+	BLI_strncpy(str, inpt, (size_t)str_len);
+
+	bUnit_ReplaceString(str, (int)str_len, uref, scale, usys, ucat);
+
+	if (PyC_RunString_AsNumber(str, &result, "<bpy_units_api>") != 0) {
+		if (PyErr_Occurred()) {
+			PyErr_Print();
+			PyErr_Clear();
+		}
+
+		PyErr_Format(PyExc_ValueError,
+		             "'%.200s' (converted as '%s') could not be evaluated.",
+		             inpt, str);
+		ret = NULL;
+	}
+	else {
+		ret = PyFloat_FromDouble(result);
+	}
+
+	PyMem_FREE(str);
+	return ret;
+}
+
+PyDoc_STRVAR(bpyunits_to_string_doc,
+".. method:: to_string(unit_system, unit_category, value, [precision=3, [split_unit=False, [compatible_unit=False]]])\n"
+"\n"
+"   Convert a given input float value into a string with units.\n"
+"\n"
+"   :arg unit_system: The unit system, from :attr:`bpy.utils.units.systems`.\n"
+"   :type unit_system: string\n"
+"   :arg unit_category: The category of data we are converting (length, area, rotation, etc.), "
+"      from :attr:`bpy.utils.units.categories`.\n"
+"   :type unit_category: string\n"
+"   :arg value: The value to convert to a string.\n"
+"   :type value: float\n"
+"   :arg precision: Number of digits after the comma.\n"
+"   :type precision: int\n"
+"   :arg split_unit: Whether to use several units if needed (1m1cm), or always only one (1.01m).\n"
+"   :type split_unit: bool\n"
+"   :arg compatible_unit: Whether to use keyboard-friendly units (1m2) or nicer utf-8 ones (1m²).\n"
+"   :type compatible_unit: bool\n"
+"   :return: The converted string.\n"
+"   :rtype: str\n"
+"   :raises ValueError: if conversion fails to generate a valid python string.\n"
+);
+static PyObject *bpyunits_to_string(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
+{
+	static const char *kwlist[] = {"unit_system", "unit_category", "value",
+	                               "precision", "split_unit", "compatible_unit", NULL};
+
+	char *usys_str = NULL, *ucat_str = NULL;
+	double value = 0.0;
+	int precision = 3, split_unit = false, compatible_unit = false;
+
+	int usys, ucat;
+
+	if (!PyArg_ParseTupleAndKeywords(args, kw, "ssd|ipp:bpy.utils.units.to_string", (char **)kwlist,
+	                                 &usys_str, &ucat_str, &value, &precision, &split_unit, &compatible_unit))
+	{
+		return NULL;
+	}
+
+	if (!bpyunits_validate(usys_str, ucat_str, &usys, &ucat)) {
+		return NULL;
+	}
+
+	{
+		/* Maximum expected length of string result:
+		 * - number itself: precision + decimal dot + up to four 'above dot' digits.
+		 * - unit: up to ten chars (six currently, let's be conservative, also because we use some utf8 chars).
+		 * This can be repeated twice (e.g. 1m20cm), and we add ten more spare chars (spaces, trailing '\0'...).
+		 * So in practice, 64 should be more than enough.
+		 */
+		char buf1[64], buf2[64], *str;
+		PyObject *result;
+
+		bUnit_AsString(buf1, sizeof(buf1), value, precision, usys, ucat, (bool)split_unit, false);
+
+		if (compatible_unit) {
+			bUnit_ToUnitAltName(buf2, sizeof(buf2), buf1, usys, ucat);
+			str = buf2;
+		}
+		else {
+			str = buf1;
+		}
+
+		result = PyUnicode_FromString(str);
+
+		return result;
+	}
+}
+
+static PyMethodDef bpyunits_methods[] = {
+	{"to_value", (PyCFunction)bpyunits_to_value, METH_VARARGS | METH_KEYWORDS, bpyunits_to_value_doc},
+	{"to_string", (PyCFunction)bpyunits_to_string, METH_VARARGS | METH_KEYWORDS, bpyunits_to_string_doc},
+	{NULL, NULL, 0, NULL}
+};
+
+PyDoc_STRVAR(bpyunits_doc,
+"This module contains some data/methods regarding units handling."
+);
+
+static struct PyModuleDef bpyunits_module = {
+	PyModuleDef_HEAD_INIT,
+	"bpy.utils.units",
+	bpyunits_doc,
+	-1, /* multiple "initialization" just copies the module dict. */
+	bpyunits_methods,
+	NULL, NULL, NULL, NULL
+};
+
+PyObject *BPY_utils_units(void)
+{
+	PyObject *submodule, *item;
+
+	submodule = PyModule_Create(&bpyunits_module);
+	PyDict_SetItemString(PyImport_GetModuleDict(), bpyunits_module.m_name, submodule);
+	Py_INCREF(submodule);
+
+	/* Finalize our unit systems and types structseq definitions! */
+
+	/* bpy.utils.units.system */
+	item = py_structseq_from_strings(&BPyUnitsSystemsType, &bpyunits_systems_desc, bpyunits_usystem_items);
+	PyModule_AddObject(submodule, "systems", item);  /* steals ref */
+
+	/* bpy.utils.units.categories */
+	item = py_structseq_from_strings(&BPyUnitsCategoriesType, &bpyunits_categories_desc, bpyunits_ucategorie_items);
+	PyModule_AddObject(submodule, "categories", item);  /* steals ref */
+
+	return submodule;
+}
diff --git a/source/blender/python/intern/bpy_utils_units.h b/source/blender/python/intern/bpy_utils_units.h
new file mode 100644
index 00000000000..5f840a2304d
--- /dev/null
+++ b/source/blender/python/intern/bpy_utils_units.h
@@ -0,0 +1,32 @@
+/*
+ * ***** BEGIN GPL LICENSE BLOCK *****
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Contributor(s): Bastien Montagne
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/python/intern/bpy_utils_units.h
+ *  \ingroup pythonintern
+ */
+
+#ifndef __BPY_UTILS_UNITS_H__
+#define __BPY_UTILS_UNITS_H__
+
+PyObject *BPY_utils_units(void);
+
+#endif  /* __BPY_UTILS_UNITS_H__ */