core: add utils::findDataFile() / samples::findFile()

modules/core/CMakeLists.txt

@@ -82,3 +82,47 @@ ocv_add_accuracy_tests()
 ocv_add_perf_tests()
 
 ocv_install_3rdparty_licenses(SoftFloat "${CMAKE_CURRENT_SOURCE_DIR}/3rdparty/SoftFloat/COPYING.txt")
+
+
+# generate data (samples data) config file
+set(OPENCV_DATA_CONFIG_FILE "${CMAKE_BINARY_DIR}/opencv_data_config.hpp")
+set(OPENCV_DATA_CONFIG_STR "")
+
+if(CMAKE_INSTALL_PREFIX)
+  set(OPENCV_DATA_CONFIG_STR "${OPENCV_DATA_CONFIG_STR}
+#define OPENCV_INSTALL_PREFIX \"${CMAKE_INSTALL_PREFIX}\"
+")
+endif()
+if(OPENCV_OTHER_INSTALL_PATH)
+  set(OPENCV_DATA_CONFIG_STR "${OPENCV_DATA_CONFIG_STR}
+#define OPENCV_DATA_INSTALL_PATH \"${OPENCV_OTHER_INSTALL_PATH}\"
+")
+endif()
+
+set(OPENCV_DATA_CONFIG_STR "${OPENCV_DATA_CONFIG_STR}
+#define OPENCV_BUILD_DIR \"${CMAKE_BINARY_DIR}\"
+")
+
+file(RELATIVE_PATH SOURCE_DIR_RELATIVE ${CMAKE_BINARY_DIR} ${CMAKE_SOURCE_DIR})
+set(OPENCV_DATA_CONFIG_STR "${OPENCV_DATA_CONFIG_STR}
+#define OPENCV_DATA_BUILD_DIR_SEARCH_PATHS \\
+    \"${SOURCE_DIR_RELATIVE}/\"
+")
+
+if(WIN32)
+  file(RELATIVE_PATH INSTALL_DATA_DIR_RELATIVE "${CMAKE_INSTALL_PREFIX}/${OPENCV_BIN_INSTALL_PATH}" "${CMAKE_INSTALL_PREFIX}/${OPENCV_OTHER_INSTALL_PATH}")
+else()
+  file(RELATIVE_PATH INSTALL_DATA_DIR_RELATIVE "${CMAKE_INSTALL_PREFIX}/${OPENCV_LIB_INSTALL_PATH}" "${CMAKE_INSTALL_PREFIX}/${OPENCV_OTHER_INSTALL_PATH}")
+endif()
+list(APPEND OPENCV_INSTALL_DATA_DIR_RELATIVE "${INSTALL_DATA_DIR_RELATIVE}")
+string(REPLACE ";" "\",\\\n    \"" OPENCV_INSTALL_DATA_DIR_RELATIVE_STR "\"${OPENCV_INSTALL_DATA_DIR_RELATIVE}\"")
+set(OPENCV_DATA_CONFIG_STR "${OPENCV_DATA_CONFIG_STR}
+#define OPENCV_INSTALL_DATA_DIR_RELATIVE ${OPENCV_INSTALL_DATA_DIR_RELATIVE_STR}
+")
+
+if(EXISTS "${OPENCV_DATA_CONFIG_FILE}")
+  file(READ "${OPENCV_DATA_CONFIG_FILE}" __content)
+endif()
+if(NOT OPENCV_DATA_CONFIG_STR STREQUAL "${__content}")
+  file(WRITE "${OPENCV_DATA_CONFIG_FILE}" "${OPENCV_DATA_CONFIG_STR}")
+endif()

modules/core/include/opencv2/core.hpp

@@ -75,6 +75,7 @@
         @defgroup core_utils_sse SSE utilities
         @defgroup core_utils_neon NEON utilities
         @defgroup core_utils_softfloat Softfloat support
+        @defgroup core_utils_samples Utility functions for OpenCV samples
     @}
     @defgroup core_opengl OpenGL interoperability
     @defgroup core_ipp Intel IPP Asynchronous C/C++ Converters

modules/core/include/opencv2/core/private.hpp

@@ -801,6 +801,82 @@ CV_EXPORTS InstrNode*   getCurrentNode();
 #define CV_INSTRUMENT_REGION(); CV_INSTRUMENT_REGION_();
 #endif
 
+namespace cv {
+
+namespace utils {
+
+//! @addtogroup core_utils
+//! @{
+
+/** @brief Try to find requested data file
+
+Search directories:
+
+1. Directories passed via `addDataSearchPath()`
+2. Check path specified by configuration parameter with "_HINT" suffix (name of environment variable).
+3. Check path specified by configuration parameter (name of environment variable).
+   If parameter value is not empty and nothing is found then stop searching.
+4. Detects build/install path based on:
+   a. current working directory (CWD)
+   b. and/or binary module location (opencv_core/opencv_world, doesn't work with static linkage)
+5. Scan `<source>/{,data}` directories if build directory is detected or the current directory is in source tree.
+6. Scan `<install>/share/OpenCV` directory if install directory is detected.
+
+@param relative_path Relative path to data file
+@param required Specify "file not found" handling.
+       If true, function prints information message and raises cv::Exception.
+       If false, function returns empty result
+@param configuration_parameter specify configuration parameter name. Default NULL value means "OPENCV_DATA_PATH".
+@return Returns path (absolute or relative to the current directory) or empty string if file is not found
+
+@note Implementation is not thread-safe.
+*/
+CV_EXPORTS
+cv::String findDataFile(const cv::String& relative_path, bool required = true,
+                        const char* configuration_parameter = NULL);
+
+/** @overload
+@param relative_path Relative path to data file
+@param configuration_parameter specify configuration parameter name. Default NULL value means "OPENCV_DATA_PATH".
+@param search_paths override addDataSearchPath() settings.
+@param subdir_paths override addDataSearchSubDirectory() settings.
+@return Returns path (absolute or relative to the current directory) or empty string if file is not found
+
+@note Implementation is not thread-safe.
+*/
+CV_EXPORTS
+cv::String findDataFile(const cv::String& relative_path,
+                        const char* configuration_parameter,
+                        const std::vector<String>* search_paths,
+                        const std::vector<String>* subdir_paths);
+
+/** @brief Override default search data path by adding new search location
+
+Use this only to override default behavior
+Passed paths are used in LIFO order.
+
+@param path Path to used samples data
+
+@note Implementation is not thread-safe.
+*/
+CV_EXPORTS void addDataSearchPath(const cv::String& path);
+
+/** @brief Append default search data sub directory
+
+General usage is to add OpenCV modules name (`<opencv_contrib>/modules/<name>/data` -> `modules/<name>/data` + `<name>/data`).
+Passed subdirectories are used in LIFO order.
+
+@param subdir samples data sub directory
+
+@note Implementation is not thread-safe.
+*/
+CV_EXPORTS void addDataSearchSubDirectory(const cv::String& subdir);
+
+//! @}
+
+} // namespace utils
+} // namespace cv
+
 //! @endcond
 
 #endif // OPENCV_CORE_PRIVATE_HPP

modules/core/include/opencv2/core/utility.hpp

@@ -1274,8 +1274,75 @@ enum FLAGS
 CV_EXPORTS void       setFlags(FLAGS modeFlags);
 static inline void    setFlags(int modeFlags) { setFlags((FLAGS)modeFlags); }
 CV_EXPORTS FLAGS      getFlags();
+
+} // namespace instr
+
+
+namespace samples {
+
+//! @addtogroup core_utils_samples
+// This section describes utility functions for OpenCV samples.
+//
+// @note Implementation of these utilities is not thread-safe.
+//
+//! @{
+
+/** @brief Try to find requested data file
+
+Search directories:
+
+1. Directories passed via `addSamplesDataSearchPath()`
+2. OPENCV_SAMPLES_DATA_PATH_HINT environment variable
+3. OPENCV_SAMPLES_DATA_PATH environment variable
+   If parameter value is not empty and nothing is found then stop searching.
+4. Detects build/install path based on:
+   a. current working directory (CWD)
+   b. and/or binary module location (opencv_core/opencv_world, doesn't work with static linkage)
+5. Scan `<source>/{,data,samples/data}` directories if build directory is detected or the current directory is in source tree.
+6. Scan `<install>/share/OpenCV` directory if install directory is detected.
+
+@see cv::utils::findDataFile
+
+@param relative_path Relative path to data file
+@param required Specify "file not found" handling.
+       If true, function prints information message and raises cv::Exception.
+       If false, function returns empty result
+@param silentMode Disables messages
+@return Returns path (absolute or relative to the current directory) or empty string if file is not found
+*/
+CV_EXPORTS_W cv::String findFile(const cv::String& relative_path, bool required = true, bool silentMode = false);
+
+CV_EXPORTS_W cv::String findFileOrKeep(const cv::String& relative_path, bool silentMode = false);
+
+inline cv::String findFileOrKeep(const cv::String& relative_path, bool silentMode)
+{
+    cv::String res = findFile(relative_path, false, silentMode);
+    if (res.empty())
+        return relative_path;
+    return res;
 }
 
+/** @brief Override search data path by adding new search location
+
+Use this only to override default behavior
+Passed paths are used in LIFO order.
+
+@param path Path to used samples data
+*/
+CV_EXPORTS_W void addSamplesDataSearchPath(const cv::String& path);
+
+/** @brief Append samples search data sub directory
+
+General usage is to add OpenCV modules name (`<opencv_contrib>/modules/<name>/samples/data` -> `<name>/samples/data` + `modules/<name>/samples/data`).
+Passed subdirectories are used in LIFO order.
+
+@param subdir samples data sub directory
+*/
+CV_EXPORTS_W void addSamplesDataSearchSubDirectory(const cv::String& subdir);
+
+//! @}
+} // namespace samples
+
 namespace utils {
 
 CV_EXPORTS int getThreadID();

modules/core/include/opencv2/core/utils/filesystem.hpp

@@ -16,6 +16,13 @@ CV_EXPORTS void remove_all(const cv::String& path);
 
 CV_EXPORTS cv::String getcwd();
 
+/** @brief Converts path p to a canonical absolute path
+ * Symlinks are processed if there is support for them on running platform.
+ *
+ * @param path input path. Target file/directory should exist.
+ */
+CV_EXPORTS cv::String canonical(const cv::String& path);
+
 /** Join path components */
 CV_EXPORTS cv::String join(const cv::String& base, const cv::String& path);
 

modules/core/src/utils/filesystem.cpp

@@ -85,6 +85,20 @@ cv::String join(const cv::String& base, const cv::String& path)
 
 #if OPENCV_HAVE_FILESYSTEM_SUPPORT
 
+cv::String canonical(const cv::String& path)
+{
+#ifdef _WIN32
+    const char* result = _fullpath(NULL, path.c_str(), 0);
+#else
+    const char* result = realpath(path.c_str(), NULL);
+#endif
+    if (result)
+        return cv::String(result);
+    // no error handling, just return input
+    return path;
+}
+
+
 bool exists(const cv::String& path)
 {
     CV_INSTRUMENT_REGION();
@@ -543,11 +557,12 @@ cv::String getCacheDirectory(const char* sub_directory_name, const char* configu
 
 #else
 #define NOT_IMPLEMENTED CV_Error(Error::StsNotImplemented, "");
-CV_EXPORTS bool exists(const cv::String& /*path*/) { NOT_IMPLEMENTED }
-CV_EXPORTS void remove_all(const cv::String& /*path*/) { NOT_IMPLEMENTED }
-CV_EXPORTS bool createDirectory(const cv::String& /*path*/) { NOT_IMPLEMENTED }
-CV_EXPORTS bool createDirectories(const cv::String& /*path*/) { NOT_IMPLEMENTED }
-CV_EXPORTS cv::String getCacheDirectory(const char* /*sub_directory_name*/, const char* /*configuration_name = NULL*/) { NOT_IMPLEMENTED }
+cv::String canonical(const cv::String& /*path*/) { NOT_IMPLEMENTED }
+bool exists(const cv::String& /*path*/) { NOT_IMPLEMENTED }
+void remove_all(const cv::String& /*path*/) { NOT_IMPLEMENTED }
+bool createDirectory(const cv::String& /*path*/) { NOT_IMPLEMENTED }
+bool createDirectories(const cv::String& /*path*/) { NOT_IMPLEMENTED }
+cv::String getCacheDirectory(const char* /*sub_directory_name*/, const char* /*configuration_name = NULL*/) { NOT_IMPLEMENTED }
 #undef NOT_IMPLEMENTED
 #endif // OPENCV_HAVE_FILESYSTEM_SUPPORT
 

modules/core/src/utils/samples.cpp

+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+#include "../precomp.hpp"
+
+#include <vector>
+
+#include <opencv2/core/utils/logger.defines.hpp>
+#undef CV_LOG_STRIP_LEVEL
+#define CV_LOG_STRIP_LEVEL CV_LOG_LEVEL_VERBOSE + 1
+#include "opencv2/core/utils/logger.hpp"
+#include "opencv2/core/utils/filesystem.hpp"
+
+namespace cv { namespace samples {
+
+static cv::Ptr< std::vector<cv::String> > g_data_search_path;
+static cv::Ptr< std::vector<cv::String> > g_data_search_subdir;
+
+static std::vector<cv::String>& _getDataSearchPath()
+{
+    if (g_data_search_path.empty())
+        g_data_search_path.reset(new std::vector<cv::String>());
+    return *(g_data_search_path.get());
+}
+
+static std::vector<cv::String>& _getDataSearchSubDirectory()
+{
+    if (g_data_search_subdir.empty())
+    {
+        g_data_search_subdir.reset(new std::vector<cv::String>());
+        g_data_search_subdir->push_back("samples/data");
+        g_data_search_subdir->push_back("data");
+        g_data_search_subdir->push_back("");
+    }
+    return *(g_data_search_subdir.get());
+}
+
+
+CV_EXPORTS void addSamplesDataSearchPath(const cv::String& path)
+{
+    if (utils::fs::isDirectory(path))
+        _getDataSearchPath().push_back(path);
+}
+CV_EXPORTS void addSamplesDataSearchSubDirectory(const cv::String& subdir)
+{
+    _getDataSearchSubDirectory().push_back(subdir);
+}
+
+cv::String findFile(const cv::String& relative_path, bool required, bool silentMode)
+{
+    CV_LOG_DEBUG(NULL, cv::format("cv::samples::findFile('%s', %s)", relative_path.c_str(), required ? "true" : "false"));
+    cv::String result = cv::utils::findDataFile(relative_path,
+                                                "OPENCV_SAMPLES_DATA_PATH",
+                                                &_getDataSearchPath(),
+                                                &_getDataSearchSubDirectory());
+    if (result != relative_path && !silentMode)
+    {
+        CV_LOG_WARNING(NULL, "cv::samples::findFile('" << relative_path << "') => '" << result << "'");
+    }
+    if (result.empty() && required)
+        CV_Error(cv::Error::StsError, cv::format("OpenCV samples: Can't find required data file: %s", relative_path.c_str()));
+    return result;
+}
+
+
+}} // namespace

modules/core/test/test_utils.cpp

@@ -2,6 +2,7 @@
 // It is subject to the license terms in the LICENSE file found in the top-level directory
 // of this distribution and at http://opencv.org/license.html.
 #include "test_precomp.hpp"
+#include "opencv2/core/utils/logger.hpp"
 
 namespace opencv_test { namespace {
 
@@ -283,4 +284,21 @@ TEST(CommandLineParser, testScalar)
     EXPECT_EQ(parser.get<Scalar>("s5"), Scalar(5, -4, 3, 2));
 }
 
+TEST(Samples, findFile)
+{
+    cv::utils::logging::LogLevel prev = cv::utils::logging::setLogLevel(cv::utils::logging::LOG_LEVEL_VERBOSE);
+    cv::String path;
+    ASSERT_NO_THROW(path = samples::findFile("lena.jpg", false));
+    EXPECT_NE(std::string(), path.c_str());
+    cv::utils::logging::setLogLevel(prev);
+}
+
+TEST(Samples, findFile_missing)
+{
+    cv::utils::logging::LogLevel prev = cv::utils::logging::setLogLevel(cv::utils::logging::LOG_LEVEL_VERBOSE);
+    cv::String path;
+    ASSERT_ANY_THROW(path = samples::findFile("non-existed.file", true));
+    cv::utils::logging::setLogLevel(prev);
+}
+
 }} // namespace

modules/python/test/test_misc.py

@@ -84,6 +84,23 @@ class Arguments(NewOpenCVTests):
         self.assertEqual(res4, "InputArrayOfArrays: empty()=false kind=0x00050000 flags=0x01050000 total(-1)=3 dims(-1)=1 size(-1)=3x1 type(0)=CV_32FC2 dims(0)=2 size(0)=3x1 type(0)=CV_32FC2")
 
 
+class SamplesFindFile(NewOpenCVTests):
+
+    def test_ExistedFile(self):
+        res = cv.samples.findFile('lena.jpg', False)
+        self.assertNotEqual(res, '')
+
+    def test_MissingFile(self):
+        res = cv.samples.findFile('non_existed.file', False)
+        self.assertEqual(res, '')
+
+    def test_MissingFileException(self):
+        try:
+            res = cv.samples.findFile('non_existed.file', True)
+            self.assertEqual("Dead code", 0)
+        except cv.error as _e:
+            pass
+
 
 if __name__ == '__main__':
     NewOpenCVTests.bootstrap()