From f94b87bbb89b2350be2f5b26c2afb2372fd9d99c Mon Sep 17 00:00:00 2001 From: Bastien Montagne Date: Tue, 17 Jun 2014 16:03:40 +0200 Subject: [PATCH] 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 --- release/scripts/modules/bpy/utils.py | 2 + source/blender/python/generic/py_capi_utils.c | 70 ++++ source/blender/python/generic/py_capi_utils.h | 2 + source/blender/python/intern/CMakeLists.txt | 2 + source/blender/python/intern/bpy.c | 2 + source/blender/python/intern/bpy_interface.c | 62 +--- .../blender/python/intern/bpy_utils_units.c | 332 ++++++++++++++++++ .../blender/python/intern/bpy_utils_units.h | 32 ++ 8 files changed, 445 insertions(+), 59 deletions(-) create mode 100644 source/blender/python/intern/bpy_utils_units.c create mode 100644 source/blender/python/intern/bpy_utils_units.h 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); + error_ret = PyC_RunString_AsNumber(expr, value, ""); - py_dict = PyC_DefaultNameSpace(""); - - 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; - } - } - 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 +#include + +#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, "") != 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__ */